Programming examples for binder APIs

The sample program in Examples for binder regular API is intended to show how the binder application programming interface could be used by an application written in System/390* assembler language. Although the task is arbitrary, the examples shows the sequence in which the APIs can be invoked in order to accomplish the task. The program is linked non-reentrant in RMODE=24.

The program invokes the binder to include an arbitrary module (IFG0198N) from a library (ddname=LPALIB), scans through its ESD entries one section at a time, and writes the ESD entries to an output file (ddname=MYDDN). The program specifies all three types of lists on the STARTD call to show how they could be used. It also demonstrates the use of the SETO call to set an option during the dialog. Use a SYSPRINT DD to see the calls made to the binder.

The program is divided into numbered sections. Additional commentary on each of the numbered sections follows:
Section
Number Description
1
This is standard MVS™ entry point linkage. Register 12 is saved in the message exit specification so that the exit routine can obtain addressability to its own code and data.

The BASR instruction clears the high-order byte (or bit) of register 12. This was done because the message user exit routine is entered in 31-bit addressing mode and uses register 12 as its base register. If the main program is entered in 24-bit addressing mode, the high-order byte of register 12 will contain extraneous bits unless it is cleared.

2
This logic opens the output file.
3
These specifications of the IEWBUFF macro obtain storage for the ESD and NAMES buffers and initialize them. Mapping DSECTs for the buffers are provided at the end of the program.
4
The STARTD call establishes a dialog with the binder. It is always required and sets the dialog token for use in subsequent binder calls. The dialog token must be initialized to binary zero before its first usage.
The example uses all three list parameters on the STARTD call:
  • FILES allows us to assign a ddname to the binder's print file. Note that when using the binder regular API, any required binder files (those whose ddnames do not appear on binder control statements or as macro parameters) must have ddnames assigned in this way.
  • EXITS allows us to specify a message exit routine that receives control, in this case, if the message severity is greater than 0. The exit routine appears at the end of this program.
  • OPTIONS allow us to specify one or more options that will apply throughout the binder dialog. In this example, option TERM is set to "Y".
5
This logic creates a binder workmod with INTENT=ACCESS. The dialog token, DTOKEN, is a required input parameter. The workmod token, WTOKEN, is set by the binder for use on subsequent calls. The workmod token must be initialized to binary zero prior to the CREATEW call.
6
SETO is used to set the LIST option to "ALL". Since the workmod token is provided on the macro, LIST is set at the workmod level and is valid only until the workmod is reset.
7
This step includes member IFG0198N from library LPALIB, using ddname and member name to identify the module to be included.
8
The GETN call retrieves from the workmod the names of all sections in module IFG0198N. Names are returned in the names buffer, IEWBBNL, and COUNTN is set to the number of names returned. TCOUNT is set to the total number of names in the module, regardless of the size of the buffer. For this example, the two counts should be the same. The size of the buffer is controlled by the second IEWBUFF macro in section 17, which specifies SIZE=50. This provides space for up to 50 names. Since IFG0198N has fewer than 50 sections, the GETN request reaches end of file before filling the buffer. That is why it ends with return code 4, and why TCOUNT and COUNTN are the same.
9
For each name returned in the names buffer, the program issues one GETD call to obtain the ESD data. If a large module had been processed, both the GETN and GETD calls would have been processed in a loop to accommodate the possibility that there are more names or ESD records than could be obtained in a single buffer. This example, however, assumes that all ESD entries can be returned in a single GETD call.

Assuming that any ESD entries were returned for the designated section, the program scans through the buffer and writes each ESD record to the output file designated by ddname MYDDN. It is possible, however, that the item does not exist and that the named section must be bypassed.

10
DELETEW removes the workmod from binder storage. PROTECT=YES, the default, merely indicates that the delete should fail if the workmod has been altered by the dialog. Since INTENT=ACCESS, no alteration was possible, and PROTECT=YES is ineffective.
11
ENDD ends the dialog between the program and the binder, releasing any remaining resources, closing all files, and resetting the dialog token to the null value.
12
A call to IEWBUFF (FUNC=FREEBUF) frees the NAME and ESD buffers previously obtained by IEWBUFF.
13
Once the intended task is completed, the program closes the output file and releases its buffer storage.
14
This logic represents standard MVS return linkage to the operating system.
Note that an error in the program might cause control to be passed to the ERREXIT label, where clean-up processing takes place. Three clean-up items are accomplished here:
  1. If the NAME and ESD buffers were obtained previously through IEWBUFF, they are released here. IEWBUFF (FUNC=FREEBUF) is invoked to accomplish this.
  2. If the binder dialog is outstanding (that is, if the STARTDialog API was invoked previously), it is ended here. Note that the workmod is deleted when the dialog is ended.
  3. If the output DCB is open, it is closed and its storage is released.
15
Many macro parameters require variable length character strings. To the binder, a variable length string consists of a halfword length followed by a byte string of the designated length. The halfword length value does not include the two bytes for the length field itself.

This section illustrates the definition of some of those variable length character string constants.

16
The STARTD function call specified all three types of lists: FILES, EXITS and OPTIONS. Each of these list parameters is defined here. Although each list contains only a single entry, additional entries could have been specified by incrementing the fullword count and adding another three-item specification at the end of the list.
17
The DCB for the output file is defined for this program only. The file is not shared or used in any way by the binder.
18
This use of the IEWBUFF macro provides DSECT maps for both the ESD and names buffers. Registers 6 and 7 are dedicated as base registers for the ESD buffer header and entries, respectively. Similarly, registers 8 and 9 are dedicated to the names buffer.

Note that you must code the IEWBUFF macro within a CSECT. Also note that the VERSION parameter in IEWBUFF must match the value of the VERSION parameter in the GETN and GETD binder regular APIs.

19
The message exit routine receives control, in this example, any time a message is issued by the binder with a severity of four or greater. This routine receives control in the binder's AMODE (31). It must provide capping code to switch to AMODE(24), if necessary, then back to the binder's AMODE before returning. Refer to z/OS MVS Programming: Assembler Services Guide for a discussion of capping.

The exit routine is copying the message from the binder's message buffer to the output file. It could have prevented the binder from issuing the message by returning a 4 in register 15.