Script Functions: Use selection criteria in order to retrieve a list of Variable object values and provide the result for further processing in the form of an internal list (data sequence).
Syntax
PREP_PROCESS_VAR (Variable [,Key [,Value [, Column]]])
PREP_PROCESS_VAR_XML (Variable, Key ,Value)
|
Syntax |
Description/Format |
|---|---|
|
Variable |
The name of the Variable object that should be processed. |
|
Key |
The filter for the Key column
. In dynamic variables, the Key column corresponds to the first basic column (value column). The result column is build only after retrieving the variable values. The wildcard characters "*" and "?" can be used. "*" stands for any character, "?" for exactly one. |
|
Value |
the filter for the value. The wildcard characters "*" and "?" can be used. "*" stands for any character, "?" for exactly one. The format for the Variable object XML has to be the same for both script functions. |
| Column |
The filter for a Variable object's particular value column. Wildcard characters must not be used. Allowed values:
If you want to filter for the value alone, you must also set the previous comma.
:SET &HND# = PREP_PROCESS_VAR("DB.MAINTENANCE",,"CLIENT", 1) |
|
Return code |
|---|
|
Reference to the data sequence of the Variable object. |
Comments
These script functions read the values of a Variable object. You can limit the values that should be read by using the optional parameters Key and Value. You can also use the wildcard characters "*" and "?" in these parameters. The input is case sensitive.
For the script function PREP_POCESS_VAR_XML all three parameters have to be specified.
Value refers to the content of a value column. Column determines the number of the particular value column that should be searched. The first value column is automatically used if you do not define a column. Static variables include 5 value columns. The column number of dynamic variables is not limited and depends on the data source and the settings that are defined in the Variable object.
The script function PREP_PROCESS_VAR_XML may only be used with the Variable object XML, which provides only one value column.
The parameter Column can only be used in combination with Value. Any column specification is invalid, if you do not specify the filter Value.
You cannot select particular columns. Each selected variable entry, that is returned, includes the values of all columns (including the Key or result column).
Note that you cannot use wildcard characters in Value if the variable is a"Number" data type. This script function either returns all entries or those that show exactly the specified value.
Using an empty string ("") as a filter specification has the same effect as using "*". All values are returned.
All the Variable object's entries are used if you do not specify Key and Value .
The return code of this script function is a data sequence reference. It is passed on to the script statements :PROCESS and :ENDPROCESS as a start parameter. If you use it in combination with the script function GET_PROCESS_LINE, you can now access each of the Variable object's individual lines.
No error message is output if the Variable object does not include the searched values. The data sequence that is defined between :PROCESS and :ENDPROCESS is not processed in this case.
Names of VARA objects that include a variable must be specified in quotation marks. Otherwise, an error message is displayed.
No new value can be assigned to the script variable that includes the data sequence reference. The data sequence must be discarded by using the script statement CLOSE_PROCESS, and then the variable can be re-used.
Note for SQL variables (SQL, SQLI): The number of lines that are returned with the setting
SQLVAR_MAX_ROWS
(UC_SYSTEM_SETTINGS) is limited. For example, when you specify the value 1000, the system will only return the first 1000 lines.
You can limit the returned lines with the
Key
but not with the specified
Value
. This means that when you define a filter for a certain
Value
in combination with the script element PREP_PROCESS_VAR, the system will only search for this value within the defined maximum number of lines. However, when you define a
Key
, it will be passed on to the database and used for the query. Therefore, Automic recommends filtering by using the
Key
instead of the
Value
when you have tables that include many entries as otherwise, you might risk that no entries are returned.
Examples
The following Variable object is used for the examples that are shown below:
Example 1 retrieves all values and within the process loop, it prints it to the activation protocol using the script statement :PRINT.
:SET &HND#=PREP_PROCESS_VAR(DATABASE_MAINTENANCE)
:PROCESS &HND#
: SET &VK#
= GET_PROCESS_LINE(&HND#,1)
: SET &VALUE# = GET_PROCESS_LINE(&HND#,2)
: PRINT "&VK# &VALUE#"
:ENDPROCESS
:CLOSE_PROCESS &HND#
Example 2 only reads the entries whose keys start with "client".
:SET &HND#=PREP_PROCESS_VAR(DATABASE_MAINTENANCE,"Client*")
:PROCESS &HND#
: SET &VK#
= GET_PROCESS_LINE(&HND#,1)
: SET &VALUE# = GET_PROCESS_LINE(&HND#,2)
: PRINT "&VK# &VALUE#"
:ENDPROCESS
:CLOSE_PROCESS &HND#
Example for using PREP_PROCESS_VAR_XML. In this example, the value of the data sequence lines represented by the script variables &VALUE# and &GB# are read, which in turn read out the values "A/B" of the key called "KEY01" of the Variable object XML, called "VARA.XML":
:SET &HND# = PREP_PROCESS_VAR_XML(VARA.XML, "KEY01", "A/B")
:PROCESS &HND#
: SET &GB# = GET_PROCESS_LINE(&HND#,1)
: SET &VALUE# = GET_PROCESS_LINE(&HND#,2)
: PRINT "&GB# &VALUE#"
:ENDPROCESS
See also:
| Script element | Description |
|---|---|
|
Discards an unnecessary data sequence. |
|
|
Loop for the line-by-line processing of a data sequence such as a sequential file or a command result. |
|
|
This is used to retrieve content from the current line of a data sequence. |
Script Elements - Data Sequences
About Scripts
Script Elements - Alphabetical Listing
Script Elements - Ordered by Function