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:
- If the NAME and ESD buffers were obtained previously through IEWBUFF,
they are released here. IEWBUFF (FUNC=FREEBUF) is invoked to accomplish
this.
- 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.
- 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.