AutoEdit Variables

Control-M/Tape can automatically perform actions based on various events, such as a tape mount. The variety of possible actions is enhanced by the use of the AutoEdit variables supported by the AutoEdit facility.

AutoEdit variables can be specified in certain Control-M/Tape DO statements (for example, DO SHOUT, DO COND) in place of values that change constantly. These variables are prefaced by a %% symbol to distinguish them from non-AutoEdit variables.

During processing, DO statements that can contain AutoEdit variables are scanned for AutoEdit variables (meaning, terms beginning %%).

When AutoEdit variables are detected, they are analyzed, edited, and automatically assigned appropriate values (eliminating the need to manually change the values). The DO statements are performed using the new, assigned values. The contents of the original DO statements remain unchanged.

Example

A rule contains a DO SHOUT statement with the message:

Copy 
VOLSER %%VOL001 WAS CHECKED-IN

When the DO SHOUT is performed, AutoEdit variable %%VOL001 is analyzed and resolved.

If the actual volser of the checked-in volume is 111222, the shouted message automatically appears as:

Copy 
VOLSER 111222 WAS CHECKED-IN

AutoEdit variables are divided into two types:

  • System Variables

    AutoEdit system variables are predefined variables, provided with the product, that are replaced by values taken from the Control-M/Tape environment.

    For example, AutoEdit system variable %%TDATE is replaced by the date a specified event occurred.

  • User-Defined Variables

    In contrast to system variables, user-defined variables are variables that are created by the user. The user must therefore provide the value (or the tools to derive the value) that replace the variable. Values for user-defined variables are provided by DO SET statements. These values can be used as input for other INCONTROL products (for example, Control-M).

    For example, the user can define a variable %%TAPELOG whose value is supplied by System variable %%JCLVOL:

    DO SET=%%TAPELOG = %%JCLVOL

    User-defined variables can be any non-reserved alphanumeric string starting with %%. Characters @, #, $, and – are also valid. Lowercase characters are not translated to uppercase characters upon resolution.

AutoEdit System Variables

The following table lists the AutoEdit System variables supported in Control-M/Tape. They can be used to insert environment information into the rule’s operation.

Table 198 Control-M/Tape AutoEdit Variables

Variable

Description

%%ACCOUNT

Account value

%%CPUID

CPU ID

%%DATE

Date of handling the event (YYMMDD format)

%%DDNAME

DD name

%%DSEXPDT

Data set expiration date
When %%DSEXPTYP is

  • DATE, resolves to Julian format (YYYYJJJ) expiration date

  • CYCLE, resolves to number of cycles

  • LAST-ACC, resolves to number of days

During an OPEN event, the value of both %%DSEXPDT and %%DSEXPTYP is the abend retention.

%%DSEXPTYP

Data set expiration type
Valid resolution values are:
CATALOG, CYCLE, DATE, EDM, JCL-EXPDT, LAST-ACC, PERMANENT, RET-VAULT, SMS

Only the first retention is supported.

%%DSLABEL

Data set label sequence number

%%DSNAME

Data set name

%%ENV

Environment ID
Valid resolution values are: SVCT, ONLC

%%JCLVOL

First five volumes, separated by commas

%%LASTACCS

Last access operation. Possible (valid) resolution values: READ, WRITE, CREATE

%%LBLTYP

Label type. Possible (valid) resolution values: NL, SL, NSL, SUL, BLP, AL, AUL

%%MEDIA

Media name

%%OWN001 – %%OWN999

Owner of volume

%%PGMNAME

Program name

%%POOL

Pool name

%%SLN001 – %%SLN999

Standard Label name of volume

%%STEPNAME

Step name

%%TDATE

Actual date the event occurred (YYMMDD format)

%%TIME

Time of handling the event (format hhmmss)

%%TJOBID

Job ID

%%TTIME

Actual time the event occurred (format hhmmss)

%%UCB

UCB address.

%%UNITGNAM

Generic unit name.

%%USERFLD

User field

%%USERID

User ID / Job name

%%VAULT

Location of the volume

%%VOL001 – %%VOL999

Volume serial number
%%vol001,%%vol002, ... ,%%vol005

%%VOLCOUNT

Number of volumes for the current data set

%%WHEN

Condition under which the event occurred. Possible (valid) resolution values: OPEN, CLOSE, MOUNT, CHECK-IN-VOLUMES, CLOSE-AFTER-ABEND, KEEP

Note the following about system variables:

  • Some AutoEdit variables may contain blanks if the information is not available when the rule is matched.

    For example, if a rule is matched when a Mount for SCRATCH is requested, the value of variable %%VOL001 is not yet known. Therefore, its value is set to blanks.

  • Correct use of the date and time variables requires that you distinguish between the date and time an IOA function was requested and the date and time the IOA function was performed:

    • Current date and time refer to the date and time the rule requested the IOA function specified in the DO command. This date and time is represented by System variables %%TDATE and %%TTIME.

    • Actual date and time refer to the date and time the requested IOA functions were actually performed by the IOA Functional monitor (subsequent to the issuing of the request by the rule). This date and time is represented by System variables %%DATE and %%TIME.

    • The values DATE / PREV / NEXT / ODAT, and so on, in the DATE field of a DO FORCEJOB or DO CONDITION statement are checked relative to %%TDATE values.

Rules of Variable Resolution

Multiple AutoEdit variables and constants can be joined together into complex terms. Resolution depends on the method used to join the component terms together. When a complex term contains multiple variables, those variables are resolved from right to left.

The methods of joining multiple variables together are described below.

  • An AutoEdit variable can be appended directly to a constant.

Examples

Table 199 Example - Appending AutoEdit Variable to a Constant

Action

Effect

Resolve:

SMF_TAPE%%VOL001

Assuming:

volser = 111111

Resolution:

SMF_TAPE_111111

  • Two variables can be concatenated into two distinct but joined variables by placing a period between them.

Table 200 Example - Concatenating Two Variables - 1

Action

Effect

Resolve:

%%PGMNAME.%%DATE

Assuming:

Program name = BACKUP and Date = 060600

Resolution Steps:

%%PGMNAME.060600

Final Resolution:

BACKUP060600

  • Two variables can be concatenated into two distinct variables joined by a period by placing two periods between them.

Table 201 Example - Concatenating Two Variables - 2

Action

Effect

Resolve:

%%PGMNAME.%%DATE

Assuming:

Program name = BACKUP and Date = 060600

Resolution Steps:

%%PGMNAME.060600

Final Resolution:

BACKUP.060600