PREP_PROCESS_VAR and PREP_PROCESS_VAR_XML

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.
Format: AE name, script literal or script variable

Key

The filter for the Key column .
Format: script literal or script variable
You can use a maximum of 64 characters.
Default value: "*"

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.
Format: script literal or script variable
Format for Variable object XML: XPath (format: string)
You can use a maximum of 64 characters.
Default 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.
Format: script literal, script variable or number without inverted commas.

Wildcard characters must not be used.

Allowed values:
Static variabless: "1" to "5"
Static variable XML: "1"
Dynamic variables: "1" to n

If you want to filter for the value alone, you must also set the previous comma.
For example: 

: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

:CLOSE_PROCESS

Discards an unnecessary data sequence.

:PROCESS... :TERM_PROCESS... :ENDPROCESS

Loop for the line-by-line processing of a data sequence such as a sequential file or a command result.

GET_PROCESS_LINE

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