Using the IEWBUFF macro

The IEWBUFF macro generates, initializes, and maps the data buffers used during binder processing. The IEWBUFF macro provides four functions:

MAPBUF to generate a buffer declaration for one data type
GETBUF to acquire storage for one buffer
INITBUF to initialize a buffer header for one buffer
FREEBUF to release storage for one buffer.

Figure 1. IEWBUFF function summary

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

                    ,FUNC=MAPBUF
                         {,SIZE=size | BYTES=bytes}
                         [,HEADREG={headreg | USERHEADREG}]
                         [,ENTRYREG={entryreg | USERENTRYREG}]
                         [,VERSION=version]
                         [,PREFIX=prefix_chars]

                    ,FUNC=GETBUF
                         [,GM_RETCODE=gm_retcode]

                    ,FUNC=INITBUF

                    ,FUNC=FREEBUF
                         [,FM_RETCODE=fm_retcode]

MAPBUF provides a mapping macro for the buffer header and for one entry record. It also defines constant values, in the calling program, associated with the specified data type. These are used by the GETBUF, INITBUF, and FREEBUF calls to determine the interface version and number of records or bytes in the buffer.

Note: If it is necessary to have more than one copy of a particular buffer in your program (for example, both Version 1 and Version 2 buffers), you must code the PREFIX parameter to vary the generated data names.

GETBUF and INITBUF are used to prepare a buffer for use, and FREEBUF is used to release the buffer after usage. GETBUF and FREEBUF are not needed if you specifically provide storage for the buffer.

A single block of storage can be used for different buffer types if it is as large as the largest buffer type used and the buffer header is initialized for the correct data type before the buffer is used. When multiple buffers are to share the same storage you should specify the buffer capacity in bytes rather than SIZE. Some buffer types (such as ESD and RLD) vary considerably from release to release. You should specify the latest buffer version to be sure that all new binder features are available. The default is VERSION=1.

This section describes the parameters for each function call. No separate return codes, other than those generated by GETMAIN and FREEMAIN, are returned by the IEWBUFF macro. The invocation environment is the same as that of the IEWBIND macro (see Setting the invocation environment).