Verbs and Built-in Functions › &SETVARS

&SETVARS

Extracts named keywords and associated data from a data string.

&SETVARS [ PREFIX=ppp ]
         [ MODFLD={ NO | YES } ]
         [ ERROR={ ABORT | CONTINUE } ]
         [ DUPLICATE={ YES | NO } ]
         [ CONCAT={ YES | NO } ]
         [ KEYWORDS=( list-of-keywords ) ]
         [ PARMS | ARGS [ RANGE=( start,end ) ] |
           VARS=prefix* [ RANGE=( start,end ) ] |
           DATA=value ]

&SETVARS allows a procedure to analyze either a data string or a set of variables, to extract named keywords and their associated data. &SETVARS takes data in the form keyword=data, keyword=data,…, creates variables for each keyword, and assigns the corresponding data to it. The variable names created are (by default) the name of the keyword. However, a prefix may be specified for the names.

Operands:

PREFIX=ppp

An optional 1- to 8-character prefix for the generated variable names. If PREFIX is not specified, the variable created is named the same as the corresponding keyword.

If you specify a numeric prefix, all keywords must be all-numeric.

MODFLD={ NO | YES }

When set to YES, the MODIFIED attribute is reset for all existing variables, and the MODFLD attribute is set on generated output variables.

ERROR={ ABORT | CONTINUE }

Indicates what action is to be taken if an error is found during processing of input data or variables.

ABORT indicates that the procedure is to abort. CONTINUE causes &RETCODE to be set to 8, &SYSMSG to be set to an error message, and creation of variables to cease at the variable in error.

Any syntax errors always result in the procedure aborting, regardless of the setting of the ERROR operand.

DUPLICATE={ YES | NO})

Indicates whether duplicate keywords are allowed. The default, YES, indicates that duplicates are allowed.

CONCAT={ YES | NO }

When CONCAT=YES is specified, all the input data specified by the PARMS, ARGS, and VARS= operands is concatenated together (without blanks), and treated as if the entire string had been specified on the DATA= operand.

CONCAT=YES cannot be specified when DATA= is specified.

KEYWORDS=(list-of-keywords)

This is an optional list of valid keywords for input. If specified, all keywords must be found in the list. Any listed keywords (prefixed by the optional prefix) have the associated variable deleted before processing.

Each keyword must be a valid part of a variable name and, if the specified prefix is numeric, then the keywords must all be numeric.

PARMS

This is the default operand meaning that &1, &2, &3, from 1 to &PARMCNT, are used (that is, the parameters supplied to the procedure).

This is similar to ARGS RANGE=(1,&PARMCNT), except that, if there are no parameters, then there are no errors.

ARGS [ RANGE=( start,end ) ]

Indicates that numeric variables in the range are to be used as input.

VARS=prefix* [ RANGE=( start,end ) ]

Indicates that nominated prefixed variables are to be used as input.

Note: The previous three options mean that a set of variables is used as input. The range is processed as follows:

• Null variables are ignored.
• Each non-null variable must be in the format: keyword=value, where the keyword and the equal sign are required and the value (which may be null) is assigned to the prefix keyword variable, without modification.
• Duplicate and keywords list checks are done as requested.

DATA=value

This optional operand can contain input data in the following formats:

kwd=value

kwd='value'

kwd=“value”

kwd=

or any combination of the above.

If quotes are used then they must be validly paired, and are stripped. Any double quote is singled up in a target variable, and blanks (real ones) is placed in a variable. Otherwise data is delimited on blanks (real or embedded).

Example 1:

If your procedure is executed as follows:

EXEC MYPROC PARM1='VALUE1 VALUE2' PARM2=OPTION

the parameter string could be analyzed using &SETVARS as follows:

&SETVARS PREFIX=AA DATA=&ALLPARMS

This results in the variable &AAPARM1 containing VALUE1 VALUE2, and &AAPARM2 containing OPTION.

Example 2:

If your procedure is executed as follows:

EXEC MYPROC PARM1=VALUE PARM2=OPTION

the parameter string is analyzed using &SETVARS as follows:

&SETVARS PREFIX=AA

This results in the variable &AAPARM1 containing VALUE and &AAPARM2 containing OPTION.

Notes:

The DATA= option allows you to easily pass data to a procedure and parse it into variables, including embedded blanks.

The ERROR=CONTINUE option allows you to keep control even if the data is incorrect.