Job variables are available as a separate software product. Like job and user switches, they too are useful in information exchange
between user programs and the operating system, or
between different user programs.
Compared with switches, however, job variables offer the following additional facilities:
They can be declared as monitoring job variables when a program is called. As such, they are automatically supplied with status and return codes, which provide information on program status and termination action, as well as on potential runtime errors.
At the operating system or program level, they can be loaded with records of up to 256 bytes in length (128 bytes in the case of monitoring job variables). Because of this, they are able to communicate more detailed information than job or user switches, which are only capable of switching between ON and OFF status.
In contrast to job and user switches, they can also be modified by jobs running under different user IDs.
Before a COBOL program can access a job variable, the variable must first be assigned to it via a link name, in a similar way to a file. The SET-JV-LINK command performs this function for job variables. Its format is described in the “Commands” [3] and “Job Variables” [7] manuals, and an example of its usage is contained in the following section. The link name to be specified in the command is apparent from the declarations in the COBOL program (see below).
COBOL2000 supports access to job variables with the following language elements (see “COBOL2000 Reference Manual” [1]):
Link names and program-internal mnemonic names for job variables, declared in the SPECIAL-NAMES paragraph of the Environment Division:
Job variables can be assigned via link names, and the statements of the PROCEDURE DIVISON can refer to them via their mnemonic names (see below). Link names and mnemonic names for job variables can be declared with phrases in the following format:JV-jvlink IS mnemonic-name
jvlink specifies the link name for the job variable. When the link name is formed, an “*” is prefixed to jvlink as its first character; the resulting link name is therefore *jvlink. For this reason, the string jvlink must not be longer than 7 bytes. mnemonic-name declares the program-internal mnemonic name for the job variable. The ACCEPT and DISPLAY statements of the Procedure Division:
ACCEPT...FROM mnemonic-name
reads the contents of the job variable that is associated (in the SPECIAL-NAMES paragraph) with mnemonic-name. The data is transferred left-justified into the receiving item specified in the ACCEPT statement, according to the length of this item. If the item is longer than 256 bytes (128 bytes in the case of monitoring job variables), it is space-filled on the right; if it is shorter, the contents of the job variable are truncated on the right during the transfer to conform to the length of the item.
DISPLAY...UPON mnemonic-name
writes data in the job variable that is associated (in the SPECIAL-NAMES paragraph) with mnemonic-name.
The size of the data transfer is determined by the length of the sending items or literals of the DISPLAY statement, provided the maximum record length of 256 bytes (128 bytes for monitoring job variables) is not exceeded. If the total number of characters to be transferred is greater than the maximum record length, the record is truncated to the maximum length when it is transferred.
When data is written to a monitoring job variable it should be noted that the first 128 bytes of the job variable are protected by the system against write access. Thus, only that part of the record starting at position 129 is written to the job variable, beginning at position 129 of the variable.
If a COBOL program which includes statements for job variables is run on a BS2000 installation that does not support job variables, these statements are not executed. After an ACCEPT statement, the receiving item contains the characters “/*”, starting in column 1. The first attempt to access a job variable causes message COB9120 to be output to SYSOUT.
A failed access to a job variable in a BS2000 installation that does support job variables causes message COB9197 to be output to SYSOUT (see table 10 in section "Program termination").
Example 8-4
Communication via a job variable
In the following interactive job, the job variable CONTROL.RUN is used both by a COBOL program and at command level. Depending on the contents of the job variable, the program can go through various processing branches, updating the contents of the job variable if required. A different job - even one under another user identification - can access this job variable, provided the job variable was cataloged with the command
CREATE-JV ...,USER-ACCESS=ALL-USERS.
Extract from the program:
...
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
TERMINAL IS T
JV-UPDATE IS FIELDJV. —————————————————————————————————— (2)
...
DATA DIVISION.
WORKING-STORAGE SECTION.
01 DATE-TODAY PIC X(6). —————————————————————————————— (3)
01 CONTENTS-JV. ——————————————————————————————————————————— (4)
05 DATE-UPDATE PIC X(6).
05 FILLER PIC X(20).
05 NUM-UPDATE PIC 9(4).
...
PROCEDURE DIVISION.
ACCEPT CONTENTS-JV FROM FELDJV. ———————————————————————— (5)
ACCEPT DATE-TODAY FROM DATE.
IF DATE-UPDATE NOT EQUAL DATE-TODAY ———————————————————— (6)
PERFORM WORK
ELSE PERFORM ALREADY-UPDATED.
...
WORK.
...
MOVE DATE-TODAY TO AKT-DAT. (7)
ADD 1 TO NUM-UPDATE. |
DISPLAY CONTENTS-JV UPON FIELDJV. (7)
...
ALREADY-UPDATED.
DISPLAY "END OF UPDATE"
UPON T.
...
|
(1) | The job variable CONTROL.RUN is assigned to the COBOL program called after it (PROG.WORK-1) via the link name *UPDATE. |
(2) | The link name *UPDATE and the (program-internal) mnemonic name FIELDJV are declared for the job variable in the SPECIAL-NAMES paragraph of PROG.WORK-1. |
(3) | DATE-TODAY is reserved as the receiving item for the date. |
(4) | The receiving item for the contents of the job variable is declared. It contains subordinate items for recording the most recent update date (DATE-UPDATE) and an updating counter (NUM-UPDATE). |
(5) | ACCEPT transfers the contents of the job variable FIELDJV to CONTENTS-JV. |
(6) | Depending on whether the update date (DATE-UPDATE) of the job variable corresponds to the current date (DATE-TODAY), different processing procedures are executed in the program. |
(7) | At the end of processing, the items DATE-UPDATE and NUM-UPDATE are updated and written back to the job variable with DISPLAY CONTENTS-JV... . |
(8) | The job variable is read at operating system level: it contains the date and the number of the most recent update. |