AutoEdit Facility

This chapter contains the following topics:

• Overview

• System Variables

  • Supported Variables

  • UNIX Server for z/OS Resource Monitor System Variables

  • Rule Stack Variables

  • User-Defined Variables

  • Global Variables

  • Reserved User-Defined Variables

  • Rules of Variable Substitution

• Assigning AutoEdit Variables

  • Using the DO SET Statement

  • Using an AutoEdit Variable Database

  • Using an XAE AutoEdit Variable Database

• AutoEdit Operators

• Control Statements

  • %%$MLLEND

  • %%$RESOLVE

  • %%$RANGE

• Functions

  • %%$CALCDATE

  • %%$POOLCOSMOS

  • %%$POOLSTORE

  • %%$POOLTYPE

  • %%$SUBSTR

  • %%$TIMEINT

  • %%$POS

  • %%$ISNUM

  • %%$PARSE

Overview

Control-O can automatically perform actions based on the occurrence of messages or events. The variety of possible actions is enhanced by use of the AutoEdit facility.

When Control-O handles DO actions, ON statements and IN conditions, the contents of the subparameters are scanned for special symbols, starting with %%. These symbols are analyzed, edited and automatically assigned new values. The modified statement is then activated. The contents of the original statement remain unchanged.

Using the AutoEdit facility in a rule definition provides great flexibility in condition specification and action definition. For example:

• A start command can contain the current date as a parameter.

• The jobID of the job that issued the message can be included in a command issued to correct a situation.

• Text from the original message can be used within a newly edited message, or in an operator command or a TSO command.

• The DO SET command can be used to assign values to reserved user-defined AutoEdit variables, or to define your own user-defined AutoEdit variables and assign them values that can be retrieved from the message or command. These values can be used in subsequent DO actions, ON statements and IN conditions of the rule.

User-defined AutoEdit variables can be defined as local, global, and XAE global. Local variables are stored on one machine, with changes affecting only a rule running on that machine. Global variables are stored in a common storage area on a machine. Changes to a Global variable can be accessed by all rules on that system. XAE Global variables can be accessed by all rules running on any system in a Sysplex. For more information about the XAE facility, see Using an XAE AutoEdit Variable Database

Global variables can be used:

• in subsequent executions of the same rule

• in other rules

• by the Control-M AutoEdit facility

• in KOA scripts

• in execution of a rule on other Sysplex participants (if an XAE database is defined)

There are several categories of AutoEdit symbols

• control statements

• functions

• operators

• System variables

• user-defined Local variables

• user-defined Global variables

The following Rule Definition screen displays examples of AutoEdit symbol types. For information about reserved user-defined variables, see Reserved User-Defined Variables.

Figure 244 AutoEdit Symbol Types Example

RL: DFS810A    LIB CTOP.V610.RULES                            TABLE: JOB 
 COMMAND ===>                                                 SCROLL===> CRSR
 +--------------------------------------------------------------------------+
 ON MESSAGE  = DFS810A
 JNAME          JTYPE      SMFID        SYSTEM          USERID
 ROUTE          DESC       CONSOLEID    CONSOLE
 APPEARED       TIMES IN      MINUTES                        And/Or/Not
 OWNER IOAADMIN GROUP                         MODE PROD    RUNTSEC
 THRESHOLD
 DESCRIPTION IDENTIFY IMS IS READY (KEEP REPLY NUMBER + SIGNAL CONTROL-M)
 DESCRIPTION
 ===========================================================================
 DO SET      = %%J = %%$JOBNAME                                    GLOBAL  N
 DO SET      = %%COUNT_%%J = %%COUNT_%%J %%$PLUS 1                 GLOBAL  Y
 DO SET      = %%REPLY_%%J = %%$REPLY                              GLOBAL  Y
 DO SET      = %%PREF = %%$SUBSTR %%$JOBNAME 1 3                   GLOBAL  N
 DO COND     = %%%J_IS_DOWN         STAT -
 DO SHOUT    = TO TSO-%%PREF        URGENCY R SYSTEM          CTO282I
 MESSAGE %%$JOBNAME ACTIVE
 DO
 ===========================================================================
 FILL IN RULE DEFINITION. CMDS: CAPS, EDIT, SHPF, SCHED, OPT         11.51.00

The first DO SET statement defines a local user variable named %%J. It is assigned the value of the %%$JOBNAME System variable that is the name of the job issuing the message.

The second DO SET statement defines a Global user variable named %%COUNT_%%J. The variable resolves into the name of the IMS that has started, for example, COUNT_IMS1. The %%$PLUS AutoEdit operator increments the variable by 1. This Global variable serves as a counter of the number of times that IMS has been started.

The third DO SET statement defines a Global user variable named %%REPLY_%%J, which is used to keep the open reply number of IMS (from the %%$REPLY System variable).

The fourth DO SET statement defines a local user variable named %%PREF using the %%$SUBSTR function to extract a prefix (the first three characters of the job name). This prefix is used in the following DO SHOUT statement to send a message to a specific TSO user.

The DO COND statement deletes a prerequisite condition in the IOA Conditions file. The prerequisite condition name is defined by an AutoEdit variable.

System Variables

Control-O System variables are predefined variables whose values are automatically updated and maintained by Control-O.

The System variable format is

%%$var

In this format, var is the name of the System variable.

Each AutoEdit System variable begins with "%%$". Each variable resolves to (is replaced by) the corresponding system value.

DO COMMAND=S BKPDISK,PARM='%%$RDATE'

DO COMMAND=S BKPDISK,PARM='001212'

IN %%$SMFID-UP

IN FDSF-UP

Supported Variables

This section describes the supported AutoEdit system variables.

Table 173 Commonly Used AutoEdit System Variables

Table 174 1-byte autoedit system variables

Table 175 Global AutoEdit System Variables

DO SET=%%$GLOBAL = IMS
DO SET=%%STATUS = UP GLOBAL Y

Table 176 Command AutoEdit System Variables

Table 177 Control-M AutoEdit System Variables

Table 178 Control-O AutoEdit System Variables

ON MESSAGE TST*
DO SET=%%$AUTOLOG=N

UNIX Server for z/OS Resource Monitor System Variables

Table 189 is a list of the UNIX Server for z/OS Monitor system variables that are supplied by Control-O.

Table 189 Unix Server for z/OS System Variables

Rule Stack Variables

A Control-O rule can trigger other Control-O rules through DO RULE statements. When a series of Control-O rules trigger each other they are referred to collectively as a Rule Stack. Control-O rules can be stacked up to 20 deep.

The variables listed below can be included in a Control-O rule to determine information about the Rule Stack of the rule.

Some of these variable names must be supplied with a numerator, where 0 indicates the first rule in a stack, 1 is the rule triggered by the first rule in the stack (that is, the second rule in the stack), and so on.

Table 190 Rule Stack Variables

User-Defined Variables

User-defined variables can be defined to provide additional flexibility for Control-O rules. You can define your own symbols, assign values to them, and they will automatically be resolved in DO statements, ON and IN statements. DO statements are resolved during rule execution. AutoEdit symbols in ON statements and IN condition names are resolved during rule ordering.

When Control-O identifies a string that starts with %%, the string is assumed to be an AutoEdit variable or instruction. If the string is a reserved AutoEdit variable or a Control-O System variable, it is interpreted as such. Otherwise the string is assumed to be a user-defined variable.

DO actions within a rule are performed sequentially. If a user-defined variable in a DO statement is not completely resolved, the default action is to cancel the DO statement and all subsequent DO statements of the rule (for the current activation). This default can be overridden by using the %%$RESOLVE NO control statement in a prior DO SET statement. For a description of the %%$RESOLVE statement format, see %%$RESOLVE. In this case, Control-O resolves the symbol as far as possible and then performs the DO statements in which it is found.

Global Variables

Global variables are user-defined variables that can be used to share information between different features of Control-O. These variables can also be referenced by other INCONTROL products active at your site. A primary usage of the Global variables is to set globally accessed flags or counters (such as the current IMS reply number).

Global variables are contained in the Global AutoEdit library and in AutoEdit variable databases. Global variables are loaded when Control-O is started. For more information on the Global AutoEdit library see the Control-O chapter in the INCONTROL for z/OS Administrator Guide. For more information on AutoEdit variable databases see IOA Variables Database Facility.

XAE databases can be used for sharing variables across the Sysplex. XAE databases are defined and administered by the INCONTROL administrator. For more information, see Using an XAE AutoEdit Variable Database.

Reserved User-Defined Variables

Some user-defined variables are reserved by, and have a special meaning for, Control-O. The values of most reserved variables are tested by Control-O before performing specific DO statements, in order to establish the processing mode and the processing parameters of the DO statements.

Reserved variables, like other user-defined variables, are set by a DO SET statement, and then resolved automatically when they appear in other DO statements. They are never Global variables.

Table 191 shows the reserved user-defined variables are available.

Table 191 Reserved User-Defined Variables

ON MESSAGE TST*
DO SET=%%$AUTOLOG=N

DO SET %%$COMMSYS = SYS*
DO SHOUT=TO TSO-CICSOPR
URGENCY R SYSTEM
MESSAGE CICS IS DOWN!

DO SET=%%$DOLIMIT = 500

DO SET=%%$GLOBAL = IMS
DO SET=%%STATUS = UP GLOBAL Y

DO SET=%%$RESPMSG = (CTM101I, CTM240I)
DO COMMAND=F CONTROLM,NEWCONLIST

DO SET=%%$RJOBNAME = %%$V3
DO SET=%%$RJOBID = %%$V4
DO RESOURCE=TAPE 0001 -

ON MSG CKH*
DO SET %%$STATID = CKHMSG

DO SET=%%$WAITKSL = YES
DO KSL=scriptname arg1 arg2 ... arg10
IF %%$KSLRC EQ# 4
DO SHOUT=...

DO SET=%%$WAITRESP = YES
DO COMMAND=D T

DO SET=%%$WAITTSO = YES
DO TSO=...
IF %%$TSORC EQ# 4
DO SHOUT=...

Rules of Variable Substitution

A User-defined variable name must conform to the following rules. It must

• begin with "%%" (percent sign, percent sign)

• be composed of letters, digits, and the following characters: "@" (at sign), "#" (number sign), "$" (dollar sign), and "_" (underscore)

• have a maximum of 163 characters

• not begin with

  • %%$ (percent sign, percent sign, dollar sign)

  • %%@ (percent sign, percent sign, at sign)

  • %%# (percent sign, percent sign, number sign)

  Variables that begin with these strings are either system variables or reserved user-defined variables.

Lowercase characters are not translated to uppercase characters upon resolution.

Variables are substituted sequentially from right to left, until the symbol is assigned a value. For example

%%SMF_TAPE_%%$DAY,

resolves on the third of the month to

%%SMF_TAPE_03,

Control-O then tries to resolve the symbol %%SMF_TAPE_03. Assuming the value of the symbol in the Global environment is EE1022, the result is

EE1022

To concatenate two symbols, separate them with a period. Before AutoEdit variables are concatenated, trailing blanks are eliminated. For example

%%$DAY.%%$MONTH

resolves on the 3rd of December to

0312

To put a period between two symbols, use two consecutive periods. For example

%%$DAY..%%$MONTH

resolves on the 3rd of December to

03.12

To concatenate a symbol and a constant, use %%. (concatenation symbol). For example

A91%%$DAY%%.UP

resolves on the 3rd of December to

A9103UP

When Control-O assigns a value to a variable, Control-O ignores leading and trailing spaces. For example, the statement

DO SET=%%X = FRIDAY RUN

assigns the value "FRIDAY RUN" to the %%X variable, regardless of how many spaces you type before or after "FRIDAY RUN."

To assign a value with leading or trailing spaces, use the %%$BLANK system variable. For example, the statement

DO SET=%%X=%%$BLANK.FRIDAY RUN

assigns the value "FRIDAY RUN" (with a leading space) to the %%X variable. Be sure to include the "." concatenation operator between "%%$BLANK" and "FRIDAY RUN." Without the "." Control-O would look for a variable called "%%$BLANKFRIDAY."

Assigning AutoEdit Variables

Values can be set to user-defined variables by either of the following methods:

• using a DO SET statement

• using an AutoEdit variable database

These methods are described below.

Using the DO SET Statement

The DO SET statement is used to set values to user-defined variables, or to specify AutoEdit control statements. The format of the DO SET statement is

DO SET=%%var = value

or

DO SET=%%var = valid_expression

or

DO SET=AutoEdit Control-statements

%%var must be a valid user-defined AutoEdit variable.

Control-O attempts to resolve the variable to a single value by processing it from right to left. For example

DO SET=%%BACKUP_UNIT_%%$WDAY = EE%%$MONTH.%%$DAY

On Sunday the 24th of September, the user-defined symbol %%BACKUP_UNIT_1 is assigned the value EE0924.

If the symbol assigned in the DO SET statement is not completely resolved, the default action is to cancel the DO SET action and the subsequent DO actions of the current rule activation. This default can be overridden by using the %%$RESOLVE NO control statement in a previous DO SET statement, in which case the symbol is resolved as far as possible before performing the DO statement in which it is found. For more information, see %%$RESOLVE.

When rule (DO parameter) activation is canceled, a message is sent to the IOA Log.

All variable assignments remain valid during the activation of that specific rule and will not affect other rules unless you set GLOBAL to Y.

When Control-O tries to resolve a symbol, it searches for the value according to the following order:

1. AutoEdit System variables

2. AutoEdit reserved words (control statements)

3. user-defined variables (Local)

4. user-defined variables (Global)

A Global AutoEdit variable that is referred to as %%variable resides in the default global member (usually $GLOBAL).

A Global AutoEdit variable can be assigned to a specific global member by referring to it as follows:

%%member\variable

For an explanation of Global assignments, see DO SET: Automated Console Action Parameter.

The maximum number that can be handled by mathematical AutoEdit operations is 231 - 1, (that is, 2147483647).

Using an AutoEdit Variable Database

To assign a value to a variable in an AutoEdit variable database:

1. Specify the variable database as the current global variable pool using the %%$GLOBAL system variable.

2. Specify the appropriate row through the %%$DBROW reserved user-defined variable.

3. Set the variable by a DO SET statement as follows:

   Copy

   DO SET %%colname = val

   In this statement

   • colname is the name of the column where the variable exists

   • val is the value to be assigned to the variable

   The following sample set of DO statements accomplishes the steps described above.

   Copy

   DO SET=%%$GLOBAL = MYDB       GLOBAL  N 
   DO SET=%%$DBROW = 3       GLOBAL  N
   DO SET=%%COLNAME = NEWVALUE       GLOBAL  Y

   WHILE and ENDWHILE statements can be used to loop through variables in a column of a table. For more information, see DO SET: Automated Console Action Parameter.

Using an XAE AutoEdit Variable Database

XAE database variable values are different in scope than other database variables. They can be accessed by rules on every system in a Sysplex XAE AutoEdit databases are defined by the administrator.

Values for XAE database variables are set using the same methods as used for other AutoEdit variables. Similarly, they can be defined using the Variable Database Definition facility and can be changed using a DO SET command.

There are two types of XAE databases:

• TYPE 1

• TYPE 2

Type 1 XAE databases

The Type 1 XAE database is composed of variable values maintained by the Sysplex partners. Each system updates its own variables in ECSA (Extended Common Service Area, a common memory area in that system), and in the Coupling Facility. Each system resolves TYPE 1 variables from its own ECSA, but other systems can access these values using the mirror copy of the variables stored in the Coupling Facility.

Resolving an XAE Type 1 database variable value on a current (default) system is the same as for standard databases. For resolutions of the rule from other systems, the default system name is obtained based on the last value set to the %%$AUTOSYS user-defined system variable.

Type 2 XAE databases

In Type 2 XAE databases, all systems participating in a Sysplex share the same view of the database. If one system updates a variable, that variable is updated in the view that is accessible by each of the other systems in the Sysplex. Resolving an XAE Type 2 database variable is the same as for a standard database, except that more than one system can update the same variable. For example, if system A updates a database variable and then system B attempts to resolve that same variable in a statement, the value of the variable accessed by system B is the value as updated by system A.

/*/* SHOUT A VAR WITH STYLE %%SYSTEMNAME\POOLNAME\VARIABLE
/*
DO SHOUT = TO OPER URGENCY R SYSTEM CTO282I
MESSAGE XES XAES1D01 SHOUTING A VARIABLE WITH STYLE SYSTEM\POOL\VAR
/* SET THE ROW NUMBER TO 2
DO SET = %%$DBROW = 2 GLOBAL N
/* THIS STATEMENT CHANGES THE DEFAULT CPU TO OS33
DO SHOUT = TO OPER URGENCY R SYSTEM CTO282I
MESSAGE OS33\XAES1D01\S1D01C01 = %%MYSYS\MYDB\MYCOL
/*

/*/* SHOUT FROM CPU OS33 THE DATABASE CONTENTS FOR OS35
/*
DO SHOUT = TO OPER URGENCY R SYSTEM CTO282I
MESSAGE XES XAES1D01 OS33 SHOUTING DATABASE IN OS35
DO SET = %%I = 0 GLOBAL N
DO SET = %%X = %%$DBCOUNT GLOBAL N
/* CHANGING THE DEFAULT SYSTEM TO OS35
DO SET = %%$AUTOSYS = OS35 GLOBAL N
WHILE %%I LT# %%X
DO SET = %%I = %%I %%$PLUS 1 GLOBAL N
DO SET = %%$DBROW = %%I GLOBAL N
DO SHOUT = TO OPER URGENCY R SYSTEM CTO282I
MESSAGE S1D01C01-5 = %%S1D01C01 %%S1D01C02 %%S1D01C03 %%S1D01C04 %%S1D01C05
ENDWHILE
DO SET = %%X = %%$DBCOUNT GLOBAL N
/* CHANGING THE DEFAULT SYSTEM BACK TO OS33
DO SET = %%$AUTOSYS = OS33 GLOBAL N
/*

/*/* SHOUT ALL THE VARIABLES IN ALL PARTNER SYSTEMS
/*
/* OUTER LOOP
/*
DO SET = %%Y = 0 GLOBAL N
WHILE %%Y LT# %%$SYSPCPUCOUNT
DO SET = %%Y = %%Y %%$PLUS 1 GLOBAL N
/* EXTRACT THE NAME OF NEXT SYSTEM AND SET AS DEFAULT
DO SET = %%$SYSPCPU = %%Y GLOBAL N
DO SET = %%SYST = %%$SYSPCPUNAME GLOBAL N
DO SET = %%$AUTOSYS = %%SYST GLOBAL N
DO SHOUT = TO OPER URGENCY R SYSTEM CTO282I
MESSAGE XES XAES1D01 OS33 SHOUTING DATABASE IN SYSTEM # %%Y (%%SYST)
/*
/* INNER LOOP
/*
DO SET = %%I = 0 GLOBAL N
DO SET = %%X = %%$DBCOUNT GLOBAL N
WHILE %%I LT# %%X
DO SET = %%I = %%I %%$PLUS 1 GLOBAL N
DO SET = %%$DBROW = %%I GLOBAL N
DO SHOUT = TO OPER URGENCY R SYSTEM CTO282I
/* DISPLAY THE VARIABLE (COLUMN NAME)
MESSAGE S1D01C01-5 = %%S1D01C01 %%S1D01C02 %%S1D01C03 %%S1D01C04 %%S1D01C05
ENDWHILE
ENDWHILE
/* RESTORE TO DEFAULT SYSTEM
DO SET = %%$AUTOSYS = %%$SYSTEMNM GLOBAL N

AutoEdit Operators

Within a DO SET statement, AutoEdit operators can be used together with AutoEdit variables. Valid AutoEdit operators are shown in Table 192.

Table 192 AutoEdit Operators

The format for use of AutoEdit symbols and operators is

operand operator operand

Only one operator may be used in each AutoEdit expression.

Operands must be resolved into numeric constants. The final result is translated into a character string. For example:

DO SET=%%NUMBER_OF_ABENDS_%%$RDATE = %%NUMBER_OF_ABENDS%%$RDATE %%$PLUS 1

On installation working date November 03, 2000 the symbol %%NUMBER_OF_ABENDS_001103 will contain the number of abends that occurred in the data center, during the working day.

Control Statements

The following AutoEdit Control Statements can be specified in a DO SET statement.

%%$MLLEND

When a rule is in command-response mode, that is, when WAITMODE=Y is specified in a DO COMMAND statement, Control-O suspends rule execution until either the specified time-out is reached, or a "last" line (that is, the last line of a multiline message) is detected.

Some command responses can contain more than one "last" line, for example, if the response contains more than one multiline message. In such cases Control-O normally exits command-response mode when it detects the first "last" line. To avoid this problem, a %%$MLLEND statement can be used to disable the search for a "last" line, in this way causing the rule to remain in command-response mode until the specified time-out is reached. The time-out is specified in the TIMEOUT subparameter in the DO COMMAND statement.

Valid %%$MLLEND control statements are shown in Table 193.

Table 193 %%$MLLEND Control Statements

For more information, see DO COMMAND: Automated Console Action Parameter.

 DO SET  = %%$MLLEND = NO 
 DO COMMAND = F CICST,CEMT I TASK
        WAITMODE   Y                    WAITRESP Y
 .
 ENDMSG

%%$RESOLVE

Control-O always attempts to resolve a variable that begins with %%. By default, if the AutoEdit expression cannot be fully resolved, the DO action containing the variable, and all subsequent DO actions of the current activation of the rule, are cancelled.

You can override this default by including a %%$RESOLVE NO or %%RESOLVE FORCE statement in a previous DO SET parameter statement. For details, see AutoEdit Resolution Override Process.

If any %%$RESOLVE statements other than %%$RESOLVE NO are specified, and a variable cannot be resolved, subsequent DO actions in the rule are cancelled and an error message is issued.

A %%$RESOLVE statement is assigned in a DO SET statement and affects all subsequent DO statements until the next %%$RESOLVE statement in the rule. For more information, see DO SET: Automated Console Action Parameter.

Default AutoEdit Resolution Process

The default %%RESOLVE statements are

• %%$RESOLVE

• %%$RESOLVE MUST

• %%$RESOLVE YES

To resolve an AutoEdit expression, Control-O analyzes the expression from right to left. The expression is divided into its components, called tokens. Each token represents an AutoEdit variable to be resolved. During normal AutoEdit resolution, this process is normally performed once.

However, if an unresolved token exists after this process is performed, a second pass is performed on the entire expression. If an unresolved token still exists, then the expression remains unresolved and the current and subsequent DO statements are not performed.

AutoEdit Resolution Override Process

The %%RESOLVE override statements are

• %%$RESOLVE NO

• %%$RESOLVE FORCE

%%$RESOLVE NO

The %%$RESOLVE NO statement instructs Control-O to perform the DO statements even if the AutoEdit statement cannot be fully resolved. If any tokens cannot be fully resolved, they are resolved as far as possible before performing the DO statement.

%%$RESOLVE FORCE

By default, if a token resolves to the name of another AutoEdit variable during the first pass, that token is considered resolved and there is no further attempt at resolution. This can occur in the following situations:

• A global variable was loaded into memory at Control-O startup, or during a LOADGLOBAL operation, and the value of that variable contained an expression that included the name of another variable.

• A variable was set to a non-existent AutoEdit variable while %%$RESOLVE NO was in effect.

The %%RESOLVE FORCE statement overrides this default by instructing Control-O to perform a second pass on the token that initially resolved to the name of another AutoEdit variable.

AutoEdit Resolution Process for Sysplex

When Control-O attempts to resolve a variable stored in a Sysplex XAE type 1 database that belongs to a Control-O in another system, then by default, if the Control-O system is down, an AutoEdit error is issued.

The %%RESOLVE ODOWN statement resolves any variables left in the Coupling facility by a Control-O system that is no longer available. This can be used, for example, to ascertain values set by the failing system.

DO SET=%%$RESOLVE NO 
DO SHOUT=TO TSO-PROD URGENCY R
 MESSAGE SET THE VALUE OF THE %%INDEX_DOLLAR PARAMETER
DO SET=%%$RESOLVE

SUB=MSTR,LLA=%%$GLOBAL\SYSCLONE

SUB=MSTR,LLA=01

DO SET=%%$RESOLVE ODOWN 
DO SHOUT=THE VARIABLE VALUE IS
 %%othersys\dbname\colname
DO SET=%%$RESOLVE

%%$RANGE

A %%$RANGE statement limits performance of AutoEdit functions to a specified column range. Data, commands and control statements outside the range remain unchanged.

This statement is useful when values must be specified in specific columns and when not every AutoEdit expression needs to be resolved.

The format of the %%$RANGE statement is:

%%$RANGE fromcol tocol

In this format

• fromcol is the first column in the range

• tocol is the last column in the range

Any range from 1 through 255 can be specified. If no range is specified, the default range is from 1 through 255.

The specified range limit applies both to the columns read for resolution and to the columns containing the resolved values, as follows:

Input for AutoEdit resolution is taken from the specified column range. All columns in the range are processed, whether they contain AutoEdit terms or constants.

Resolved values are limited to the specified range. If the resolved value would normally exceed the range, it is truncated.

The %%$RANGE statement can prevent the shifting of constants and variables that appear subsequent to an AutoEdit variable in the same line. By limiting AutoEdit resolution to a specified range, all constants and variables outside the specified range remain in their original positions regardless of the length of the resolved variables.

A %%$RANGE statement is valid until a new %%$RANGE statement is specified.

DO SET      = %%$RANGE 1 44                                                GLOBAL 
DO SHOUT    = TO OPER                    URGENCY  RCTO282I
     MESSAGE %%$MYVAR                                             WAS DELETED

Functions

The following AutoEdit functions can be specified in a DO SET statement.

You can use a statement such as the following:

DO SET      = %%NDATE = %%$CALCDATE %%WDATE +%%HH

However, do not use a statement such as the following:

DO SET      = %%NDATE = %%$CALCDATE %%.%%WDATE +%%HH

%%$CALCDATE

The %%$CALCDATE function performs date calculations based on a given date. The valid format is

%%$CALCDATE date ± quantity

In this format

• date must be in the format yymmdd

• quantity is a number, or numeric AutoEdit expression, of days to add to or subtract from the date (from 1 through 99999)

DO SET=%%A = %%$CALCDATE %%$RDATE -1

DO SET=%%A = 000131

%%$POOLCOSMOS

The %%$POOLCOSMOS function returns the type of COSMOS database. The valid format is

%%$POOLCOSMOS cosmos_dbname

In this format, cosmos_dbname is the name of the COSMOS database, and is mandatory.

This function returns one of the following types:

• UNKNOWN — The pool is unknown.

• METHOD — The database contains methods of operation.

• PREREQ — The database contains prerequisite conditions.

• WORKING — The database contains working objects.

• NONE — The database is not supported by COSMOS.

DO SET %%COSTYPE = %%$POOLCOSMOS COSSTCSD 
%%COSTYPE is set to WOR KING.

DO SET %%COSTYPE = %%$POOLCOSMOS $GLOBAL
%%COSTYPE is set to NONE.

%%$POOLSTORE

The %%$POOLSTORE function returns the source type of the pool Control-O storage. The valid format is

%%$POOLSTORE gblvar_pname

In this format, gblvar_pname is the Global variable pool name, and is mandatory.

This function returns one of the following types:

• UNKNOWN — The pool is unknown.

• MEMBER — The source is a member in the Control-O Global variable library.

• DATABASE — The pool is a database type.

• SYSPLEX1 — The pool is a database type that can be shared for read-only operations in the Sysplex environment.

• SYSPLEX2 — The pool is a database type that can be shared for read and write operations in the Sysplex environment.

DO SET %%DB_STOR = %%$POOLSTORE COSSTCSD 
%%DB_STOR is set to DATABASE.

DO SET %%DB_STOR = %%$POOLSTORE COSSTCSD
%%DB_STOR is set to SYSPLEX1.

DO SET %%DB_STOR = %%$POOLSTORE $GLOBAL
%%DB_STOR is set to MEMBER.

%%$POOLTYPE

The %%$POOLTYPE function returns the type of pool in Control-O as defined in the list of pools to be loaded (DAGLBLST). The valid format is

%%$POOLTYPE gblvar_pname

In this format, gblvar_pname is the global variable pool name, and is mandatory.

This function returns one of the following types:

• UNKNOWN — Unknown pool.

• INOUT— The database is loaded and updated using the LOADGLOBAL and WRITEGLOABAL commands.

• INPUT — The database can be loaded, but not written to. This type can be used for AutoEdit variables whose initial values are specified in the database and do not require check pointing. The value of each AutoEdit variable can be changed, and new AutoEdit variables can be added to the database, during the INCONTROL product session. However, these new values and variables are not saved when the product session is ended.

• PROT — The database cannot be updated during the INCONTROL product session, and no new AutoEdit variables can be assigned to the database. This type can be used for a database containing AutoEdit variables that are "constants."

• TEMP — The database does not reside on the disk, and therefore cannot be loaded or written to. This type is useful for a database containing AutoEdit variables that do not need to be saved after the INCONTROL product session is ended.

DO SET %%DB_TYPE =%%$POOLTYPE COSSTCSD 
%%DB_TYPE is set to TEMP.

DO SET %%DB_TYPE =%%$POOLTYPE $GLOBAL 
%%DB_TYPE is set to INOUT.

%%$SUBSTR

The %%$SUBSTR function extracts a substring from the input string. The valid format is

%%$SUBSTR strng startpos len

In this format

• strng is the input string from which the substring is extracted.

• startpos is the first character of the input string to extract.

• len is the number of characters to extract.

A string is returned composed of the specified number of characters from the input string beginning with the character in the specified starting position.

startpos and len must be numbers (or numeric AutoEdit expressions) and greater than zero.

• If startpos is greater than the string length, an AutoEdit error message is displayed.

• If (startpos + len – 1) is greater than the string length, the returned value is truncated.

• If the length is unknown you can use the values shown in Table194.

Table 194 Valid %%$SUBSTR Values — Unknown Length

DO SET=%%A = %%$CALCDATE %%$RDATE -1 
DO SET=%%AMON = %%$SUBSTR %%A 3 2

DO SET=%%A = 001130 
DO SET=%%AMON = 11

%%$TIMEINT

The %%$TIMEINT function calculates the time interval between two given times (specified in any order). The valid format is

%%$TIMEINT time1 time2

time1 and time2 are constants or variables in the format yydddhhmmss.

In this format

• yy is the two-digit year

• ddd is the Julian day

• hh are the hours

• mm are the minutes

• ss are the seconds

The resulting time interval is in format dddddhhmmss

• ddddd is the number of days

• hh is the number of hours

• mm is the number of minutes

• ss is the number of seconds

DO SET=%%A = %%$TIMEINT 00120070000 00119060000

DO SET=%%NOW = %%$YEAR.%%$JULDAY.%%$TIME 
IF %%$TIMEINT %%NOW %%PAST GT# 30
DO SHOUT
ENDIF

%%$POS

The %%$POS function locates a substring in a specified string, and indicates the position of the first character in the located substring.

The format of the %%$POS function is

%%$POS substring string

In this format

• substring is the constant or variable that contains the substring for which to search.

• string is the constant or variable that contains the string to search for the specified substring.

DO SET %%A = HAVE A NICE DAY 
DO SET %%B = %%$POS NICE %%A

DO SET %%A = %%$POS ABCD ABCED

%%$ISNUM

The %%$ISNUM function indicates whether a specified string is numeric. In order to be considered numeric, the specified string must contain only numeric characters from 0 through 9, because a numeric string cannot contain letters, blanks, or special characters.

Possible values returned by this function are

• YES — the specified string is numeric

• NO — the specified string is not numeric

The format of the %%$ISNUM function is

%%$ISNUM string

In this format, string is the constant or variable that contains the string to evaluate.

DO SET %%A = %%$ISNUM 1234

DO SET %%A = %%$ISNUM 12PM

%%$PARSE

The %%$PARSE function is a powerful tool that offers extensive string manipulation capabilities in Control-O AutoEdit environment. This function, which is similar to the REXX PARSE command in the TSO/E environment, can be used to analyze and extract information from various AutoEdit strings, such as messages intercepted by Control-O.

The %%$PARSE function parses a specified string (that is, it splits the specified string into substrings) according to a specified template. A template consists of variables and "patterns" that determine the parsing process.

The format of the %%$PARSE function is

DO SET=%%$PARSE string template

In this format

• string is the AutoEdit variable that contains the string to be parsed

• template is the AutoEdit variable or constant that contains the template

DO SET=%%S=THIS IS A SAMPLE STRING 
DO SET=%%T=A1 A2 A3 A4 A5
DO SET=%%$PARSE %%S %%T

The DO SET statements in the above example provide the same result as the following DO SET statements:

DO SET=%%A1=THIS 
DO SET=%%A2=IS
DO SET=%%A3=A
DO SET=%%A4=SAMPLE
DO SET=%%A5=STRING

The parsing process involves the following stages:

1. The string is broken into substrings, from left to right, using the patterns in the template.

2. Each substring is parsed into words, from left to right, using the variable names in the template.

Template elements are

• String Patterns

• Position Patterns

• Variables

• Place holders (Dummy variables)

The rules of parsing are detailed in the following paragraphs.

Parsing Words

Scanning is performed from left to right and words in the string (leading and trailing blanks excluded) are matched one by one with the variables named in the template. The last variable named in the template will contain the remaining part of the string, including leading and trailing blanks.

Up to 30 variable names can be specified in a parsing template.

The following situations can be encountered:

• The number of words in the string matches the number of variables in the template.
  Each of those variables contains one word of the string. The last variable contains the last word in the string including leading and trailing blanks.

• The number of words in the string is smaller than the number of variables named in the template
  The first variables each contain one word of the string and the extra variables receive a value of NULL (a string of 0 character length).

• The number of words in the string is greater than the number of variables in the template
  All variables but the last one contain one word of the string and the last variable named in the template contains the remaining part of the string, including leading and trailing blanks.

DO SET=%%S = THIS IS A SAMPLE STRING 
DO SET=%%T = A1 A2 A3
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS 
DO SET=%%A2 = IS
DO SET=%%A3 = A SAMPLE STRING

Using Dummy Variables (Place Holders)

A single period can be used as a dummy variable in the template. This is useful when the corresponding word in the string does not need to be stored in a named variable.

DO SET=%%S = THIS IS A SAMPLE STRING 
DO SET=%%T = . . . A4.
DO SET=%%$PARSE %%S %%T

DO SET=%%A4 = SAMPLE

Using Patterns in Parsing

Patterns can be included in the template. Their purpose is to break down the string into substrings prior to the actual parsing into words process. Parsing will then be performed, as previously described, on the substrings and not on the original string.

Two types of patterns are available:

• String Patterns – a character string delimited by quotes, to distinguish it from a variable name

• Numeric (Positional) Patterns – a number, signed or unsigned

Using String Patterns

The string is scanned from left to right for a substring that matches the string pattern.

The following situations may occur:

• A match is found, that is, a substring within the string is identical to the given string pattern.

  The original string is divided into two substrings. The first substring (up to, but not including, the string pattern) is parsed into words using the variables named before the string pattern on the template. Parsing continues from the character following the matched string.

  Copy

  DO SET=%%S= THIS IS A SAMPLE STRING 
  DO SET=%%T= A1 A2 'SAMPLE' A3 A4 A5
  DO SET=%%$PARSE %%S %%T

  A match is found since the string SAMPLE is part of the original string.

  The %%$PARSRC System variable, which is discussed in %%$PARSE, can be used to check if all strings specified in the template were matched during the parsing process.

  The original string is divided into two substrings while the matched part of the string is excluded. Parsing of the first substring will use the variables listed before the match on the template while parsing of the second substring will use the variables listed after the match:

  • First substring: THIS IS A

    As a result of parsing

    Copy

    A1=THIS 
    A2=IS A

  • Second substring: STRING

    As a result of parsing:

    Copy

    A3=STRING
    A4=NULL
    A5=NULL

    A match is not found. There is no substring identical to the given string pattern within the string.

    It is assumed that a match is found at the end of the string. The first substring consists of the entire string and it is parsed using only the variables named before the string pattern on the template. Parsing continues from the character following the matched string (the end of the string, in this case).

    Copy

    DO SET=%%S = THIS IS A SAMPLE STRING 
    DO SET=%%T = A1 A2 A3 'EASY' A4 A5 
    DO SET=%%$PARSE %%S %%T

    A match was not found. The string ‘EASY’ does not exist within the original string.

    • First substring: THIS IS A SAMPLE STRING

    As a result of parsing:

    Copy

    A1=THIS 
    A2=IS
    A3=A SAMPLE STRING

    • Second substring: NULL

    As a result of parsing:

    Copy

    A4=NULL 
    A5=NULL

Using Numeric Patterns Within the Template

Numeric patterns are numbers that mark positions in the string. They are used to break the original string into substrings at the position indicated by the number.

The position specified can be absolute or relative:

• An absolute position is specified by an unsigned number.

• A relative position is specified by a signed number (positive or negative) and its purpose it to determine a new position within the string, relative to the last position.

• The last position is one of the following:

  • the start of the string (position1), if the last position was not specified previously

  • the starting position of a string pattern if a match was found

  • the position of the end of the string, if the string pattern was not matched

  • the last position specified by a numeric pattern

• If the specified position exceeds the length of the string, the numeric pattern is adjusted to the end of the string. Similarly, if the specified position precedes the beginning of the string (negative or zero numeric pattern), then the beginning of the string is used as last position.

DO SET=%%S =THIS IS A SAMPLE STRING 
DO SET=%%T = A1 A2 11 A3 A4 A5
DO SET=%%$PARSE %%S %%T

A1=THIS 
A2=IS A

A3=SAMPLE 
A4=STRING 
A5=NULL (0length string)

DO SET=%%S =THIS IS A SAMPLE STRING 
DO SET=%%T = A1 A2 +10 A3 A4 A5
DO SET=%%$PARSE %%S %%T

A1=THIS 
A2=IS A

A3=SAMPLE 
A4=STRING
A5=NULL (0length string)

Using More Than One Pattern and Combining Pattern Types in the Template

Both types of patterns (string and numeric) can be combined in the same template. Up to 30 patterns and up to 30 variable names can be specified.

Scanning of the string proceeds from beginning of the string until the first pattern (if any).

1. String pattern – A match was found

   The substring that precedes the match to the pattern is parsed using the variables named in the template before the pattern, with the last variable receiving the end of the substring, including leading and trailing blanks.

2. String pattern – A match was not found

   Since no match was found in the string, it is assumed that a match is found at the end of the string. The whole string is parsed using only the variables named in the template before the pattern.

3. Numeric pattern (absolute)

   The absolute numeric pattern points to a position within the string when the beginning of the string is position1.

   The string is divided into two substrings.

   • The first substring extends from the beginning of the string and up to, but not including, the position that corresponds to the numeric pattern and it is parsed using the variables named in the template before the pattern.

   • If the absolute numeric pattern specifies a position beyond the length of the string, it is readjusted to the first position beyond the length of the string and the entire string is parsed using the variables named in the template before the pattern.

4. Relative numeric pattern

   The relative numeric pattern (a signed number) specifies a position within the string, relative to the last position.

5. Last position

   It is the beginning of the string when the relative numeric pattern is the first pattern in the template.

   • If the relative numeric pattern is not the first pattern in the template and the previous pattern was numeric, the last position is that specified by the previous numeric pattern.

   • If the relative numeric pattern is not the first pattern in the template and the previous pattern was a string, the last position is that of the starting character of the match (if there was a match) or the position following the end of the string (if there was no match).

As a result of what was just explained:

• If a pattern was not matched until the end of the string and the following pattern is a string pattern, this new string pattern is ignored since the starting point for the new scan is the end of the string.

• If a pattern was not matched until the end of the string and the following pattern is a numeric pattern, then the scan and subsequent parsing will resume from the new position indicated by that numeric pattern.

DO SET=%%S = THIS IS A SAMPLE STRING 
DO SET=%%T = A1 A2 11 A3 6 A4
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS 
DO SET=%%A2 = IS A
DO SET=%%A3 = SAMPLE STRING
DO SET=%%A4 = IS A SAMPLE STRING

A1=THIS 
A2=IS A

A3=SAMPLE STRING

A4=IS A SAMPLE STRING

DO SET=%%S = THIS IS A SAMPLE STRING 
DO SET=%%T = A1 6 A2 +3 A3
DO SET=%%$PARSE %%S %%T

A1=THIS

A2=IS

A3=A SAMPLE STRING

DO SET=%%T = A1 A2 +40 A3 -13 A4 A5 
DO SET=%%S = THIS IS A SAMPLE STRING
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS 
DO SET=%%A2 = IS A SAMPLE STRING
DO SET=%%A3 = %%NULL
DO SET=%%A4 = SAMPLE
DO SET=%%A5 = STRING

DO SET=%%S = THIS IS A SAMPLE STRING 
DO SET=%%T = A1 'A' A2 +3 A3
DO SET=%%$PARSE %%S %%T

DO SET=%%A1 = THIS IS 
DO SET=%%A2 = A S
DO SET=%%A3 = AMPLE STRING