VARSET – Set a Workload Automation Programming Language variable
Use the VARSET
command to set a Workload Automation Programming Language variable, work with it,
and save it in a JCL variable table in HCL Workload Automation for Z.
VARSET variable = <expression>
orVARSET variable [VALUE(value)]
[USRF(user-field-name)]
[@V(input-variable-name)]
[SYMBOL(system-symbol-name)]
[OBJECT(<object>)]
[MISSING(ERROR|FAIL|NULL|ASIS)]
[ENVATTR(major,minor,item)]
[ADDWORD(string)]
[APPEND(string)]
[BEFORE|BEFOREX(string)]
[CLEAN(n[,characters])]
[CONCAT(string)]
[LEFT(n)]
[RIGHT(n)]
[SUBSTR(start[,length])]
[WORD(n,[ALL|BASIC|COMMA|NONE|PERIOD|SPACE],[<other>])]
[UPPER(YES|NO)]
[DELTA(n)]
[TABLE(table)]
[SAVE(YES|NO)]
[SETUP(YES|NO|PROMPT)]
[OBJECT(<file-object>)]
[CURSOR(<rowvar>,<colvar>)]
[POSITION([+|-]row|=,[+|-]col|=,[+|-]end)]
The VARSET
command can be either a simple REXX style assignment or a
keyword-driven process. You can also use the alternative command name
SETVAR
.
The REXX style is identified by an equal sign (=) after the variable name. The characters following the equal sign (=) must be a standard REXX expression and can use REXX functions. For more details about the REXX expressions and available functions, see the TSO/E REXX Reference manual.
The first keyword of each VARSET
command must be the variable to
which the command refers. All other keywords are optional. A VARSET
command without optional keywords, sets the variable to a null value. If the variable was
already set or referenced in the Workload Automation Programming Language statements, that value
is kept and modified by any following keyword.
- Data sources
VALUE(value)
- Sets the value of the variable within Workload Automation Programming Language. The
VALUE
keyword alone does not update any JCL variable table.For example,
VARSET MYVAR VALUE(Hello World)
causes any subsequent references to!MYVAR
to be replaced withHello World
.The
VALUE
keyword can contain a reference to another or the same variable, so that loads that variable at that specific point in your Workload Automation Programming Language statements.For example,
VARSET MYADID VALUE(!OADID)
causesMYADID
to contain the name of the currently running application. USRF(user-field-name)
-
Sets the variable to the value of an operation user field with the same name, if attached to the operation running the Workload Automation Programming Language job. Workload Automation Programming Language first searches for a match using the same case specified in
USRF
, then looks for a match regardless of the case. TheUSRF
keyword is not available for the versions of HCL Workload Automation for Z without the user field functionality. @V(input-variable-name)
-
The
@V
keyword allows you to specify another Workload Automation Programming Language variable and provide it with a value. Because the content of this keyword is the name of the variable, you do not need to specify the variable prefix (such as the exclamation mark !), instead you can use variable names to provide all or part of the name, allowing subscripting to be performed.For example, in the command
VARSET JOB VARIABLE(@MYOBJ-ADOP-!X-ADOPJN)
the variable!X
is used to provide the segment sequence number in an object variable, allowing all operations to be looped through. SYMBOL(system-symbol-name)
- Sets the variable to the value of a system symbol. If a symbol with that name is not found, an empty value is returned.
OBJECT(<object>)
- Indicates a file object, such as the one created with the
READ
command, to be used as input to set a variable. Omit the at sign (@) because only object names are allowed. The object must already exist and have sequential file type. Complex objects, such as those generated byLIST
orSELECT
command, are not allowed.You can use the
OBJECT
keyword together with thePOSITION
keyword, and optionally with theCURSOR
keyword. MISSING(ERROR|FAIL|NULL|ASIS)
- Determines what to do if a field specified in the
USRF
keyword is not attached to the current operation. TheMISSING
keyword must be specified after aUSRF
keyword. If you specify it before, theVARSET
command fails.Valid values are:ERROR
- Workload Automation Programming Language issues an error (RC=8) if the user field is not found.
FAIL
- Workload Automation Programming Language fails (RC=12) if the user field is not found.
NULL
- The variable is set to a null value if the user field is not found.
ASIS
- The value is left unchanged if the user field is not found. The
VALUE
keyword sets a default value, and theUSRF
keyword requires only that you set the user field on the operation if you want to override the default behavior (this is the default behavior for Workload Automation Programming Language).Note:ERROR
issues RC=8, which by default allows the following commands to be run;FAIL
issues RC=12, which by default stops processing further commands.For example, in the command
VARSET USERNAME VALUE(RANA) USRF(OVR_USERNAME)
, the variableUSERNAME
is set to RANA, unless the user has added a User Field to the running job namedOVR_USERNAME
. In this case, the value in the User Field is kept.In the command
VARSET USERNAME USRF(User Name) MISSING(FAIL)
, the variableUSERNAME
is set to the contents of a User Field namedUser Name
. If not found, the command fails.
ENVATTR(major,minor,item)
- Returns information about the running job environment. You can specify up to 3
levels of argument to identify the information that you require:
major
- The part of the environment from which the data is extracted. Valid values
are:
CMD
, for information about Workload Automation Programming Language commands.DD
, for information about DD statements in the running step.JCL
, for information about steps in the JCL.OPTIONS
, for values of a Workload Automation Programming LanguageOPTIONS
keyword.
minor
- The type of information you want, which varies depending on
major
. item
- Key information to identify the item from which you require
information.
For
CMD
, the item can be one of the following:- The label of the command.
- The absolute command number, for example 1 is the command in the current step.
- The relative command number, for example -1 is the command before the current command.
- Special command labels:
LAST_RC
- The previous command.
LAST_XRC
- The last command that was actually run.
MAX_RC
- The command that issued the highest return code.
MAX_RESP
- The command that issued the highest response code.
ForDD
the item can be one of the following:- A DD name. If the DD name has multiple data sets coded, a fourth
argument can be coded to identify the number of the DD statement. For
example,
ENVATTR(DD,DSNAME,MYDD,3)
refers to the 3rd data set on the MYDD concatenation. If omitted, the first DD statement for the DD name is returned. - Absolute DD number. For example, 1 is the first DD statement in the current step.
- Relative DD number. For example, -1 is the last DD statement in the current step.
ForJCL
, the item can be one of the following:PROCSTEP
orSTEPNAME.PROCSTEP
values tTo specify the step. If duplicates occur, the latest name is used.- Absolute step number. For example, 1 is the first step in the JCL.
- Relative step number. For example, -1 is the step before the current step, 0 is the current step.
- Special step labels:
LAST_RC
- The previous step.
LAST_XRC
- The last step that was actually run.
MAX_RC
- The step that issued the highest return code, or most recent ABEND.
For
OPTIONS
, there is noitem
value except when you setminor
toSPE
; in this case,item
can be the name of theSPE
.Valid combinations for ENVATTRThe valid combinations are listed in the following table:
Table 1. Valid combinations for ENVATTR
Major Minor Item Description CMD
#
no Number of commands run so far, including currently running command. CMD
ARGS
yes Argument of the identified command. CMD
LABEL
yes Label of the identified command. CMD
LEVEL
yes Message level of the identified command. CMD
NAME
yes Name of the identified command. CMD
RC
yes Return code or response code of identified command (whichever is highest). DD
#
no Number of named DD statements in the step. DD
#
yes Number of DD statements for the identified DD name. DD
DDNAME
yes DD name of the identified DD statement or concatenation. DD
DSNAME
yes Data set name of the identified DD statement. If the DD statement refers to a member in a library, this includes both the data set name and library name. DD
LIBRARY
yes If the identified DD statement refers to a member in a library, this is the data set portion of the name, without the member name. If this is an ordinary data set reference, this value is the same as DSNAME
.DD
MEMBER
yes If the identified DD statement refers to a member in a library, this is the member name. If this is an ordinary data set reference, this value is blank. JCL
#
no Number of steps in the job, including the currently running step. JCL
STEP
yes Fully qualified step name of the identified step. If this is a step in a proc, the step name is composed by the step calling the procedure and the step within the procedure that is running, separated by a period. For example, STEPNAME.PROCSTEP. If this is a step running directly within the job JCL, this value is only the single step name without period. JCL
STEPNAME
yes The name of the step calling the procedure, if this step is within a procedure. Otherwise, this value is blank. JCL
PROCSTEP
yes The name of the step actually running the program. JCL
RC
yes The return code of the step. JCL
PGM
yes The name of the program for the current step. JCL
PARM
yes The PARM value for the current step. OPTIONS
<keyword>
no The value of the specified OPTIONS
keyword.OPTIONS
SPE
yes Whether the SPE has been activated (Y or N).
- Text modifiers
ADDWORD(<string>)
- Adds the string of words, separated by blanks, to the end of the current value, if they do not already exist in the list.
AFTER(<string>)
- Returns the text following the specified string.
APPEND(<string>)
- Adds the contents of the keyword to the end of the current value, separated by a blank.
BEFORE|BEFOREX(<string>)
- Returns the text up to the first occurrence of the string. If the string is not
found, the whole text is returned. The
BEFOREX
keyword returns only the text before the string. If the string is not found, nothing is returned. This makes it possible to collect the text within delimiters.In the following example,MEM1
contains text even if only the left parenthesis(
is specified in the input variable, whileMEM1X
contains text if both the left and right parenthesis(
and)
are set in the input variable.VARSET MEM1 @V(FILE1) AFTER("(") BEFORE(")") VARSET MEM1X @V(FILE1) AFTER("(") BEFOREX(")")
CLEAN(n[,characters])]
-
Enables a set of cleanup actions to be performed upon the content at that point. Each action can be performed individually by selecting the action number, or together by adding the action numbers together. To perform the action upon other characters, specify them as a second argument. If you add actions together and also set a second argument, all the actions are applied.
- Action 1 – Strips leading characters from the string (the default is blanks). If multiple characters are specified, they are removed from the beginning of the string one at a time in the order specified.
- Action 2 – Strips trailing characters from the string (the default is blanks). If multiple characters are specified, they are deleted from the end of the string one at a time in the order specified.
- Action 4 – Equalizes blanks (the default is one blank). The second argument for this action is the number of blanks to equalize to.
- Action 8 – Deletes punctuation characters when followed by blanks (default . , ! and ?). The characters are removed instead of changing them to another character.
- Action 16 – Translates characters to blanks unconditionally, regardless of what follows them (default is comma).
- Action 32 – Removes specified characters unconditionally, regardless of what follows them. There is no default for this action, therefore a second argument must be specified.
The cleaning actions are designed to remove extraneous characters and rationalize the layout of fields.
CONCAT(<string>)
- Adds the contents of the keyword to the end of the current value, without any blank.
LEFT(n)
- Sets the n left most characters of the current variable value as the
new value of the variable.
For example,
VARSET MYPFX VALUE(!OADID) LEFT(4)
causesMYPFX
to contain the first 4 characters of the application name.You can use
LEFT
andRIGHT
together in the same statement to extract characters relative to the end of value of unknown length. For example,VARSET MYPFX VALUE(!OADID) RIGHT(4) LEFT(1)
causesMYPFX
to contain the 4th from last non-blank character of the application name. RIGHT(n)
- Sets the n right most non-blank characters of the current variable value as
the new value of the variable.
For example,
VARSET MYPFX VALUE(!OADID) RIGHT(4)
causesMYPFX
to contain the last 4 characters of the application name, regardless of how long the application name actually is.You can use
RIGHT
andLEFT
together in the same statement to extract characters relative to the end of value of unknown length. For example,VARSET MYPFX VALUE(!OADID) RIGHT(4) LEFT(1)
causesMYPFX
to contain the 4th from last non-blank character of the application name. SUBSTR(start[,length])
- Allows you to extract a specific portion of the current value of a variable, by
specifying the start position and optionally the length. For example,
VARSET MYBIT VALUE(!OADID) SUBSTR(2,1)
.If the length is omitted, the value is set to the remaining part of the current value from the start position onwards.
For example,
VARSET MYBIT VALUE(!OADID) SUBSTR(3)
setsMYBIT
to be the application name, minus the first 2 characters. WORD(n,[ALL|BASIC|COMMA|NONE|PERIOD|SPACE],[<other>])]
- Extracts individual words from a variable value. The number identifies which word
to extract.
For example,
VARSET MYVAR VALUE(The quick brown fox) WORD(2)
returnsquick
.Negative numbers extracts words from the end of the phrase. -1 identifies the last word, -2 the 2nd to last, and so on.
For example,
VARSET MYVAR VALUE(The quick brown fox) WORD(-2)
returnsbrown
.By default, words are considered to be space delimited, the optional second and third parameters can be used to specify alternative delimiters.
The second parameter can be one of the following:ALL
- Uses a space, comma, and period as delimiters.
BASIC
- Uses a space and comma as delimiters.
COMMA
- Uses a comma as delimiter.
NONE
- No predefined delimiters are used (the third parameter is used).
PERIOD
- Uses a period as delimiter.
SPACE
- Uses a space as delimiter.
The third keyword can be used to specify any additional characters. For example,
WORD(2,COMMA,;:)
looks for the second word delimited by comma, semi-colon and colon.WORD(3,,/)
looks for the third word delimited by a slash (/
).Consecutive delimiters without intervening characters return null words for their positions. For examples:
VARSET MYFIRST VALUE(A,,C,,E,F) WORD(1,COMMA)
returnsA
VARSET MY5TH VALUE(A,,C,,E,F) WORD(5,COMMA)
returnsE
VARSET MYLAST VALUE(A,,C,,E,F) WORD(-1,COMMA)
returnsF
UPPER(YES|NO)
- Forces the value into upper case. This is useful if the value will eventually be
used in something that requires upper case (for example, JCL), but the source of the
value cannot be depended upon to have forced upper case. For example, a Variable
table or User field.
UPPER(YES)
forces upper case;UPPER(NO)
leaves the value a sis. TheUPPER
keyword without arguments defaults toUPPER(YES)
.For example,
SETVAR USERNAME VALUE(RANA) USRF(OVR_USERNAME) UPPER
- Mathematical modifiers
DELTA(n)
- Takes the current value and adds n to it. The current value must be numeric
and n must be numeric, otherwise the command fails. The only exception is
when the variable is set to a null value, which is considered zero. This allows for
new counter variables to be self-initializing.You can use this keyword to increment variables within JCL variable tables. In the following example, the table
MYTABLE
is opened. Before theVARSET
command is run, the value ofRUNCOUNT
is substituted into theVALUE
keyword. Then, theVARSET
command adds 1 to the current value and saves it intoMYTABLE
. IfRUNCOUNT
does not already exist inMYTABLE
, theVARFAIL(NULL)
results in theVALUE
keyword containing a null value, which theDELTA
process considers as zero. The end result beingRUNCOUNT
contains 1 and is added toMYTABLE
.VARSUB SCAN(!) TABLE(MYTABLE) VARFAIL(NULL) VARSET RUNCOUNT VALUE(!RUNCOUNT) DELTA(1) SAVE(YES)
- Variable management
TABLE(table)
- Assigns a JCL Variable Table to a Workload Automation Programming Language variable, so
that it can be saved in a JCL Variable Table. If the variable has already been
referenced from a JCL Variable Table, the
TABLE
keyword is not needed. If a Workload Automation Programming Language variable is not assigned to a table name, it cannot be saved.In the following example,RUNCOUNT
could not exist inMYTABLE
, butVARFAIL(NULL)
causes the first table in the search sequence to be assigned as the source table name. You can, however, use theTABLE
keyword to override the name of the table from which the variable originally came, and save the value in a new table.VARSUB SCAN(!) TABLE(MYTABLE) VARFAIL(NULL) VARSET RUNCOUNT VALUE(!RUNCOUNT) DELTA(1) SAVE(YES)
SAVE(YES|NO)
- Determines if and when the variable is written to a JCL variable table:
YES
- The variable is written directly into the associated table at this point.
NO
- The variable is not written into the associated table, but could be written
later if a
VARSAVE
command is run by referencing the table associated to this variable.
If you specifySAVE
without argument,SAVE(YES)
is assumed.Note:- To set several variables in the same table, it is more effective to use a
subsequent
VARSAVE
command than usingSAVE
on everyVARSET
. - Variables do not need to already exist within a table. They are added to the table, if needed.
- Tables to not need to exist to have variables saved to them. If a table
does not exist, it is created automatically, using
OPTIONS OWNER
to set the Owner ID. The description is set to the creating Job name, Jes Number, and current date.
SETUP(YES|NO|PROMPT)
- Sets the
SETUP
value for any new variables when saved into a JCL Variable Table:YES
- Resolve variable at SETUP phase.
NO
- Resolve variable at SUBMIT phase (default).
PROMPT
- Promptable variable.
You can change the default with
OPTIONS SETUP
.
- Object processing
CURSOR(<rowvar>,<colvar>)
- Names the variables used in a previous
VARSCAN
command to establish the row and column where the string is located. Use thePOSITION
keyword to offset from the cursor position to collect data from the same or adjacent rows.Both arguments in this keyword must point to existing variables that contain integers.
POSITION([+|-]row|=,[+|-]col|=,[+|-]end)
- Enables data to be collected from a row in an object variable. You must set an
integer for row, column, and end positions by setting three arguments as follows:
- The first argument sets the row from which to collect data. Specify an integer
(for example, 1 to collect data from row 1), or a relative number with
respect to the
CURSOR
(for example, -1 or +2 to collect data from 2 rows before or after theCURSOR
, respectively). Use the equal sign = to collect data from the same row as theCURSOR
).If a negative offset results in a row before the start of the file, an empty row is returned. If a positive row is generated beyond the end of the object, an empty row is returned and a warning message issued (RC=4).
- The second argument sets the column from which to collect data. Specify an
integer (for example, 10 to collect data from column 10), or a relative
number with respect to the
CURSOR
(for example, -10 or +10 to collect data from 10 characters before or after theCURSOR
, respecitvely). Use the equal sign = to collect data from the same column as theCURSOR
. - The third argument sets the column where to end collecting data. Specify an
integer (for example, 72 to end collecting at column 72) or a relative
number with respect to the
CURSOR
(for example, -10 or +10 to end collecting data from 10 characters before or after theCURSOR
, respectively). Use the equal sign = to end collecting data at the same column as theCURSOR
. If you do not specify any value for the third argument, data is collected until the end of the row.
- The first argument sets the row from which to collect data. Specify an integer
(for example, 1 to collect data from row 1), or a relative number with
respect to the
After data is extracted from the object with the combination of the
OBJECT
,CURSOR
andPOSITION
keywords, the value can be further refined by using the Text Modification keywords.
Use the VARSET
command set, modify, and optionally save a variable.
It is a progressive command where the order the keywords is important for the result, because
each keyword is applied to data in the order you specified.
Use Data source keywords first, and possibly Object processing keywords, before being passed into either Text or Mathematical modifiers to manipulate the value. Finally, use the Variable management keywords to determine how and where the variable is to be stored.
23
:VARSET MYVAR VALUE(12345678) LEFT(3) RIGHT(2)
78
:VARSET MYVAR VALUE(12345678) RIGHT(2) LEFT(3)
Examples
The following command sets the Workload Automation Programming Language variable
MYVAR
to Hello
, which can be used for
the remainder of this Workload Automation Programming Language step.
VARSET MYVAR = “Hello”
does the same thing, but this
syntax does not have access to any other VARSET
features.VARSET MYVAR VALUE(Hello)
VAR1
toABC123
VAR2
to the value ofVAR1
, then takes the 3 leftmost characters, resulting inABC
VAR3
to the value ofVAR1
, then takes the 3 rightmost characters, resulting in123
VARSET EMAIL VALUE(don.lexer@abc.com)
VARSET USER @V(EMAIL) BEFORE(@)
VARSET DOMAIN @V(EMAIL) AFTER(@)
MY.DSN
in DSN and MEMBER in
MEM
. If you did not set the right parenthesis ) the
MEM
variable would be
blank.VARSET FILE = "MY.DSN(MEMBER)"
VARSET DSN @V(FILE) BEFORE("(")
VARSET MEM @V(FILE) AFTER("(") BEFOREX(")")
MYVAR
to Hello
. The variable is then assigned
to JCL variable table MYTAB
and saved in the
database.VARSET MYVAR VALUE(Hello) TABLE(MYTAB) SAVE(YES)
VARSET
command, but not SAVE them on
the VARSET command, instead having a separate VARSAVE
command
to update the table record with all the variables at
once.VARSET NAME1 VALUE(Tom) TABLE(MYTAB)
VARSET NAME2 VALUE(Dick) TABLE(MYTAB)
VARSET NAME3 VALUE(Harriet) TABLE(MYTAB)
VARSAVE MYTAB
1000000
:VARSET BIGNUM = "1,000,000"
VARSET CLNNUM @V(BIGNUM) CLEAN(32,,)
INFILE
:VARSET DSNAME ENVATTR(DD,DSNAME,INFILE)