SETJCW



SETJCW

     Creates or assigns a value to a Job Control Word (JCW) variable.  (CM)

SYNTAX


SETJCW jcwname delimiter value [{+} value]
{-}

PARAMETERS


jcwname The name of a new or existing user- or Job Control
Word (JCW). You can use "@" to specify all currently
defined JCWs.

You may not specify the system-reserved JCWs,
HPMINUTE, HPHOUR, HPDAY, HPDATE, HPMONTH, or HPYEAR.

delimiter One or more punctuation characters or spaces, except
% and ! and -. Whatever character is used will
delimit the name and value.

value One of the following

An octal number between %0 and %177777, inclusive.

A decimal number between 0 and 65,535, inclusive.

An MPE/iX-defined JCW value mnemonic (OK for 0; WARN
for 16,384; FATAL for 32,768; SYSTEM for 49,152) or
an offset value of a mnemonic (OK3 for 0 + 3, etc.).

The name of an existing JCW.

All specified values must be in the range of 0 to
65,535, inclusive. If the option + or - is used,
the result of the indicated operation must also be
within the range of 0 to 65,535, inclusive.

OPERATION

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


JOB CONTROL WORDS (JCW)

     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 are in MPE/iX are now called as system
variables of type JCW. You may delete user-created
variables. You may modify the two system-defined variables
CIERROR and JCW.

The SETJCW command creates or assigns variables of type JCW,
which function exactly as Job Control Words did in the MPE
V/E system.

The SETVAR command creates and assigns, 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 will succeed. If the new
value is out of range for a JCW, the variable type will be
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 will 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.

The contents of a JCW may be displayed using 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

Bit Value Step Value Mnemonic
------------------------------------------------------
00 0 OK
01 16,384 WARN
10 32,768 FATAL
11 49,152 SYSTEM

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 will be generated, and the value of the JCW
will remain 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
will be 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 MPE/iX's 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 will not recognize the term as a valid
mnemonic, and will treat 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 will
result 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 will cause the following
error message to be displayed

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

SYSTEM-DEFINED JCWS

     MPE/iX has two system-defined JCWs that are created for each
job and session JCW and CIERROR. The JCW named JCW is
always initialized to zero at the beginning of the job or
session and will remain 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 lists system-reserved JCWs and possible values

HPDAY Day of the week. The possible integers are 1
through 7. Sunday is indicated by 1. Saturday is
indicated by 7.

HPDATE Day of the month. The possible integers are 1
through 31.

HPMONTH Month of the year. The possible integers are 1
through 12. January is indicated by 1.

HPYEAR Year of the century. The possible integers are 00
through 99.

HPHOUR Hour of the day. The possible integers are 0
through 23.

HPMINUTE Minute of the hour. The possible integers are 0
through 59.

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 will set the value of the 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.

!SETJCW CHEKPROGSTAT=OK
!CONTINUE
!RUN CHEKPROG ** Prevents abort in case of errors. *
** Edit, verify, and count valid *
! IF CHEKPROGSTATJCW to 0. *
!ENDIF
!RUN FINALRPT ** Produce final report. *

EXAMPLE(S)

     To set the Job Control Word CURR1 to 100, enter

     SETJCW CURR1,100     ** The comma (,) is the delimiter **
                          ** and is used instead of an "=". **

     To set CURR1 to the value of the mnemonic WARN, enter

     SETJCW CURR1/WARN    ** The slash (/) is the delimiter **
                          ** and is used as an "=".         **

     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

ADDITIONAL INFORMATION

Commands:   SETVAR, SHOWJCW, SHOWVAR

Manuals :   Appendix A, "Predefined Variables in MPE/iX," of the
            MPE/iX Commands Reference Manual (32650-90003)