SETJCW

Operation Notes

A job control word (JCW) is a flag that allows information to be passed between processes within a single job or session. There are three forms of JCWs: system-defined, user-defined, and system-reserved.

Job control words in MPE/iX are classed as system variables of type JCW. You may delete user-created variables. You may modify the two system-defined variables CIERROR and JCW. Refer to appendix A, "Predefined Variables in MPE/iX," for a list of system-defined variables.

The SETVAR command creates and assigns variables too, but variables created or assigned with SETVAR are not of type JCW and cannot function as true job control words.

If you create or assign a value to a variable using the SETJCW command and later reassign its value using the SETVAR command, the reassignment succeeds. If the new value is out of range for a JCW, the variable type is changed to that of an ordinary user-defined variable:

  SETJCW PROGCNTR 0
 ....
  SETVAR PROGCNTR 65536
 JCW VARIABLE RECLASSIFIED AS A STANDARD VARIABLE
 (CIWARN 8126)

PROGCNTR is now a user-defined variable and does not function as a job control word.

JCWs can be tested against specific values. The user can use IF and WHILE conditional statements that act according to the results of these tests. The user-defined JCWs can also be set to user-selected values by a process so that they reflect the completion of steps within that process. System-defined JCWs can be used to determine whether certain events have occurred within MPE/iX.

The values in the system-reserved JCWs can be inspected by the user, but not altered.

To display the contents of a JCW use the SHOWJCW or the SHOWVAR command.

JCW Values and Mnemonics

JCWs may be assigned any positive integer value between 0 and 65,535 inclusive (%0 and %177777). These values are treated as 16-bit unsigned integers by MPE/iX, since all 16 bits are used for numeric information, rather than using the most significant bit as a sign bit.

MPE/iX treats the two most significant bits of a JCW in a special way: the bits define "bases" or "steps" of 16K each. Each of these steps is given a mnemonic to simplify references to it or to the numbers between steps. If the 14 least significant bits are considered to be zeros, the two "step" bits, step value (in decimal), and mnemonic have the following relationship:

It is important to remember that these mnemonics are not the names of JCWs. They cannot be used as user-defined JCW names.

You may use a combination of mnemonics and numbers to indicate numeric values between steps. If you specify a mnemonic and a number with no intervening spaces, an implied addition takes place. For example, WARN3 has a value of 16,387, since it is WARN (16,384) plus 3. The value of the mnemonic plus the appended number value may not exceed 65,535. Again, no valid value of the form, mnemonic[number], may be used as a valid user-defined jcwname. An explicit addition or subtraction can also be specified, using a + or - sign, as in OK+7 (7) or WARN-4 (16,380). A mnemonic may also be added to another mnemonic, as in WARNFATAL.

The result of a mathematical operation must be in the range of 0 to 65,535, inclusive; if the number is out of range, an error message is generated, and the value of the JCW remains unchanged. When the result of an operation is greater than the value of the next "step", the JCW value displayed by the SHOWJCW command will be the mnemonic of the higher step plus any offset. For example, the value OK16385 is displayed as WARN1.

User-Defined JCWs

User-defined JCWs are created and initialized to a value by the SETJCW command or PUTJCW intrinsic. The JCW name contains alphanumeric characters and must begin with an alphabetic character. The name can be up to 255 characters long. The value assigned to the JCW must be in the range of 0 to 65,535, inclusive.

The SETJCW command scans the MPE/iX variable table for the name of the specified JCW (jcwname). If the specified name is found, the JCW is set to value. If the jcwname is not found, it is created and set to value. The term "value," as used here, means the explicitly stated or the computed value.

You may not begin a JCW name with the mnemonic names OK, WARN, FATAL, or SYSTEM, unless you append a number to the mnemonic such that the computed value exceeds 65,535 (for example, WARN999999, or SYSTEM200000). If the computed value exceeds 65,535, MPE/iX does not recognize the term as a valid mnemonic, and treats it as the name of a JCW. This restriction is intended to eliminate the possibility of an ambiguous JCW assignment. For example, it is unclear from the following two commands whether the JCW X is equal to 100 or to 0:

 SETJCW OK=100
 SETJCW X=OK

Naming a JCW with a mnemonic or predefined JCW value results in an error message, as in the following example:

  SETJCW OK200=1982
 JCWNAME CANNOT BE A VALID JCW VALUE (CIERR 1725)

Negative or out-of-range JCW values cause the following error message to be displayed:

 VALUE NOT IN RANGELEGAL RANGE IS 0 TO 65535 (CIERR 1712)

System-Defined JCWs

JCW and CIERROR are MPE/iX system-defined JCWs created for each job and session. The JCW named JCW is always initialized to zero at the beginning of the job or session and remains zero, unless fatal errors occur, or unless the user changes the value. There are two special values for the system-defined JCW:

 %140000 (System 0) Program aborted per user request.
 
 >%140000      Program terminated in an error state.

The CIERROR JCW tracks command interpreter (CI) errors.

CIERROR is set to zero at the beginning of the job or session. If a command interpreter error occurs, CIERROR is updated to reflect the current CI error message number.

Users are advised not to alter the values of the CIERROR and JCW job control words. User-defined JCWs should be used for information the user wishes to control.

The following example shows the use of the CIERROR JCW:

  LISTF
  ^
 UNKNOWN COMMAND NAME. (CIERR 975)
  SHOWJCW CIERROR
 CIERROR = 975 
  RUN
    ^
 NO PROGRAM FILE SPECIFIED. (CIERR 600) 
  SHOWJCW CIERROR
 CIERROR = 600 
 : 

System-Reserved JCWs

The system-reserved JCWs are HPMINUTE, HPHOUR, HPDAY, HPDATE, HPMONTH, and HPYEAR. They contain system-assigned minute, hour, day, date, month, and year information. If the user attempts to assign values, an error message is displayed. You can retrieve the values in these JCWs with the FINDJCW intrinsic. The values can also be tested if the JCW is used with an IF, WHILE, SETJCW, SETVAR, or CALC command. The names of the system-reserved JCWs are reserved.

The following describes system-reserved JCWs and possible values:

Conditional Execution Using JCWs

JCWs are typically used to control the flow of batch jobs, based on events that take place within the job. You can use the MPE/iX IF/THEN (ELSE/ELSEIF), ENDIF, and WHILE/ENDWHILE statements to test JCW values.

The following example illustrates a conditional execution function. The sample job runs a program that edits, verifies, and counts valid transactions (CHEKPROG). If no fatal errors occur, the job runs the program SHIPPROG, which schedules shipments. The job then runs FINALRPT, which produces a final report. If fatal errors do occur, the CHEKPROG sets the value of the JCW CHEKPROGSTAT to FATAL, and SHIPPROG is not run. Instead, ERRORRPT is run, which produces an error report. A final report is also produced by FINALRPT.

You can use the SHOWVAR command to display the value of any specified variable or any group of variables, including JCW type variables. You can display the contents of a system-defined JCW with the SHOWJCW command only if you specify the jcwname.

In the following example the CONTINUE command prevents an abort in case of errors; the RUN CHEKPROG edits, verifies, and counts valid transactions; the IF command specifies that if no fatal errors occur, schedule shipments; the RUN command schedules the shipments; the ELSE command produces the error report and resets the JCW to 0; and the RUN command produces a final report:

 !SETJCW CHEKPROGSTAT=OK
 !CONTINUE
 !RUN CHEKPROG
 ! IF CHEKPROGSTAT<FATAL THEN
 !  RUN SHIPPROG
 ! ELSE
 !  SHOWJCW CHEKPROGSTAT
 !  RUN ERRORRPT
 !ENDIF
 !RUN FINALRPT

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command.

Examples

To set the job control word CURR1 to 100, and use a comma (,) as the delimiter instead of an =, enter:

 SETJCW CURR1,100

To set CURR1 to the value of the mnemonic WARN, and use a slash (/) as the delimiter instead of an =, enter:

 SETJCW CURR1/WARN

To use an arithmetic operation to set one JCW value relative to another, enter:

 SETJCW NEWJCW=LASTJCW + 56

To schedule a full backup job on Saturdays and a partial backup job on the other days of the week, you could create a user command:

 SETJCW FRIDAY=6
 IF HPDAY = FRIDAY THEN
     SCHEDJOB FULLBKUP;IN=1
 ELSE
     SCHEDJOB PARTBKUP;IN=1
 ENDIF