IBMPXSF — PL/I extract side file routine

Purpose

Usage notes

• IBMPXSF can only be used on z/OS non-CICS.
• IBMPXSF is AMODE(31) and RMODE(ANY). It expects to be entered in AMODE(31). It returns using a BSM. Routines that call IBMPXSF must access it by a dynamic load (for example, issuing a LOAD SVC, using CEELOAD, COBOL dynamic call, PL/I fetch, C fetch). IBMPXSF must not be linkedited with any other load modules, otherwise it will cause upward compatibility problems when moving from one release of Language Environment to another.
• IBMPXSF expects to be called from a Language Environment-conforming program.
• R12 must point to the CAA on entry.
• R13 must point to a DSA with a valid NAB.
• The user is responsible for freeing each of the three storage areas (address of compilation information, address of statement table, and address of expanded program source that are returned in the output structure) using Language Environment free heap storage services (for example, CALL CEEFRST(address,feedback-code) or CALL CEEVFRST(address,feedback-code)). If the storage is not freed by the user, it will be implicitly freed by Language Environment at enclave termination.
• The minimum Enterprise PL/I compiler level supported by IBMPXSF is V4R1M0.
• The following compiler options are required to ensure that the SYSDEBUG side file contains the complete expanded program source and statement table:
  • TEST(SEPARATE) – the ALL and NOHOOK sub-options are also recommended but not required.
  • GONUMBER(SEPARATE) – required to produce the statement table in the SYSDEBUG side file.
  • MACRO or PP(MACRO) is required if there are %INCLUDE statements in the source (using the MACRO suboption CASE(ASIS) will leave the case of the source unchanged).
  • LISTVIEW(AFTERALL) – required if include files, EXEC CICS® commands, or SQL code are in the source.

Compilation information

1. The address and length of the compilation information are returned in the output structure.
2. This maps to the following side file header

   +00 H      Length of side file header info in halfwords
   +02 H      Version of side file header
   +04 CL3    Eyecatcher (‘SID’)  
   +07 CL17   YYYYMMDDHHMMSSTTT (compile date and time)
   +18 CL6    VVRRMM (compiler version/release/modification level)
   +1E H      # of include files
   +20 CL8    YYYYMMDD (compiler build date; version >= 2 only)

Statement table

1. The address and length of the statement table are returned in the output structure.
2. The statement table consists of one or more block statement structures which represent the blocks in the compile unit.
3. Each block statement structure may contain one or more statement sections depending on the length of the code for the block.
4. The format of each block statement structure entry is as follows (may be repeated as needed):
   1. Block statement header

      +00 F 		Offset of block entry within compile unit
      +04 F 		Length of generated code for block

   2. Statement section (one for every x’8000’ bytes of code in the block)

      +08 F 			Section end offset (from the start of statement table)
      +0C XL6		Struct statement table entry (repeated until section end offset is reached)
      			+00 XL2 		Statement offset (including reserved flags)
      			+02 XL4 		Statement number and index
      						BL10 		file index (should be 0 if the correct compiler options were used)
      						BL17 		statement number
      						BL5  		reserved

   3. End block delimiter

      +nn XL6 		X‘0E0E0E0E0E0E’

5. The end of the statement table may contain up to 8 bytes of padding.
6. When there are multiple statement sections for a block, the statement offset requires a base increment of x’8000’ for each statement section after the first one to determine the actual offset into the block.
7. To determine the statement offset value, AND the 2 bytes with x’7FFE’ to remove the high order and low order bits.
8. To determine the offset into the module, the block offset value from the statement block header must also be added to the statement offset value.
9. The following is the layout for the block statement structure:
   Figure 1. Structure for the block statement

        +-------------------------------------------------+
        | Block offset           | Block Code             | 
        |                        | Length                 |
        +-------------------------------------------------+
        | Section end            |
        | offset                 |
        +--------------------------------+
        | Statement descriptor           |
        +--------------------------------+     
        | Statement descriptor           |
        +--------------------------------+
        | Statement descriptor           |                                                |
        +--------------------------------+
              ...
              ...
         Repeat descriptors to section end
   
         New section appears here (if block length >= x’8000’)
         Else block end string (x’0E0E0E0E0E0E’)
   
         New block statement structure appears here if needed
         Else end of stmt table (with up to 8 bytes of padding) 

10. The following displays the entry layout for the statement table:

    Byte 1		Byte 2		Byte 3	Byte 4		Byte 5	Byte 6
    1	Bits: 14		1	10		17			5
    x	statement offset value		x	file index		statement number			x

Expanded program source

1. The address and length of the expanded program source are returned in the output structure.
2. The data is mapped as follows:

   +00 F 		number of records
   +04 F 		max LRECL
   Expanded source code (repeated as needed)
         +08 CL2+n struct 			variable length strings
               +00 H 					LRECL
               +02 CLn        statement   

3. The expanded source code does not contain the statement numbers; the source lines should be numbered sequentially starting with 1.