User variables

You can use user-defined variables, RUV-defined variables, and IBM defined variable substitution symbols when you create journal model, skeleton JCL, internal reader, and VSAM name model entries.

User-defined variables

Use the ADD USER_VARIABLES command to define your own user-defined variables. Define a user-defined variable by coding a variable name, which begins with the less-than character (<) and ends with the greater-than character (>), and its variable substitution value, which can contain other system or user-defined variables. Each user-defined variable is limited to one command line (71 characters). Indicate the end of the list of user-defined variables by coding the END_DATA keyword. For more information, see ADD USER_VARIABLES syntax.

Substring notation

You can select portions of a user variable by using substring notation, as shown in the following example:

<USER_VARIABLE { (<start_location> {, <length> } ) } >

The start_location and length values indicate position and count. The default start_location number is 1. If the start_location number is larger than the length of the variable, RUV substitutes a null value. Use a minus sign in the start_location value to specify a count from the end of the variable and a move right by the length value. If you do not provide a length value, RUV assumes that you want to use the remainder of the string. The following table shows examples with the job name PRODGNL.

Notation	Result	Explanation
<PRODGNL>	PRODGNL	Default uses all characters
<PRODGNL(3,2)>	OD	Start at third character, count 2
<PRODGNL(,2)>	PR	Start at first character, count 2
<PRODGNL(5)>	GNL	Start at fifth character
<PRODGNL(9,3)>		9 too large, null substitution
<PRODGNL(-3)>	GNL	Go to end, move back 3

RUV-defined variables

RUV provides the following predefined variables:

Variable	Definition
<BACKUP_DSN>	The data set name of the backup data set. This variable is the value of the BACKUP_FILE keyword (1–44 characters) from the REGISTER BACKUP_FILE command that was used to register the backup. This variable is valid in restore job JCL records.
<BACKUP_TIME>	The start time, in yyyyjjjhhmmsst format, of the backup. This variable is the value of the START_TIME keyword. This variable is valid in restore job JCL records.
<JOBNAME>	Standard z/OS JCL job statement name that executes an initiator.
<JOB_NUMBER>	Standard z/OS JES job number.
<LOOP_TIME>	A time, in yyyyjjjhhmmsst format, that RUV assigns to this variable when it encounters the <:BEGIN_LOOP> action variable. This time value does not change until RUV finishes processing the members of the group and exits the loop.
<LOOP_TIME_HEX>	A time, in X hhhhhhhhhhhhhhhh format, that RUV assigns to this variable when it encounters the <:BEGIN_LOOP> action variable. This time value does not change until RUV finishes processing the members of the group and exits the loop.
<NODE n>	The contents of the node (qualifier) in the input data set name at the position that is indicated by n; for example, if the input data set name is PAYROLL.TAXWTHLD.DATA, the variable <NODE2> refers to the string TAXWTHLD. The <NODE n> variable is valid in VSAM name models, output models, and job JCL records. If you specify this variable in a backup or restore job JCL record, it is valid only within a set of <:BEGIN_LOOP> and <:END_LOOP> action variables.
<PARAMETER>	A 64-byte user-defined field. The value is provided at registration time. This variable is valid in backup and restore job JCL records.
<PGMNAME>	Standard z/OS JCL EXEC job statement name for program being executed.
<PROCNAME>	Standard z/OS JCL procedure name in a PROCLIB that will produce a set of JCL.
<RUVBACKUP>	consolidates <RUVDATE> and <RUVTIME> into one variable.
<RUV_CONTROL>	A place-holder specification for all RUV commands and keywords. Used in JCL and ISPF. This variable indicates the position in which all control statements will be placed in your job.
<RUVDATE>	The current Julian date D yyyyjjj: 4-digit year, 3-digit day of the year (1 to 366).
<RUV_JOB_JCL>	The 32-character name of the backup job JCL record that was specified in the SUBMIT command.
<RUV_JOURNAL>	The journal data set name (44-characters) that is active for the batch journaling facility. Whenever a batch job is running and it has journaling, a user-set file will be opened named RUV_JOURNAL. Used primarily for backout situations.
<RUV_JOURNAL_ DEACTIVATE>	Used to deactivate logs and journals after a backout. Used in JOB_JCL models; valid only in backout jobs. Causes the following statement to be added for each log or journal created in a job step: UPDATE ARCHIVE_FILE( archive_dsn) REGISTRATION_TIME( Xhhhhhhhhhhhhhhhh) STATUS(INACTIVE); Xhhhhhhhhhhhhhhhh is replaced with the registration time of the archive or archives.
<RUV_LOG>	The logging data set name (44-characters) that is active for the batch journaling facility. Whenever a batch job is running and it has before-image logging, a user-set file will be opened named RUV_LOG. Used primarily for backout situations.
<RUV_STEPLIB>	Propagates the current z/OS load libraries and RUVEVLIB to the recovery job. Used in JOB_JCL models. Enter this variable on a line by itself. It might produce multiple lines of output.
<RUVTIME>	The current GMT time in 24-hour military time: T hhmmsst 2-digit hour (00 through 23), 2-digit minute (00 through 59), 2-digit second (00 through 59), and 1-digit tenths of a second (0 through 9).
<RUVTIME_HEX>	The current GMT time in hexadecimal format: X hhhhhhhhhhhhhhhh.
<SMFID>	Standard z/OS JCL 4-character name that identifies a system (like SYSx).
<STEPNAME>	Standard z/OS JCL job step name that executes in an initiator.
<SYSNDX>	A seven-digit number that works with <:BEGIN_LOOP> and <:END_LOOP> action variables that define a processing loop. <:BEGIN_LOOP> sets the value of <SYSNDX> to 0000001. RUV processes the statements within the loop for each member of a VSAM group and increments the value of <SYSNDX> by one for each loop. <SYSNDX> is valid in backup and restore job JCL records.
<USERID>	Standard z/OS JCL job statement value that identifies the user.
<VSAM_DEFINITION>	Build IDCAMS Define function statements for a VSAM file. This variable is valid only within a set of <:BEGIN_LOOP> and <:END_LOOP> action variables.
<VSAM_PATH_ DEFINITION>	Build IDCAMS Define function statements for all associated alternate indexes and paths. BLDINDEX commands are also created. This variable is valid only within a set of <:BEGIN_LOOP> and <:END_LOOP> action variables.
<VSAM_DSN>	A user-specified data set name (44-characters). If you specify this variable in a backup or restore job JCL record, it is valid only within a set of <:BEGIN_LOOP> and <:END_LOOP> action variables.
<+1>	This variable allows you to change a value incrementally by adding a number to the end of it. Each time you use this variable, it adds 1 to a hidden number n (a 7-character number formatted as V0000000). The first time the variable is used, it is incremented to 1 (V0000001). The next time it is used, it is 2 (V0000002), and so forth.

IBM variable substitution symbols

RUV supports IBM type variable (such as & XXX .&YYY ) substitution, as shown in the following example:

GL.&SYSUID.&DATE.T<RUVTIME(2,5)>.

You can display the IBM symbols that are defined at your data center by entering the command D SYMBOLS at the z/OS console.

RUV action variables

You can use RUV action variables in backup and restore job JCL records to control the variable substitution process. Action variables are enclosed by the less-than symbol and the colon ( <: ) and a greater-than (>) symbol; <:BEGIN_LOOP> is an example of an action variable. The <: combination is reserved by RUV and is always interpreted as an action variable. Do not use this combination for any other purpose.

Action Variable	Usage
<:BEGIN_LOOP>	Code the <:BEGIN_LOOP> action variable at the beginning of a set of JCL statements that you want RUV to process for each member of the specified VSAM group. <:BEGIN_LOOP> also resets the <SYSNDX> variable to 0000001. Loops cannot be nested; close a loop that is started with the <:BEGIN_LOOP> action variable by coding the <:END_LOOP> action variable before you code another <:BEGIN_LOOP> action variable.
<:END_LOOP>	Code the <:END_LOOP> action variable at the end of a set of JCL statements that you want RUV to process for each member of the specified VSAM group.
<:IMBED imbed_source>	Code the <:IMBED outside_source> action variable to insert statements from a source that is outside of the job JCL record. The string outside_source represents the ddname or data set name of a flat file or partitioned data set member that contains fixed-length, 80-byte records. After RUV inserts the statements from the outside source, RUV continues to perform variable substitution for any variables. RUV supports nested <:IMBED outside_source> action variables for a maximum of ten levels. You can use variables to build the ddname or data set name that identifies the outside source. Code the <:IMBED outside_source> action variable on a line by itself. You can also use the <:IMBED outside_source> action variable with the STORE INTO_FILE command.
<:VSOFF>	Code the <:VSOFF> action variable to disable RUV substitution and echo the input statements as they are coded. You can code <:VSOFF> in any position in the input statement.
<:VSON>	Code the <:VSON> action variable to resume RUV substitution after you have disabled it with <:VSOFF>. You can code <:VSOFF> in any position in the input statement.