Chapter 21: JCL API

MSS provides a number of API calls that you can call from a COBOL program to carry out JCL-type tasks.

List of API Calls

Calls available are:

MFJZABND, to abend the current job step
MFJZLOG, to write a message to the syslog and/or the joblog.
MFJZS099, to issue an SVC 99 call.

Definitions of API Calls

This section describes each JCL API call in detail.

MFJZABND

MFJZABND abends the current job step with a system or user abend.

Syntax:

call "MFJZABND" using abend-type abend-code

Parameters:

abend-code	pic 9(8) comp	The abend code.
abend-type	pic 9(8) comp	Type of abend to occur; 0 indicates a user abend; 1 indicates a system abend..

Example:

Example 21-1. To cause an abend with user abend 1004:

77  abend-code                 pic  9(08) comp.
77  abend-type                  pic 9(08)  comp. 
...
move 0 to abend-type
move 1004 to abend-code
call 'MFJZABND' using abend-type abend-code

Example 21-2. To cause an abend with system abend SDED (note that system abend codes are always hex not decimal):

77  abend-code                 pic  9(08) comp.
77  abend-type                  pic 9(08)  comp. 
...
move 1 to abend-type
move h"ded" to abend-code
call 'MFJZABND' using abend-type abend-code

MFJZLOG

MFJZLOG writes a message to the syslog and/or the joblog.

Syntax:

call "MFJZLOG" using msg-dest msg-len msg-txt

Parameters:

msg-dest	pic 9(8) comp	Message destination; 1 sends it to the joblog; 2 sends it to the syslog,; 0 sends it to both.
msg-len	pic 9(8) comp	Length of the message text.
msg-txt	x(118)	Text of the message.

Comments:

The message length should be less than 108 bytes if you wish to keep the whole message on one line.

Note:

Where the characters in positions 6 ,7, 8 and 9 of your message string are digits (as is the case in the examples below) MFJZLOG assumes that you are supplying your own message code. In all other circumstances, it prepends your message with the default code, 'JCLXM0000I '.
If the message string contains the character 'I' at position 10 (as is the case where your original string is prepended with JCLXM0000I) the default user exit casumxit will exclude it from the system log.

Example:

Example 21-1. To write “MyMsg0001P Hi there!” to both the system log and the job log:

77 msg-dest                     pic 9(8) comp.
77  msg-txt                     pic x(118).
77  msg-len                     pic  9(08) comp.

move 0 to msg-dest
move "MyMsg0001P Hi there!" to msg-txt
move 20 to msg-len
call 'MFJZLOG' using  msg-dest msg-len msg-txt

Example 21-2. To write “MyMsg0001P Hi there!” to just the job log:

77 msg-dest                     pic 9(8) comp.
77  msg-txt                     pic x(118).
77  msg-len                     pic  9(08) comp.

move 1 to msg-dest
move "MyMsg0001P Hi there!" to msg-txt
move 20 to msg-len
call 'MFJZLOG' using  msg-dest msg-len msg-txt

MFJZS099

MFJZS099 issues an SVC 99 call.

Syntax:

call "MFJZS099" using s99rb caller-id returning retcode

Parameters:

s99rb	See below	SVC 99 request block mapped by IDAS99RB.CPY. You may use IDAS99TU.CPY to assist you in the construction of the Text Units (TUs).
caller-id	See Below	While using this parameter is recommended, it is not a requirement for COBOL programs compiled as INTs and GNTs. For non-COBOL programs, it is required and is used by the SVC 99 handler to interpret format of addresses and CHARSET of the character data. Binary data must always in z/OS (Big-Endian) format.
retcode	pic 9(8) comp	SVC 99 return code that would have been placed in the general purpose register 15. All other error and info codes are stored in SVC99RB.

Comments:

SVC99 uses the high-order bit of a TU (Text Unit) address to interpret it as the last TU address in the TU address array.

When the calling program is compiled with NOAMODE, the high order bit of a TU address will not be interpreted as an indication of the last address in the TU pointer array. In this case, you have two options:

Make sure the last TU address is indicated by a value of either x’80000000’ or x’00000080’. This will keep the source compatible with the host. If either of these could potentially be a legitimate address on the computer you are running on, then the following option is the only alternative.
Specify a last address value of your choice in the extension portion of the SVC99 Request Block (S99RB).

If the calling program is compiled with AMODE, no changes are required. It is recommended that you use a null address to signify the last address. For example, set TU last address to x’80000000’.

Example:

A program running with NOAMODE:

copy idas99rb
        replacing ==()== by ==s99rb==.
    copy idas99tu
        replacing ==()== by ==s99tu==. 
    01 caller-id.
       03 caller-id-char               pic x(04) value 'S099'.
       03 caller-id-ptr                pointer.*> ptr to s99rb
       03 caller-id-bin                pic 9(8) comp value 1.
       03 caller-id-float              comp-1 value 1.
    01 .
       03 tu-ptr-list.
          05 tu-ptr-ddn                pointer.
          05 tu-ptr-dsn                pointer.
          05 etc                       pointer. 
          05	                       pic x(4) value s99rb-last-ptr-val-x4-val. 
           
     move low-values to s99rb
     move s99rb-len-mf-ext to s99rb-len
     move s99rb-last-ptr-val-x4-val to s99rb-last-ptr-val-x4
     set s99rb-s99tu-array-ptr to address tu-ptr-list
     set caller-id-ptr to address s99rb

     call 'MFJZS099' using  s99rb caller-id returning retcode
     if retcode = 0 
        *> SVC99 ok            
     else      
        *> SVC99 not ok – check for errors
     end-if

A program running with AMODE:

copy idas99rb
        replacing ==()== by ==s99rb==.
    copy idas99tu
        replacing ==()== by ==s99tu==. 
    01 caller-id.
       03 caller-id-char               pic x(04) value 'S099'.
       03 caller-id-ptr                pointer.*> ptr to s99rb
       03 caller-id-bin                pic 9(8) comp value 1.
       03 caller-id-float              comp-1 value 1.
    01 .
       03 tu-ptr-list.
          05 tu-ptr-ddn                pointer.
          05 tu-ptr-dsn                pointer.
          05 etc                       pointer. 
          05	                       pic x(4) value x'80000000' 
           
     move low-values to s99rb
     move s99rb-len-mf-ext to s99rb-len
     move s99rb-last-ptr-val-x4-val to s99rb-last-ptr-val-x4
     set s99rb-s99tu-array-ptr to address tu-ptr-list
     set caller-id-ptr to address s99rb

     call 'MFJZS099' using  s99rb caller-id returning retcode
     if retcode = 0 
        *> SVC99 ok            
     else      
        *> SVC99 not ok – check for errors
     end-if