VARSET – Set a Workload Automation Programming Language variable

VARSET variable = <expression>

VARSET 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)]

• 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 with Hello 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) causes MYADID 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. The USRF 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 by LIST or SELECT command, are not allowed.

  You can use the OBJECT keyword together with the POSITION keyword, and optionally with the CURSOR 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. The MISSING keyword must be specified after a USRF keyword. If you specify it before, the VARSET 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 the USRF 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 variable USERNAME is set to RANA, unless the user has added a User Field to the running job named OVR_USERNAME. In this case, the value in the User Field is kept.

  In the command VARSET USERNAME USRF(User Name) MISSING(FAIL), the variable USERNAME is set to the contents of a User Field named User 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 Language OPTIONS 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.

  For DD 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.

  For JCL, the item can be one of the following:

  • PROCSTEP or STEPNAME.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 no item value except when you set minor to SPE; in this case, item can be the name of the SPE.

  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, while MEM1X 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) causes MYPFX to contain the first 4 characters of the application name.

  You can use LEFT and RIGHT 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) causes MYPFX 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) causes MYPFX to contain the last 4 characters of the application name, regardless of how long the application name actually is.

  You can use RIGHT and LEFT 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) causes MYPFX 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) sets MYBIT 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) returns quick.

  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) returns brown.

  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) returns A

  VARSET MY5TH VALUE(A,,C,,E,F) WORD(5,COMMA) returns E

  VARSET MYLAST VALUE(A,,C,,E,F) WORD(-1,COMMA) returns F

  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. The UPPER keyword without arguments defaults to UPPER(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 the VARSET command is run, the value of RUNCOUNT is substituted into the VALUE keyword. Then, the VARSET command adds 1 to the current value and saves it into MYTABLE. If RUNCOUNT does not already exist in MYTABLE, the VARFAIL(NULL) results in the VALUE keyword containing a null value, which the DELTA process considers as zero. The end result being RUNCOUNT contains 1 and is added to MYTABLE.

  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 in MYTABLE, but VARFAIL(NULL) causes the first table in the search sequence to be assigned as the source table name. You can, however, use the TABLE 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 specify SAVE without argument, SAVE(YES) is assumed.

  Note:

  1. To set several variables in the same table, it is more effective to use a subsequent VARSAVE command than using SAVE on every VARSET.
  2. Variables do not need to already exist within a table. They are added to the table, if needed.
  3. 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 the POSITION 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:

  1. 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 the CURSOR, respectively). Use the equal sign = to collect data from the same row as the CURSOR).

     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).

  2. 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 the CURSOR, respecitvely). Use the equal sign = to collect data from the same column as the CURSOR.
  3. 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 the CURSOR, respectively). Use the equal sign = to end collecting data at the same column as the CURSOR. If you do not specify any value for the third argument, data is collected until the end of the row.

  After data is extracted from the object with the combination of the OBJECT, CURSOR and POSITION keywords, the value can be further refined by using the Text Modification keywords.

VARSET MYVAR VALUE(12345678) LEFT(3) RIGHT(2) 

VARSET MYVAR VALUE(12345678) RIGHT(2) LEFT(3)