Functions

The mfpubspl interface data structure contains several constant fields you can use to populate the API function field. These are documented in the structure itself, under a section labeled Function. The name of each field describes the function itself. There are single OPEN and CLOSE functions, but for each spool file there are the following functions:

START
Greater than, Less than, Greater than or equal to, and Less than or equal to. These functions allow you to establish a position in the files, relative to the key(s) provided in the associated key data area.
GET NEXT
Retrieve the next record in logical sequence, determined by the chosen index.
GET PREV
Retrieve the previous record in logical sequence.
GET UNIQUE
Retrieve the record matching the key(s) provided in the associated key data area.

For COBOL programs, the function names will be prefixed with the string specified in the replacing clause; see Program Requirements for an example. For PL/I programs, the function names will be prefixed with mfpubspl_.

COBOL example

...
      *=================================================================
      *    Function
      *=================================================================

           03  ()-FUNC                       PIC X(8).
              88 ()-FUNC-OPEN                        VALUE 'OPEN'. 
              88 ()-FUNC-OPEN-IO                     VALUE 'OPEN-IO'. 
              88 ()-FUNC-CLOSE                       VALUE 'CLOSE'.
      *             Get SPLJOB - Next, Previous, or Unique (i.e. by key)
              88 ()-FUNC-GN-JOB                      VALUE 'GN-JOB'.
              88 ()-FUNC-GP-JOB                      VALUE 'GP-JOB'.
              88 ()-FUNC-GU-JOB                      VALUE 'GU-JOB'.
...

PL/I example

...	
    /*
       mfpubspl_FUNC_CONSTANTS
    */
    DCL mfpubspl_FUNC_OPEN                CHAR(8) VALUE('OPEN');
    DCL mfpubspl_FUNC_OPEN_IO             CHAR(8) VALUE('OPEN-IO'); 
    DCL mfpubspl_FUNC_CLOSE               CHAR(8) VALUE('CLOSE');
    /*          Get SPLJOB - Next, Previous, or Unique (i.e. by key) */
    DCL mfpubspl_FUNC_GN_JOB              CHAR(8) VALUE('GN-JOB');
    DCL mfpubspl_FUNC_GP_JOB              CHAR(8) VALUE('GP-JOB');
    DCL mfpubspl_FUNC_GU_JOB              CHAR(8) VALUE('GU-JOB');
...

To specify a function, set the value of one of these fields to the function field defined in the mfpubspl data structure. For example, in a COBOL program, if you have included mfpubspl.cpy in your program replacing () with WS-API:

set WS-API-FUNC-GN-JOB to TRUE.

Or in a PL/I program:

mfpubspl_FUNC = mfpubspl_FUNC_GN_JOB;

A typical sequence of calls could contain the following functions:

Seq no. Function Purpose
1 OPEN To open the spool files
2 STGT-JOB To position on a particular SPLJOB record (e.g., start, key greater than)
3 GN-JOB To get the next logical SPLJOB record
4 STGE-DSN To position on the first SPLDSN record for the job retrieved in (3) above. The JESYSMSG record (i.e. the job log) is always the first SPLDSN record for a job, with a DD number of zero. If there are no associated OUTPUT statements, the Output sequence number will be zero, otherwise there will be a record for each associated OUTPUT statement, with a non-zero Output sequence number.
5 GN-DSN To get the next logical SPLDSN record
6 CLOSE To close the files

Sequence number 5 would be repeated until no more SPLDSN records exist for the job (API return code 3 – Job number has changed), followed by a repeat of sequence numbers 2, and/or 3, to retrieve more job records.