PREP_PROCESS_VAR and PREP_PROCESS_VAR_XML

Use the PREP_PROCESS_VAR script function to retrieve a list of VARA object values. For XML VARA objects, you can also use PREP_PROCESS_VAR_XML. The script functions let you filter by key and value. The script functions return a reference to a data sequence that you can use for further processing by assigning the return code to the :PROCESS script statement. Use the GET_PROCESS_LINE script function to access a particular line in the VARA object.

More Information

Notes:

You cannot assign a new value to the script variable that contains the reference to the data sequence. Use :CLOSE_PROCESS to discard the existing data sequence, and then assign a new value.
No error message is displayed if the data sequence does not contain the indicated content. In this case, the data sequence that is defined between :PROCESS and :ENDPROCESS is not processed.

SQL and SQLI VARA Objects with Many Entries

The number of lines returned can be limited in your system settings. When you filter for a particular Value with PREP_PROCESS_VAR, the system will only search for the value within the defined maximum number of lines.

More Information:

Tip: Use the Key parameter in PREP_PROCESS_VAR to limit the number of lines returned when the VARA object has many entries. The Key value is passed to the database and used for the query.

Example

Your system is configured to limit the returned number of lines: SQLVAR_MAX_ROWS is set to 1000. Your SQL VARA object contains over 1000 lines and you are looking for a particular value that can occur in any of the lines. Because of the limitation, PREP_PROCESS_VAR only returns the first 1000 lines. You may not find all occurrences of the value. Specify the Key parameter to reduce the number of lines retrieved, and search those lines only for the value.

Syntax

PREP_PROCESS_VAR (VARA object[,Key [,Value [, Column]]])
PREP_PROCESS_VAR_XML (VARA object, Key, Value)

Parameters

PREP_PROCESS_VAR or PREP_PROCESS_VAR_XML
Retrieves a list of values from any type of VARA object, or from an XML VARA object, respectively
VARA object
Name of the VARA object
Format: AE name, script literal or script variable
Important! If the name of the VARA object includes a variable, specify the name in quotation marks. An error will occur if you do not use quotation marks.
Key
(Optional) Filters for values in the Key column
Format: script literal or script variable
Maximum number of characters: 200
Default value: *
Notes:
- Use the wildcard character * to stand for any number of characters, or ? for a single character in a filter.
- The filter is case sensitive.
- In dynamic VARA objects, the Key column corresponds to the first column (value column). The result column is built dynamically when the content is read.
Value
(Optional) Filters for a particular value
Format:
- (XML VARA objects only) XPath (string format)
  The format is the same for both PREP_PROCESS_VAR and PREP_PROCESS_VAR_XML.
- (Other types of VARA objects) Script literal or script variable
Maximum number of characters: 1024
Default value: *
Notes:
- Use the wildcard character * to stand for any number of characters, or ? for a single character, for data types other than number.
- If the value is a number data type, do not use wildcards. The script function returns all entries (no filter), or entries that show exactly the specified value.
- The filter is case sensitive.
Column
Filters for a particular column in a VARA object
Format: script literal, script variable or number without quotation marks
Important!
- You must specify the Value parameter if you want to specify a column.
- Do not use wildcard characters.
Notes:
- If you do not specify a column, the script retrieves the value of the first column.
- Set the comma before Value when you want to filter only for the value, without specifying a Key.
- Columns are numbered. Static VARA objects contain 5 columns. Dynamic VARA objects can contain any number of columns, depending on the data source and settings of the VARA object.
- The Column parameter is used for filtering, but the whole row is retrieved when there is a match.
  Tip: Use GET_PROCESS_LINE to retrieve a specific column only.
Allowed values:
- (Static VARA objects) 1 to 5
- (Static XML VARA objects) 1
  Note: XML VARA objects provide a single column of values, so this parameter can only be 1.
- (Dynamic VARA objects) 1 to n

Important! When you use PREP_PROCESS_VAR to access values in an XML VARA object, specify all three parameters (Key, Value, and Column).

Notes:

Specifying an empty string has the same effect as specifying *, and returns all values.
If you do not specify the Key and Value, the script function returns all entries in the VARA object.

Examples

A VARA object that is called DATABASE_MAINTENANCE contains the following entries, in 2 columns (Key and Value1):

Key: ARCHIVING
Value1: Y
Key: REORGANIZING
Value1: N
Key: UNLOADING
Value1: N
Key: CLIENT
Value1: 3

The following script retrieves all values in the VARA object. The script prints the values from both columns in the activation report.

: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#

The activation report would look like this:

2018-01-31 11:28:59 - U0020408 ARCHIVING Y
2018-01-31 11:28:59 - U0020408 REORGANIZING N
2018-01-31 11:28:59 - U0020408 UNLOADING N
2018-01-31 11:28:59 - U0020408 CLIENT 3

The following script only retrieves entries where the key starts 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#

The activation report would only include the following line:

2018-01-31 11:28:59 - U0020408 CLIENT 3

The following example retrieves values from an XML VARA object that is called VARA.XML. The specified XPath filters for elements in the 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