IGZXAPI — COBOL file and runtime information query routine

Purpose

IGZXAPI is a loadable module, which can be called to query information about a running COBOL program. Below is sample code for calling the routine:

   LOAD  EP=IGZXAPI
   ..
   LA    R1,[parm area]   see note below 
   BALR  R14,R15         
   ..

Note:

[parm area] is an array of addresses. Only the first address entry is used, which points to XINFO, XINFO2, and everything below DSECT. (In this description, a DSECT is also known as an "information structure".) End of change

Syntax

void IGZXAPI

R1 (input): Points to the parameter area.
(output): The data structure (XINFO or XINFO2) is populated. Registers R2-R13 remain unchanged.

File information query

To query file information of a running COBOL program (language member identifier 4).

The DSECT XINFO is the information structure to communicate with the file information routine. The caller should take note of the following data fields:

XNREST: This is the number of files remaining to be returned from the query.; On the first call, the caller has to set this field to zero. This indicates the first call. The routine returns information of the first file; XNREST is set by the routine to the number of files remaining.; On subsequent calls, the caller should not modify any of the data fields returned from the previous call. The routine will return information of the next file.; When the last file has been returned, this field is set to zero by the routine.
XNFILES: This is an output field, and indicating the total number of files. This is returned by the routine in the first call, and remains unchanged in subsequent calls.
XDSA: This is the DSA address of the COBOL program being queried. This is set by the caller in the first call, and must not be modified in subsequent calls.; Only COBOL files in this program are returned.
XLEN: Length of the XINFO data structure. Caller should set this field to the length of XINFO, 124.; Caller should provide storage for XINFO.
XFNCODE: This is the function code. Set to 1 by caller for file information query.

All other data fields are output from the routine. The caller should not modify any of these fields, including the ones marked as reserved for future use.

Note: SD files are not physical data files. They don't actually exist until the sort is active. The current sort record, if present, is provided by way of the runtime information query (in XINFO2).

Runtime information query

To query general runtime information. The DSECT XINFO2 is the information structure to communicate with the runtime information routine. On input:

XDSA2: The DSA address of the COBOL program to be queried.
XLEN2: Length of XINFO2.; Caller should set this to 48.; Caller should provide memory for this data structure.
XFNCODE2: This is the function code. Set to 2 for general runtime information query.

All other fields are output from the routine. The calling convention is the same as the file information routine. End of change

CWSA address query

To find the COBOL working storage area address of a given entry point. DSECT XINFO3 is the information structure to communicate with the CWSA address query routine. On input:

XEP3: The entry point address of the COBOL program to be queried.
XLEN3: Length of XINFO3.; Caller should set this to 40.; Caller should provide memory for this data structure.
XFNCODE3: This is the function code. Set to 3 for WSA address query.
R12: Register 12 points to the Language Environment CAA.

All other fields are output from the routine. The calling convention is the same as the file information routine. This routine requires the Language Environment to be up and running. End of change

File status update

To update the file status variable of the specified file. DSECT XINFO4 is the information structure. On input:

XDSA4: The DSA address of the COBOL program.; The file, whose file status variable is to be updated, must be defined in this program.
XLEN4: Length of XINFO4.; Caller should set this to 76.; Caller should provide memory for this data structure.
XFNCODE4: This is the function code. Set to 4 for file status update.
XFILENM: COBOL FD name of the file.
XFSTATUS: Address of the buffer area containing the new file status data.; Data in this area will be copied to the file status variable in the COBOL program. No checking is done on this data. Exactly XFSLEN bytes will be copied from this buffer to the file status variable.
XFSLEN: Length of the XFSTATUS buffer area.
R12: Register 12 points to the Language Environment CAA.

There is no output field from this routine. The calling convention is the same as the file information routine. This routine requires the Language Environment to be up and running. End of change

Layout of the information structure

The layout of the information structure is described below.

--------------------------------------------------------------------------------
*        1         2         3         4         5         6         7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
XINFO    DSECT
XFNCODE  DS    F       Input: Function code, =1 for file information
XFILLER0 DS    A         reserved
XSIG     DS    F         X'C0B00501'
XVER     DS    H         Version of this information structure block
XLEN     DS    H       Input: Length of this data structure, 120
XDSA     DS    A       Input: DSA of COBOL program to be querired
*
XNFILES  DS    H         Total number of files
*
* BNREST is input field during the first call, set it to zero;
*        on return, contains the remaing number of files to go
*
XNREST   DS    H       Input in first call, set to zero 
*
XDCB     DS    A         Address of DCB or ACB
XDDNAME  DS    A         Address of DDNAME (8 characters)
XFNAME   DS    A         Address of file name (30 characters)
*
XCFLAG1  DS    X         Compile time information flags
XSOPTNL  EQU   X'80'      SELECT OPTIONAL
XRCDSPN  EQU   X'40'      Record format spanned
XBLKED   EQU   X'20'      Record format blocked
XLINAGE  EQU   X'10'      Linage is specified
XLINFOOT EQU   X'08'      Linage FOOTING is specified
XLINTOP  EQU   X'04'      Linage TOP is specified
XLINBOT  EQU   X'02'      Linage BOTTOM is specified
XBUFUSE  EQU   X'01'      Buffer usage indicator
*
XCFLAG2  DS    X         Compile time information flags
XEXTFILE DS    X'80'      External file 

FILLER2  DS    X          Reserved
FILLER3  DS    X          Reserved
*
XORG1    DS    X         File Type
XVSAM    EQU   X'01'      VSAM
XLSEQ    EQU   X'02'      Line Sequential
XQSAM    EQU   X'03'      QSAM
*
XORG2    DS    X         File Organization
XORGSEQ  EQU   X'01'      Sequential
XORGIND  EQU   X'02'      Indexed
XORGREL  EQU   X'03'      Relative
*
XACCESS  DS    X         File Access Mode
XACCSEQ  EQU   X'01'      Sequential
XACCRAN  EQU   X'02'      Random
XACCDYN  EQU   X'03'      Dynamic
*
XRECFM   DS    X         Record Format
XRECFIX  EQU   X'01'      Fixed
XRECVAR  EQU   X'02'      Variable
XRECUND  EQU   X'03'      Undefined
*
XRFLAG1  DS    X         Run time information flags 1
XOPOPT   EQU   X'80'       OPEN, missing optional file
XOPREV   EQU   X'40'       OPEN REVERSED     (valid when XOPENED)
XOPNOREW EQU   X'20'       OPEN, NO REWIND   (valid when XOPENED)
XCLNOREW EQU   X'10'       CLOSE, NO REWIND  (valid when XCLOSED)
XCLLOCK  EQU   X'08'       CLOSE, LOCK       (valid when XCLOSED)
XCLREMOV EQU   X'04'       CLOSE FOR REMOVAL (valid when XCLOSED)
XSOKACT  EQU   X'02'       A successful action since OPEN
*
XRFLAG2  DS    X         Run time information flags 2
XPEND    EQU   X'20'       OPEN or CLOSE pending
XSEOF    EQU   X'10'       Previous READ hit end of file
XEOP     EQU   X'08'       End of page
XMOPTNL  EQU   X'04'       OPTIONAL FILE MISSING
XADVAFT  EQU   X'02'       WRITE AFTER ADVANCING x LINES
XADVBEF  EQU   X'01'       WRITE BEFORE ADVANCING x LINES

FILLER4  DS    H         Reserved
*
XFMODE   DS    X         Current file mode
XOPENED  EQU   X'01'       Opened
XCLOSED  EQU   X'02'       Closed
XNEVERO  EQU   X'03'       Never opened
*
XOMODE   DS    X         Information about OPEN (valid when XOPENED)
XOPIN    EQU   X'01'       OPEN INPUT
XOPOUT   EQU   X'02'       OPEN OUTPUT
XOPIO    EQU   X'03'       OPEN IO
XOPEXT   EQU   X'04'       OPEN EXTENDED
*
XCMODE   DS    X          Information about CLOSE (valid when XCLOSED)
XCLFILE  EQU   X'01'       CLOSE 
XCLUNIT  EQU   X'02'       CLOSE REEL/UNIT
*
XLASTREQ DS    X          Last operation on file
XLASTRD  EQU   X'01'       READ 
XLASTWRT EQU   X'02'       WRITE
XLASTRWT EQU   X'03'       REWRITE
XLASTSTR EQU   X'04'       START
XLASTDLT EQU   X'05'       DELETE
XLASTOPN EQU   X'06'       OPEN
XLASTCLO EQU   X'07'       CLOSE
*
* Various LINAGE values
*
XLNLING  DS    F          Linage
XLNFOOT  DS    F          Linage footing
XLNTOP   DS    F          Linage top
XLNBOT   DS    F          Linage bottom
XLNCTR   DS    F          Linage counter
*
* File Status
*
XFSTAT   DS    X          File status, in 2 hex bytes
XVSMCOD  DS    X          VSAM feedback code
XVSMRET  DS    X          VSAM return code
XVSMFUNC DS    X          VSAM function code
*
XADVVAL  DS    F          Write after/before advancing value
*
XRECLEN  DS    F          Record length; max length for variable rec
XBLKLEN  DS    F          Block size
XRECLAD  DS    A          Address of address of record
XBUFAD   DS    A          Address of buffer provided by DFSMS
*
XPNAME   DS    A          Address of program name
XPNAMLEN DS    H          Program name length
FILLER5  DS    H          Reserved
*
FILLER6  DS    4F         Reserved
*
*        1         2         3         4         5         6         7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
--------------------------------------------------------------------------------
*
*        1         2         3         4         5         6         7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
XINFO2   DSECT
XFNCODE2 DS    F       Input: Function code, =2 for RT information
FILLER10 DS    A         reserved
XSIG2    DS    F         X'C0B00501'
XVER2    DS    H         Version of this information structure block
XLEN2    DS    H       Input: Length of this data structure, 48 
XDSA2    DS    A       Input: DSA of COBOL program to be querired
*
FILLER11 DS    X         Reserved
FILLER12 DS    X         Reserved
FILLER13 DS    X         Reserved
*
XRFLAG4  DS    X         Run Time Flags
XINSORT  EQU   X'02'      Sort is active
XISMAIN  EQU   X'01'      Program is main
*
XSDREC   DS    A         Address of active sort record
XSDLEN   DS    F         Sort record len
FILLER14 DS    4F        Reserved
*
*
*        1         2         3         4         5         6         7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
--------------------------------------------------------------------------------
*
*        1         2         3         4         5         6         7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
XINFO3   DSECT
XFNCODE3 DS    F       Input: Function code, =3 for WSA address query
FILLER30 DS    A         reserved
XSIG3    DS    F         X'C0B00501'
XVER3    DS    H         Version of this information structure block
XLEN3    DS    H       Input: Length of this data structure, 40 
*
XEP3     DS    A       Input: Entry point address of COBOL program
XWSA     DS    A         Address of WSA
*
FILLER31 DS    4F        Reserved
*
*
--------------------------------------------------------------------------------
*
*        1         2         3         4         5         6         7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
XINFO4   DSECT
XFNCODE4 DS    F       Input: Function code, =4 for file status update
FILLER40 DS    A         reserved
XSIG4    DS    F         X'C0B00501'
XVER4    DS    H         Version of this information structure block
XLEN4    DS    H       Input: Length of this data structure, 76
*
XDSA4    DS    A       Input: DSA address of COBOL program
XFILENM  DS    CL30      File Name. COBOL FD name of the file.
FILLER42 DS    CL2
XFSTATUS DS    A         Addr of buff containing new File Status data
XFSLEN   DS    F         Length of XFSTATUS buffer
*
FILLER31 DS    4F        Reserved
*
*
*        1         2         3         4         5         6         7
*
* 345678901234567890123456789012345678901234567890123456789012345678901
*
--------------------------------------------------------------------------------

Usage notes

R13 must point to the caller’s DSA.
R14 is the return address.
R15 is the entry point address of IGZXAPI.
On return from the routine, R15 is set to zero if the call is successful. R15 is set to non-zero if the call is not successful and the requested information is not available.