Operator Command Script Tool

COMMAND DOCUMENTATION

OPSCOMMAND™

Operator Command Script Tool

An Enterprise Systems

Purchase Price: $25,000

Annual Maintenance Fee: $15,000

(215) 641-9775

NARRITIVE:

The primary purpose of OPSCOMMAND is to automate/document manual Computer Operator/System Automation procedures within a data center. While several software vendors provide an extensive array of console/operator automation software, none of them offer a product that:

Quickly installs on a Disaster Recovery floor system
Reads like English and can be programmed by almost anyone
Can automate an IPL procedure early on in the IPL process
Is reasonably priced.

OPSCOMMAND is an assembler written program that uses either PARM= and/or SYSIN input to issue an OS/390-MVS command or execute a program logic script command. OPSCOMMAND has it's own scripting language called Execution Directive (ED)which is defined below (see sample and syntax). It can be used to automate/document manual operations within your data center or a disaster recovery site. Typical uses are:

BENEFITS:

Script disaster recovery floor system automation/documentation.
Verify disaster recovery floor system readiness (ie. devices online).
Automate IPL Startup/Shutdown procedures.
Conditionally start/stop CICS, DB2, IMS or other system tasks.
Check system task, job, or device status on a regular basis, i.e. "Health Check".
Automatically notify Computer Operator of abnormal conditions.
Programmatically issue z/OS, OS/390, and MVS Operator commands.
Prompt the Computer Operator for relevant input.
Automate day-to-day Computer Operator routine tasks.
Use automation scripts as documentation.
Issue z/OS, OS/390, or MVS Computer Operator commands.

FEATURES:

Simple, easy to understand English-like commands.
Dynamic system symbolic variable substitutions.
User defined variables.
User defined program labels.
Structured IF, THEN, ELSE, ENDIF logic.
Program logic including looping, GOTO, GOSUB, and RETURN.
Ability to check device status (ONLINE/OFFLINE).
Ability to check task (STC, JOB, TSO) status (ACTIVE/INACTIVE).
Ability to wait, ie. hh:mm:ss.
Dump the active UCB Table, device status, and volser to SYSOUT or dataset.
Use the UCB Table output for Disaster Recovery preparations.
Display messages on the console.
Prompt the Operator for a REPLY and use the value via a user defined variable.
Freeform language layout allows indentation and comments.
Script input provided by PARM=, SYSIN DD, or both.
TEST keyword to nullify execution and display the script.
ECHO keyword to display/suppress script on the Operator Console.
Scripts can be stored in a variety of dataset types including PDS members.
Predefined date and time variables in a variety of standard formats.
Debugging tools within the Script language.

NOTES:

It is important to note that if OPSCOMMAND doesn't recognize input as it's own program script language syntax (ED), then it will take that entire input line and issue it to OS/390-MVS as an operator issued command.

Before I begin, I want you to understand the color scheme I've employed below in the sample and syntax to help illustrate the features of OPSCOMMAND. Below is a color legend for this document:

Program Execution Directives (ED statements) are in bold dark blue.

Program labels are always in bold green.

Variable names are always in bold red.

Comments are always in bold orange.

User specified values are always in bold italicized black.

SAMPLE OPSCOMMAND SCRIPTS (ED Language and MVS Commands):

1. Start a set of CICS Regions named CICSREG1-4.

*------

* Automated CICS Startup procedure (STRTCICS)

*------

SETVAR &RC = 0 Set default return code to zero.

{AskAgain}

WTOR&REPLY,Are you sure you want to start the CICS Regions? (Y/N)

IF &REPLYYES THEN

IF &REPLYNO THEN

WTO Invalid reply, please respecify.

GOTO {AskAgain}

ELSE
GOTO {EXIT}

ENDIF

{Cold?}

WTOR&REPLY,Should I start them COLD or AUTO? (C/A)

IF &REPLYCAND &REPLYA THEN

WTO Invalid reply, please respecify.

GOTO {Cold?}

ENDIF

SETVAR &CICSNAME = CICSREG1

GOSUB {STRTCICS}

SETVAR &CICSNAME = CICSREG2

GOSUB {STRTCICS}

SETVAR &CICSNAME = CICSREG3

GOSUB {STRTCICS}

SETVAR &CICSNAME = CICSREG4

GOSUB {STRTCICS}

GOTO {EXIT}

{STRTCICS}

IF STC(&CICSNAME) = ACTIVE THEN

WTO &CICSNAMEnot started, already active.

SETVAR &RC = 4 Indicate task already active.

ELSE

S &CICSNAME,START=&REPLY Start the region

ENDIF

RETURN

{EXIT}

EXIT &RC

2. Shutdown a set of CICS Regions:

*------

* Automated CICS Shutdown procedure (SHUTCICS)

*------

SETVAR &RC = 0 Set default return code to zero.

{Askagain}

WTOR&REPLY,Are you sure you want to shutdown the Regions? (Y/N)

IF &REPLYYES THEN

IF &REPLYNO THEN

WTO Invalid reply, please respecify.

GOTO {Askagain}

ELSE
GOTO {EXIT}

ENDIF

{TryNorml}

SETVAR &SHUTCICS = 0 Set default return code to zero.

SETVAR &COMMAND = CEMT P SHUT

GOSUB {Execute}Try to shut them down.

IF &SHUTCICS = 0 THENWere any active?

WTO No CICS Regions Active.

GOTO {Exit}Nope, go Exit.

ENDIF

WAIT 00:03:00Waiting 3 minutes

* If any CICS Regions are active, issue CEMT P SHUT I

SETVAR &SHUTCICS = 0 Set default return code to zero.

SETVAR &COMMAND = &COMMAND I

GOSUB {Execute}

IF &SHUTCICS = 0 THENWere any active?

WTO All CICS Regions were shutdown Normal.

SETVAR &RC = 0Set return code.

GOTO {Exit}Nope, go Exit.

ENDIF

{TryImmed}

* Give CEMT P SHUT I a chance to execute.

WAIT 00:03:00Waiting 3 minutes

SETVAR &SHUTCICS = 0 Set default return code to zero.

SETVAR &COMMAND = CANCEL

GOSUB {Execute}

IF &SHUTCICS = 0 THENWere any active?

WTO Some CICS Regions were shutdown Immediate.

SETVAR &SHUTCICS = 4Indicate at least one immediate.

GOTO {Exit}Nope, go Exit.

ENDIF

WTO Some CICS Regions were CANCELLED.

SETVAR &SHUTCICS = 16Indicate at least one cancelled.

GOTO {Exit}Nope, go Exit.

{Execute}

SETVAR &CICSNAME = CICSREG1

GOSUB {ShutCICS}

SETVAR &CICSNAME = CICSREG2

GOSUB {ShutCICS}

SETVAR &CICSNAME = CICSREG3

GOSUB {ShutCICS}

SETVAR &CICSNAME = CICSREG4

GOSUB {ShutCICS}

RETURN

{ShutCICS}

IF STC(&CICSNAME) = ACTIVE THEN

IF &COMMAND = CANCEL THEN

WTO CICS Region &CICSNAME was CANCELLED.

C &CICSNAME Cancel the region.

ELSE

SETVAR &SHUTCICS = 4Indicate at least one active.

F &CICSNAME,&COMMAND Shutdown the region.

ENDIF

RETURN

{EXIT}

EXIT &RC

OPSCOMMAND (ED) USER GUIDE:

Parameters and SYSIN Execution:
If a PARM= value is specified and SYSIN is also specified, the value specified on the PARM= will be stored and executed as the first line of the script and the SYSIN records will be placed after the PARM= line. This is helpful for testing or nullifying a script via operator override. For example:

a)You could execute the COMMAND PROC and specify CMD=TEST.

In this case COMMAND would execute, but all of the input SYSIN statements

would be echoed to the console and no "real" execution would occur. It is important to note that the standard COMMAND PROC has a symbolic variable named CMD= which is used as follows within the PROC:

//COMMAND EXEC PGM=COMMAND,PARM=&CMD

b)You could execute the COMMAND PROC and specify CMD='EXIT 16'

In this case the EXIT 16 would be executed and no SYSIN statements

would execute thereby nullifying the script and the step would end with

a return code of 16.

Symbolic Variable Substitution:

There are three phases of symbolic variable substitution within OPSCOMMAND.

PHASE 1 (script initialization):

Predefined OPSCOMMAND variables are set with run-time values (specified in item #4 below). If you try to set one of these variables a "RESERVED VARIABLE NAME" message will be displayed on the console and in the log and your script will abend with a S0C1.

PHASE 2 (script execution):

A LINK to module ASASYMBM is made to resolve any OS/390-MVS system defined variables. If your application uses any system defined variables they will always be replaced with the value specified in your IEASYMxx member. Your script application can not assign a different value. It is possible to specify a system variable name in your SETVAR statement, but the value you specify will not be resolved during execution. The system defined value will always prevail. Keep this in mind if you're having a problem with variable value substitution. It may be that your script variable name is defined in your IEASYMxx member.

PHASE 3 (script execution):

The final phase of symbolic variable substitution takes place just before each script command is executed. The script statement is scanned for an "&". If an "&" is found an attempt to find the end of the variable name is made. If a valid variable name is found a variable value lookup routine is executed. If the variable is located, the value of the variable is used at the time of command script execution. Please note that every command script line performs variable substitution each time it is executed regardless of the number of times it is executed. This provides the capability to change the value of the variables and ensures each statement executed contains current values, i.e. &TIME, &DATE, and user specified variables.

One last note: The variable name specified to the left of the equals sign (=) on the SETVAR statement is not converted. This ensures that the variable name specified receives the symbolically substituted value specified to the right of the equals sign.

Comments:

a)Blank lines are treated as comments.

b)Any line beginning with an asterisk (*) is treated as a comment.

Take note that the asterisk (*) can be in any column, as long as it's the first character on the line, the entire line will be treated as a comment.

c)Comments are only ECHOed if ECHO is ON.

ED OPSCOMMAND Variables pre-assigned and loaded with current values:

a)&SYSIDSystem Name(i.e. SYSA)

b)&DATEUS DateMM/DD/YYYY

c)&DATEEEuropean DateDD/MM/YYYY

d)&DATEMMilitary DateDD Mon YYYY

e)&JDATEJulian DateYYYYDDD

f)&TIMEUS TimeHH:MM:SS AM

g)&TIMEHUS TimeHH:MM:SS.hh AM

h)&TIMEEEuropean TimeHH.MM.SS AM

i)&TIMEEHEuropean TimeHH.MM.SS.hh AM

j)&TIMEMMilitary TimeHH:MM:SS

k)&TIMEMHMilitary TimeHH:MM:SS.hh

l)JOBIndicates whether this execution is running as a job.
IFJOBTHEN

IF&JOB=TRUE THEN

IF&JOB=FALSE THEN

m)TSOSame as Job, but is it TSO?
IFTSOTHEN

IF&TSO=TRUE THEN

IF&TSO=FALSE THEN

n)TSUIdentical to &TSO.
IFTSUTHEN

IF&TSU=TRUE THEN

IF&TSU=FALSE THEN

o)STCSame as above, but is this execution a STC?
IFSTCTHEN

IF&STC=TRUE THEN

IF&STC=FALSE THEN

p)&JOBNAMEName of job that is running this program execution.

User assigned variables and values:

a)SETVAR&varname=<value>

b)Anything to the left of the equals sign is stored as the variable name.

c)&varname can’t be one of the pre-assigned variables.

d)For the <value>, any characters are valid. Quotes are not required, ever. Trailing blanks are deleted. Be careful not to have the word THEN in your <value> area since it will cause spurious results during IF/THEN logic.

Program Labels:

a)Must be 8 bytes or less long.

b)Must be surrounded by braces {12345678}.

c)Can contain any characters (including spaces) except for braces.

d)Can begin in any column.

e)Everything beyond the ending brace } is considered a comment.

f)A variable can be specified instead of the braces provided the variable contains a value which matches the syntax of a label. For example: You could do the following:

SETVAR &TEST={LABEL1}

GOTO &TEST

…

GOSUB &TEST

…..

{LABEL1}

…..

Branching:

a)GOTO {label}

b)GOSUB {label}

c)RETURN. Return is used in combination with the GOSUB statement. Return will always return you to the next command following the GOSUB statement that called the subroutine.

Example:

IF&SYSID=SYSATHEN

GOSUB {SHUTSYSA}

GOTO {EXIT}

ENDIF

IF &SYSID =SYSB THEN

GOSUB {SHUTSYSB}

GOTO {EXIT}

ENDIF

WTO 'No shutdown performed'

EXIT 16

{SHUTSYSA}

RETURN

{SHUTSYSB}

RETURN

{EXIT}

EXIT 0

The above example could also have been rewritten as:

IF&SYSID=SYSAOR &SYSID =SYSB THEN

GOSUB {SHUT&SYSID }

GOTO {EXIT}
ELSE
WTO 'No shutdown performed'

EXIT 16

ENDIF

EXIT 0

{SHUTSYSA}

RETURN

{SHUTSYSB}

RETURN

{EXIT}

END

IF / THEN / ELSE / ENDIF statements:

a)Formatting is not important. You can have as many leading and trailing blanks that you like. You can indent to arrange your IF statements into logical order.

b)Variables can be placed on either side of the conditional operator. For example:

IF &var1 = &var2 THEN

…

ENDIF

IF YES= &var1 THEN …

…

ENDIF

IF &var1 = YES THEN …

…

ENDIF

c)System values such as DEVICE(…), VOLSER(…), JOB(…) and other OPSCOMMAND defined system runtime values must be specified on the left-hand side of the operator sign. The comparative value must be specified on the right. An example:

IF DEVICE(40AC) = ONLINETHEN

….

ELSE

IF VOLSER(DASD01) = ONLINE THEN

…

ENDIF

d)The value checked begins at the first nonblank character after the conditional operator and continues up to the value THEN. It does not include the preceding blank that is always placed before the word THEN.

e)Comments can be placed after the word THEN.

f)All IF statements must have a corresponding ENDIF statement.

g)ELSE is supported.

h)AND and OR are supported.

i)No parenthesis logic is supported, i.e. IF (A = B) AND (C = D) This is invalid. A solution to this would be to create multiple IF statements or use AND and OR without parentheses.

j)IF can begin in any column and column alignment is not necessary.

k)IF conditions can’t span multiple lines. If necessary, just create a new IF statement on the next line.

l)Valid Operators are:

Equals=

Not Equal or ^= (shift 6 + equals sign)

Greater Than

Greater Than or Equal>= or =>

Less Than

Less Than or Equal<= or =<

Examples:

IF &SYSID = SYSA THEN

IF &DATE = 01/01/2000 THEN

IF &REPLY = YES THEN

ENDIF

ENDIF

ELSE

IF &REPLY = I DON’T KNOW THEN

<statements>
ENDIF

ENDIF

Another version of the IF includes multiple conditions on the same

line.

IF &SYSID = SYSA AND &DATE = 01/01/2000 AND &REPLY = YES THEN

ELSE …

ENDIF

Control block values at run time:

a)You can check to see if a specific JOB is active or not running (inactive) in the system at the time the OPSCOMMAND script is run by issuing one of the following IF statements:

IF JOB(<Jobname>) = ACTIVE THEN…

IF JOB(<Jobname>) = INACTIVE THEN …

b)You can check to see if a specific STC is active or not running (inactive) in the system at the time the OPSCOMMAND script is run by issuing one of the following IF statements:

IF STC(<Stcname>) = ACTIVE THEN

IF STC(<Stcname>) = INACTIVE THEN

c)You can check to see if a specific TSO Userid is active or not logged on at the time the OPSCOMMAND script is run by issuing one of the following IF statements:

IF TSO(<Userid>) = ACTIVE THEN

IF TSO(<Userid>) = INACTIVE THEN

IF TSU(<Userid>) = ACTIVE THEN

IF TSU(<Userid>) = INACTIVE THEN

d)If your not sure whether the task is a JOB, a STC, or a TSO User, you can check to see if it is active or not running (inactive) in the system at the time the OPSCOMMAND script is run by issuing one of the following IF statements:

IF ANY(<Anyname>) = ACTIVE THEN

IF ANY(<Anyname>) = INACTIVE THEN

e)If you want to check to see if your OPSCOMMAND script is running as a STC, JOB, or TSO session, you can issue one of the following IF statements:

IF JOB THEN(assumes TRUE)

IF &JOB = TRUE THEN

IF &JOB = FALSE THEN

IF STC THEN(assumes TRUE)

IF &STC = TRUE THEN

IF &STC = FALSE THEN

IF TSO THEN(assumes TRUE)

IF &TSO = TRUE THEN

IF &TSO = FALSE THEN

IF TSU THEN(assumes TRUE)

IF &TSU = TRUE

IF &TSU = FALSE THEN

f)If you want to check if a specific device is online or offline you can issue one of the following IF statements:

IF DEVICE(<cua>) = ONLINE THEN

IF DEVICE(<cua>) = OFFLINE THEN

g)If you want to check to see if a specific volume is online or offline you can issue one of the following IF statements:

IF VOLSER(<volser>) = ONLINE THEN

IF VOLSER(<volser>) = OFFLINE THEN

WAIT Instruction.

a)The WAIT instruction’s syntax is:

WAIT hh:mm:ss <comments>

Where hh:mm:ss is the amount of time specified in hours, minutes,

and seconds you want to wait beginning right now.

b)Anything specified to the right of the hh:mm:ss is considered a comment.

Example (Shutdown CICSPROD):

F CICSPROD,CEMT P SHUT

WAIT 00:03:00 Wait 3 minutes for shutdown

IF STC(CICSPROD) = ACTIVE THEN

F CICSPROD,CEMT P SHUT I

WAIT 00:03:00 Wait another 3 minutes

IF STC(CICSPROD) = ACTIVE THEN

C CICSPROD

WAIT 00:01:00 Give it time to die.

ENDIF

WTO’s and WTOR’s.

a)A message to the Operator can be sent via the WTO … command. No operands other than the message text is required.

b)A message to the Operator with a reply is sent via the WTOR command. A variable is specified as part of the message text followed by a comma, then the message text. This variable can be checked for values later in the program.

Example:

{RuSURE?}

WTO Are you sure you want to Shutdown CICS?

WTOR &REPLY, Please reply YES or NO

IF &REPLYYES THEN

IF &REPLYNO THEN

WTO Invalid Reply, Please Respecify

GOTO {RuSURE?}

ELSE
GOTO {EXIT}

ENDIF

F CICSPROD,CEMT P SHUT

…….

…...

…

{EXIT}

Terminating the program via the EXIT or END commands.

a)Program termination occurs when the command processor runs out of statements, i.e. reaches the end of the input source program. This condition will end with a return code of zeroes.

b)Program termination occurs when an END statement is encountered. The END statement will end with a return code of zeroes.

c)The EXIT command will also terminate the program, but it can pass a return code if specified. The syntax for the EXIT command is:

Syntax:

EXIT <optional return code> Comments

Examples are:

EXIT(will end with a return code 0)

EXIT Comments (will end with a return code 0)

EXIT 0 Comments(will end with a return code 0)

EXIT 16(will end with a return code 16)

SETVAR&var=8(set a variable to 8)

EXIT&var(will end with a return code 8)