Serviceability aids for the Binder API interface

You do NOT need to specify the diagnostic file names in the STARTD file list if you use the standard DDNAMES. For example, to obtain the binder trace dataset you need only allocate IEWTRACE. However, if you wish to override the default ddnames for these data sets, you can do so by coding filelist entries on STARTD.

Table 1. Filelist diagnostic entries.
FILE name	Default ddname
DIAG	IEWDIAG
DUMP	IEWDUMP
GOFF	IEWGOFF
TRACE	IEWTRACE

To request a dump on a specific ecode using the binder interface, use the following assembler example as a guide.

**********************************************
*        START THE BINDER DIALOG             *
**********************************************
STARTD   IEWBIND FUNC=STARTD,RETCODE=RETCODE,RSNCODE=RSNCODE,                X
               DIALOG=DTOKEN,OPTIONS=OPTLIST,FILES=FILELIST
*
OPTLIST  DS    0F
         DC    F'2'                           NUMBER OF ENTRIES IN OPTIONS LIST
         DC    CL8'MSGLEVEL',F'2',A(MSGVALU)
         DC    CL8'DUMP    ',F'10',A(ECODE)   DUMP ON SPECIFIC ECODE
MSGVALU  DC    C'12'
ECODE    DC    C'''2500A000'''                ECODE FOR ENTRY TO
*                                             BINDER MODULE IEWBFMOD
FILELIST DS    0F
         DC    F'1'                           NUMBER OF ENTRIES IN FILES LIST
         DC    CL8'DUMP    ',F'8',A(DDNAME)   DUMP DATA SET REQUESTED
DDNAME   DC    C'IEWDUMP '

You may write the DIAG or TRACE files to a z/OS® UNIX file either by allocating the ddname for the file to z/OS UNIX file or by specifying a z/OS UNIX path name in place of the ddname in the STARTD filelist. The path name may be either a relative or absolute path name and may be up to 1023 characters in length. It must begin with either a '/' or './'. The DIAG and TRACE files will be written as text files. Trace records will be truncated to 80 characters if written to a z/OS UNIX file.

If you are writing a BInder API program which may be executed in the UNIX shell, we recommend that you pass the optional 'environ' parameter on the STARTD call. This will allow users of the API program to override or add path names or ddnames for the binder files using the external variables recognized by the binder, or to pass additional binder options.

The following environment variables are supported for binder diagnostic files:

IEWBIND_DIAG: pathname or ddname to be used for IEWDIAG
IEWBIND_TRACE: pathname or ddname to be used for IEWTRACE
IEWBIND_DUMP: ddname to be used for IEWDUMP
IEWBIND_GOFF: ddname to be used for IEWGOFF

For more information about binder support for environment variables, refer to the documentation under the binder STARTD API description. For example to obtain an IEWDUMP for a speciifc binder ecode without altering the souce code for your program, the binder DUMP option could be coded with the desired ecode as the value for the IEWBIND_OPTIONS environment variable.

See z/OS MVS Program Management: Advanced Facilities for more information on the binder API.