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.

Syntax

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

PREP_PROCESS_VAR_XML (VARA object, Key, Value)

Parameters

Parameter	Description	Format	Allowed Values	Default Value
VARA object	Defines the name of the VARA object. 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.	AE name, script literal or script variable	n.a.	n.a.
Key	(Optional) Filters for values in the Key column. 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.	Script literal or script variable (Maximum 200 characters)	n.a.	*
Value	(Optional) Filters for a particular 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.	(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 1024 characters)	n.a.	*
Column	Filters for a particular column in a VARA object. 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.	Script literal, script variable or number without quotation marks	(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	n.a.

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.

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.

Important Considerations

• 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.
• Important! When you use PREP_PROCESS_VAR to access values in an XML VARA object, specify all three parameters (Key, Value, and Column).
• 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.

Return Codes

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.

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

Related Topics

• User-Defined VARA Objects
• XML VARA Objects
• UC_SYSTEM_SETTINGS - Systemwide Settings
• SQLVAR_MAX_ROWS
• SQL VARA Objects
• SQLI VARA Objects

See also:

• :PROCESS... :TERM_PROCESS... :ENDPROCESS
• GET_PROCESS_LINE