Validate Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Container
Alternate Context:	Pick or Thing
Fields Finalized?	Yes
Where Used:	Components, Things
Procedure Use:	"validate" type, "pick" context

The Validate script utilizes the following special symbols:

valid	(Number) Entry: Assumes the pre-requisite is not satisfied with a value of zero. Exit: Indicates whether the pre-requisite is satisfied (non-zero) or not satisfied (zero).
message	(String) Entry: Contains the default message text if the pre-requisite is not satisfied. Exit: Contains the final message text to display if the pre-requisite is not satisfied. The text may contain encoding.
ispick	(Number) Entry: Indicates whether the pre-requisite is being applied to a pick (non-zero) or thing (zero). Exit: Ignored.

Description

The Validate script is exclusively used within pre-requisite tests. The script verifies that a specific pick or thing satisfies a particular pre-requisite relative to its container. If the requirement is not satisfied, then the object is designated as invalid. If the object is a pick that has already been added to the portfolio, the specified message is displayed within the validation report for the actor.

The pre-requisite test can be anything you want, provided only the object and the container are considered by the test. The requirement is always either satisfied or not satisfied. This is determined by the "valid" special symbol. The symbol starts out as zero, indicating that the requirement is not satisfied. At any point during the script, you can set the symbol to non-zero, thereby indicating that the requirement is satisfied. The only value that matters is the final value when the script ends, where a non-zero value indicates the pre-requisite is satisfied.

Each pre-requisite is associated with a particular thing. If a pre-requisite is defined for a component, then it is inherited by the things which derive from that component. The pre-requisites are checked for every thing when it is presented as an option for the user to add via a table or chooser. If one or more pre-requisites are not satisfied, the thing is designated as invalid and the failed requirements are shown in the description information for the thing. If the thing is added by the user in spite of the failed pre-requisites, then all the pre-requisites are applied to the pick at the end of every evaluation cycle.

When invoked, a Validate script starts with the container as its initial context. If the object is a pick, the container is the one the pick resides within. If the object is a thing, the container is the prospective container to which the thing will potentially be added. The reason for the container as the initial context is that the pre-requisite test is defined on the thing. Consequently, the thing will know about itself and will typically be looking to verify that the prospective container satisfies the needs of the thing.

For those situations where you also need to access characteristics of the pick or thing, the Validate script provides an alternate context. This context will always be the pick or thing, as appropriate. You can use the "ispick" special symbol to determine whether the pre-requisite is being applied to a pick or a thing. After that, you can use the "altpick" or "altthing" context to access the object.

NOTE! The use of pre-requisites with a Validate script is generally only needed in more complex situations. The "pickreq" and "exprreq" mechanisms are much simpler to use and maintain, and they should cover 90% of the situations where you need to establish a pre-requisite.

Example

A simple pre-requisite might establish a dependency on an attribute value being at least equal to some number. The example below shows a Validate script that tests whether the container has a child pick (strength) that has a final value of at least 13.

if (child[attrStr].field[trtFinal].value >= 13) then
  @valid = 1
  endif