HP 3000 Manuals HP 3000 Manuals
SETJCW
Creates or assigns a value to a job control word (JCW) variable.
Syntax
SETJCW jcwname delimiter value [{+} value]
[{-} ]
Parameters
jcwname The name of a new or existing user-defined or
system-defined 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 -. Whatever character is used
delimits 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).
* 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 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:
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 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 RANGE--LEGAL 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:
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.
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
Related Information
Commands DELETEVAR, SETVAR, SHOWJCW, SHOWVAR
Manuals Appendix A, "Predefined Variables in MPE/iX"