MAPBUF: Map buffer declaration

The syntax of the MAPBUF call is:

FUNC=MAPBUF

Requests a declaration of the buffer header and its entries. This function is required if any other IEWBUFF functions are used and may be specified only once per TYPE and PREFIX combination in the assembler source module containing the macro expansion.

TYPE={CUI | ESD | LIB | RLD | IDRU | IDRL | IDRZ | IDRB | SYM | TEXT | NAME | XTLST | MAP | PINIT | PMAR}

Specifies a record buffer for B_CUI, B_ESD, B_LIB, B_RLD, B_IDRU, B_IDRL, B_IDRZ, B_IDRB, B_SYM, and B_MAP class data items; a byte-oriented buffer for B_TEXT and PMAR data; a record buffer for name lists (NAME) (see GETN: Get names); a data buffer for an extent list (B_XTLST) that is returned to the caller after a program module is loaded (see LOADW: Load workmod); and a record buffer for part initializers (B_PARTINIT) (see binder-defined class B_PARTINIT). ADATA and all compiler-defined text classes must use TEXT for buffer type.

SIZE=nnn | BYTES=nnnn

SIZE=nnn Specifies the size of the buffer in bytes for text data buffers and in records for all other buffer types.

BYTES=nnnn Specifies the maximum number of bytes available for the buffer, including the header, regardless of the TYPE specified. This parameter is an alternative to the SIZE parameter and is used when a single block of storage is shared by several different buffers.

Code the values for SIZE and BYTES as integer values in the range 0-2**31.

Note: Values provided here should be treated as estimates of the amount of data that can be returned. The macro will add additional space for overhead, but that, too, is only an estimate. The amount of data actually returned is always reported by the entry count in the output parameter list and the entry length as defined in the buffer header for each type of buffer.

HEADREG={headreg | USERHEADREG}

Specifies a value from 1-15 indicating the register number to equate to the base register used for the buffer header dummy section (DSECT). If the default, USERHEADREG, is used, IEWBUFF does not use a specific register to base the buffer header DSECT. Instead, you define a symbol named IEWBxyz_BASE, where xyz is 3 characters representing the TYPE, as the base register for the DSECT. The PREFIX value will be used to differentiate IEWBxyz_BASE as well as other symbols in the buffer declaration. For example, using TYPE=CUI,PREFIX=V2 will result in V2_IEWBCUI_BASE.

The following codes must be substituted for xyz in the register names, depending on the TYPE= keyword value used.

TYPE:   CUI   IDRB  IDRL  IDRU  IDRZ  LIB  NAME  PINIT  TEXT  XTLST  PMAR
xyz:    CUI   IDB   IDL   IDU   IDZ   LIB  BNL   PTI    TXT   XTL    PMR

ENTRYREG={entryreg | USERENTRYREG}

Specifies a value from 1-15 indicating the register number to equate to the base register used for the buffer entry DSECT. If the default, USERENTRYREG, is used, IEWBUFF does not use a specific register to base the buffer entry DSECT. Instead, you define a symbol named xyz_BASE, where xyz represents the TYPE (see the codes under HEADREG), as the base register for the DSECT. The PREFIX value will be used to differentiate xyz_BASE as well as other symbols in the buffer declaration. For example, using TYPE=CUI,PREFIX=V2 will result in V2_CUI_BASE.

VERSION=1 | 2 | 3 | 4 | 5 | 6 | 7

Each version of the binder API supports all earlier buffer format versions, so you do not need to modify your program to call a more recent level of the binder API. It is recommended that new programs specify the latest VERSION available when they are written because the default is VERSION=1. Using the default, or any older version, is likely to make it impossible for the binder to return all of the data in the requested record; only compatible fields will contain returned data.

New buffer versions were introduced in the following releases:

• VERSION=1 DFSMS/MVS Release 1
• VERSION=2 DFSMS/MVS Release 3
• VERSION=3 DFSMS/MVS Release 4
• VERSION=4 OS/390® DFSMS Version 2 Release 10
• VERSION=5 z/OS® Version 1 Release 3
• VERSION=6 z/OS Version 1 Release 5
• VERSION=7 z/OS Version 1 Release 10

PREFIX=string

Specifies that each generated symbol in the buffer declaration is prefixed with the provided string, followed by an underscore (_). The PREFIX value is needed for differentiating the field names of two versions of the same record type. For instance, if you use Version 2 and Version 3 of the ESD mapping in the same program, you can use "V2" and "V3" respectively, for each PREFIX. The mappings are generated with the differentiating prefixes (for example, V2_ESD_TYPE and V3_ESD_TYPE), and you can then refer to any field name in either mapping without ambiguity.

Note: The PREFIX value should not be enclosed by apostrophes and must not exceed 32 bytes.