GETN: Get names

GETN returns the names of each section or class in the workmod, a count of the total number of sections or classes, and the compile unit (CU) numbers for each section. The names returned also include names generated by the binder to represent private code sections, unnamed common, SEGTAB and ENTAB sections for overlay programs, and any other sections created by the binder. GETN can only be performed on a bound workmod.

The syntax of the GETN call is:

[symbol]

IEWBIND

FUNC=GETN

[,VERSION=version]
[,RETCODE=retcode]
[,RSNCODE=rsncode]
,WORKMOD=workmod
[,AREA=buffer]
,CURSOR=cursor
,COUNT=count
,TCOUNT=tcount
[,NTYPE={SECTION | CLASS}]

FUNC=GETN: Specifies that a count of the number of sections in a workmod and, optionally, the names of each section, be returned to a specified location.
VERSION=1 | 2 | 3 | 4 | 5 | 6 | 7 | 8: Specifies the version of the parameter list to be used. The default value is VERSION=1.
Note: This version must match the version you specify with the IEWBUFF macro when you define the buffer passed on this call.
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 hexadecimal string that is to receive the reason code returned by the binder.
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.
AREA=buffer — RX-type address or register (2-12): Specifies the location of a buffer to receive the names. This buffer must be in the format for section names (TYPE=NAME). See IEWBUFF - Binder API buffers interface assembler macro for generating and mapping data areas and Binder API buffer formats for information on buffer definition.
Section names will be moved until either the buffer is filled or all names have been moved. This keyword is optional. If it is not specified, only the number of section names in the workmod will be returned.
CURSOR=cursor — RX-type address or register (2-12): Specifies the location of a fullword integer that contains the position relative to the start of the list of names where the binder should begin processing. Specifying a zero for this argument causes the binder to begin processing at the beginning of the list. Offsets are specified in records and are relative to the start of the list. The cursor value is modified before returning to the caller.
COUNT=count — RX-type address or register (2-12): Specifies the location of a fullword integer in which the binder will indicate the number of names actually returned in the buffer.
TCOUNT=tcount — RX-type address or register (2-12): Specifies the location of a fullword integer in which the binder will indicate the total name count. TCOUNT indicates the total number of sections or classes in the workmod, not just those returned in the buffer.
NTYPE={SECTION | CLASS}: Specifies the type of names to be returned and counted. SECTION causes the names of all sections in the workmod, including special sections, to be returned. In addition, the compile unit CU numbers are provided for buffer version 6 or higher. CLASS causes the names of all classes in the workmod containing data to be returned. The value for NTYPE can be abbreviated as S or C. SECTION is the default.

Processing notes

The CURSOR value identifies an index into the requested data beginning with 0 for the first name list entry. The name list buffer formats defined in Binder API buffer formats contain an entry length field in their headers. Multiplying the cursor value by the entry length provides a byte offset into the data. CURSOR is both an input and output parameter. On input to the service, the cursor specifies the first item to return. On exit from the service, it is updated to the index of the next sequential name list entry if not all entries have yet been retrieved.

Return and reason codes

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

Return Code	Reason Code	Explanation
00	00000000	Normal completion.
04	83000800	An end-of-data condition was detected. Some data might have been returned in buffer. There is no message associated with this condition.
04	83000801	No section names exist. No data was returned.
08	83000750	The buffer is not large enough for one record. No data is returned.
04	83000810	Cursor is negative or beyond the end of the specified item. No data was returned.
12	83000102	Workmod is unbound. GETN request rejected.

Parameter list

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

Table 1. GETN parameter list

`PARMLIST`	`DS`	`0F`
	`DC`	`A(GETN)`	Function code
	`DC`	`A(RETCODE)`	Return code
	`DC`	`A(RSNCODE)`	Reason code
	`DC`	`A(WORKMOD)`	Workmod token
	`DC`	`A(BUFFER)`	Data buffer
	`DC`	`A(CURSOR)`	Starting position
	`DC`	`A(COUNT)`	Data count
	`DC`	`A(TCOUNT)`	Total count
	`DC`	`A(NTYPE+X'80000000')`	Name type to return and end-of-list indicator
`GETN`	`DC`	`H'60'`	GETN Function code
	`DC`	`H'version'`	Interface version number
`NTYPE`	`DC`	`CL1'C'`	'C' = class; 'S' = section