GETC: Get compile unit list

GETC: Get compile unit list

z/OS MVS Program Management: Advanced Facilities
SA23-1392-00

GETC returns data which is mapped to a new CUI buffer format (Version 6). The COMPILEUNITLIST parameter determines which data is returned.

The syntax of the GETC call is:

[symbol]

IEWBIND

FUNC=GETC

,VERSION=version
[,RETCODE=retcode]
[,RSNCODE=rsncode]
,WORKMOD=workmod
[,COMPILEUNITLIST=compileunitlist]]
,AREA=buffer
,CURSOR=cursor
,COUNT=count

FUNC=GETC

Requests that data from items in a workmod be returned to a specified location.

VERSION=6

Specifies the version of the parameter list to be used (6 or higher).

RETCODE=retcode — RX-type address or register (2-12)

Specifies the location of a fullword integer that is to receive the return code returned by the binder.

RSNCODE=rsncode — RX-type address or register (2-12)

Specifies the location of a 4-byte field that is to receive the reason code returned by the binder. Reason codes are documented as a sequence of 8 hexadecimal digits.

WORKMOD=workmod — RX-type address or register (2-12)

Specifies the location of an 8-byte area that contains the workmod token for this request.

COMPILEUNITLIST=compileunitlist

Determines which data is returned. If COMPILEUNITLIST is specified, one record for each compile unit in a list of compile units will be returned. If COMPILEUNITLIST is omitted, one record of each of all compile units will be returned. The header record, the first compile unit record, is built when the cursor is zero.

The compile unit list is a structure:

Count    DC    F'5'   List with 5 entries
List     DS    5F     Returned by GETN

Note: compileunitlist must be composed of values returned in BFNL_6_SECT_CU resulting from a GETN TYPE=SECTION,VERSION=6 API call.

When INTENT=ACCESS is specified in the CREATEW API call, information about the input module (the target module of the GETC call) is placed in the header record. This information includes the program object version and the source of the input module (data set name or path name, ddname, and member name).

AREA=buffer — RX-type address or register (2-12)

Specifies the location of a CUI buffer to receive the data. The binder returns data until either this buffer is filled or the specified items have been completely moved. See IEWBUFF - Binder API buffers interface assembler macro for generating and mapping data areas for information on buffer handling.

CURSOR=cursor — RX-type address or register (2-12)

Specifies the location of a fullword integer that contains the position within the items where the binder begins processing. Specifying a zero causes the binder to return the header record, the first compile unit record. The information is provided on the DASD location of the program object. The cursor value is modified before returning to the caller.

When no compile unit list is provided, the cursor is an index into an ordered list of all CUI entries that can be returned. If the application does not modify the cursor during the retrieval process, multiple calls return all CUI records in the order by CU number because the buffer is full. When a compile unit list is provided, the cursor is an index into that application-provided list. CUI records are returned in the order specified in the CU list. If the application still does not modify the cursor during the retrieval process, multiple calls continue with subsequent entries in the list because the buffer is full. End of data is signalled when the end of the application-provided list is reached.

COUNT=count — RX-type address or register (2-12)

Specifies the location of a fullword that receives the number of CUI records returned by the binder.

Processing notes

The CURSOR value identifies an offset into the requested data beginning with 0. It is both an input and output parameter. On input to the service, the cursor specifies the first byte to return. On exit from the service, it is updated to the next byte for continued sequential retrieval if not all data has yet been retrieved.

For load modules and program object formats at a compatability level prior to z/OS® V1R5 , a compile unit is the same as a section. For z/OS V1R5 compatible modules, a compile unit corresponds to a single object module. Each compile unit in a workmod is assigned a unique number; however, this assigned number may change when a module is rebound. Furthermore, the compile unit number will be zero for all binder generated sections (IEWBLIT or section 1, for example).

Return and reason codes

The common binder API reason codes are shown in Table 1.

Return Code	Reason Code	Explanation
00	00000000	Normal completion. There might be additional data that did not fit in the buffer.
04	83000800	End of data. Some data might have been returned in the buffer, but no more is available.
04	83000801	No section names exist. No data was returned.
04	83000810	Cursor is negative or beyond the end of the specified item. No data was returned.
08	83002342	Some of the passed compile unit numbers do not exist in workmod. Data for the valid compile units is returned.
12	83000102	Workmod was in an unbound state.

Parameter list

If your program does not use the IEWBIND macro, place the address of the GETC parameter list in general purpose register 1.

Table 1. GETC parameter list

`PARMLIST`	`DS`	`0F`
	`DC`	`A(GETC)`	Function code
	`DC`	`A(RETCODE)`	Return code
	`DC`	`A(RSNCODE)`	Reason code
	`DC`	`A(WORKMOD)`	Workmod token
	`DC`	`A(CULIST)`	Compile unit list
	`DC`	`A(BUFFER)`	Data buffer
	`DC`	`A(CURSOR)`	Starting position
	`DC`	`A(COUNT+X'80000000')`	Data count
`GETC`	`DC`	`H'64'`	GETC function code
	`DC`	`H'6'`	Interface version number