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(4).
              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.