STARTD: Start dialog

STARTD begins a dialog with the binder, establishing the processing environment and initializing the necessary control blocks. You specify the ddnames for the data sets to be accessed, how errors are to be handled, and the global binder options.

STARTD returns a dialog token that is included with later calls for the same dialog.

The syntax of the STARTD call is:


[symbol]       IEWBIND        FUNC=STARTD

                              [,VERSION=version]
                              [,RETCODE=retcode]
                              [,RSNCODE=rsncode]
                              ,DIALOG=dialog
                              [,FILES=filelist]
                              [,EXITS=exitlist]
                              [,OPTIONS=optionlist]
                              [,PARMS=parms] 
                              [,ENVARS=envars]

FUNC=STARTD

Specifies that a dialog is opened and initialized.

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

Specifies the version of the parameter list to be used. The default value is VERSION=1.

Note:

If VERSION=1 is specified for the STARTD call, PARMS cannot be specified as a macro keyword. The parameter list ends with the OPTLIST parameter (with the high-order bit set). This exception is for Version 1 only.
ENVARS cannot be specified if VERSION is less then 6.

RETCODE=retcode — RX-type address or register (2-12)

Specifies the location of a fullword integer that is to receive the return code returned by the binder.

RSNCODE=rsncode — RX-type address or register (2-12)

Specifies the location of a 4-byte hexadecimal string that is to receive the reason code returned by the binder.

DIALOG=dialog — RX-type address or register (2-12)

Specifies the location of an 8-byte area where the binder places the dialog token. This token must not be modified.

FILES=filelist — RX-type address or register (2-12)

Specifies the address of a list containing one entry for each binder file for which a ddname or file name is provided. You code some or all of these file names in the list and provide a ddname or filename for each:

File name: Description
CALLIB: Automatic call library
MODLIB: Target program library
PRINT: Listing data set for messages produced by the LIST, MAP, and XREF options
TERM: Terminal data set for messages issued during binder processing
SIDEFILE: Data set to contain the side file of a DLL module.

The ddnames specified for PRINT and TERM can designate files. CALLIB can designate a directory and a archive file. MODLIB can designate a directory. SIDEFILE can designate a directory or a file.

Entries for all files on this list will accept a z/OS® UNIX pathname in place of a ddname. Path names must begin with a slash (/) or a period and a slash (./).

EXITS=exitlist — RX-type address or register (2-12)

Specifies the address of a list of user exit names. You can specify the following user exits in this list:

MESSAGE exit: Specifies an entry into the calling program that receives control immediately prior to the binder issuing a message. See Message exit.
SAVE exit: Specifies an entry into the calling program that receives control if the binder is about to reject a primary name or an alias name or after an attempt to save a member or alias name. The save operation might have succeeded or failed. See Save exit.
Note: This exit is not invoked if the target is a z/OS UNIX System Services file.
INTFVAL exit: The Interface Validation Exit (INTFVAL) allows your exit routine to examine descriptive data for both caller and called at each external reference. The exit can perform audits such as examining parameter passing conventions, the number of parameters, data types, and environments. It can accept the interface, rename the reference, or leave the interface unresolved. See Interface validation exit.

See User exits for additional information on writing user exit routines.

OPTIONS=optionlist — RX-type address or register (2-12)

Specifies the location of an options list that contains the address of binder options to be initialized during the STARTD call. Any option that can be set by SETO can be initialized by STARTD. See Setting options with the regular binder API for a list of allowable options. However, the EXITS option listed in the table may not be specified as part of the OPTIONS parameter; use the EXITS or PARMS parameter on STARTD to specify user exits.

Note: The negative option format (for example, NORENT) is not allowed. Use the corresponding keyword with a value. For example:

            DC   CL8'REUS'
            DC   AL4 (6) ,C'SERIAL'

PARMS=parms — RX-type address or register (2-12)

Specifies the location of a varying character string that contains a list of option specifications separated by commas. The STARTD FILES, EXITS and OPTIONS lists have precedence over the STARTD PARMS string in the STARTD call. See Setting options with the binder API for more information.

ENVARS=envars — RX-type address or register

Specifies the address of a list of 31-bit pointers. Each pointer in the list contains the address of a character string that is an environment variable, in the form of name=value, to be passed to the specified program. Each character string must end with zeros. Note that this is the same as passing the external variable, environ. See Environment variables for more information.

Passing lists to the binder

Any list passed to the binder must conform to a standard format, consisting of a fullword count of the number of entries followed by the entries. Each list entry consists of an 8-byte name, a fullword containing the length of the value string, and a 31-bit pointer to the value string. The list specification is provided in Table 1.

Table 1. Binder list structure
Field Name	Field Type	Offset	Length	Description
LIST_COUNT	Integer	0	4	Number of 16-byte entries in the list
LIST_ENTRY	Structure	4,20,...	16	Defines one list entry
ENTRY_NAME	Character	0	8	File, exit, or option name
ENTRY_LENGTH	Integer	8	4	Length of the value string
ENTRY_ADDRESS	Pointer	12	4	Address of the value string
Note: ENTRY_NAME, ENTRY_LENGTH, and ENTRY_ADDRESS are repeated for each entry in the list up to the number specified in LIST_COUNT.

You code the data pointed to by ENTRY_ADDRESS according to the list type:

File list

Code one entry for each file name:

ENTRY_NAME:: 'CALLIB ', 'MODLIB ', and so on. See list of file names in FILES parameter description in STARTD: Start dialog.
ENTRY_LENGTH:: The byte length of the corresponding ddname.
ENTRY_ADDRESS:: The address of the string containing the ddname.

Each file name specified in the FILES parameter of the STARTDialog API must correspond to a currently defined ddname. Your data sets can be new or preallocated. Although you can use any valid ddname for a given FILE name, the following ddnames are recommended. Their allocation requirements are listed as follows.

FILE name: Recommended ddname
CALLIB: SYSLIB
MODLIB: SYSLMOD
PRINT: SYSPRINT
TERM: SYSTERM
SIDEFILE: SYSDEFSD

The SYSLIB Data Set (the CALLIB file)

This DD statement describes the automatic call library, which must reside on a direct access storage device. This is a required data set if you want to enable autocall processing while you bind your modules through the use of the BINDWorkmod API call (See the CALLIB parameter in the BINDW API).

The data set must be a library and the DD statement must not specify a member name. You can concatenate any combination of object module libraries and program libraries for the call library. If object module libraries are used, the call library can also contain any control statements other than INCLUDE, LIBRARY, and NAME. If this DD statement specifies a PATH parameter, it must specify a directory.

Table 2 shows the the SYSLIB data set attributes, which vary depending on the input data type.

Table 2. SYSLIB data set DCB parameters
LRECL	BLKSIZE	RECFM
80	80	F, FS, OBJ, XOBJ, control statements, and GOFF
80	32720 (maximum size)	FB, FBS OBJ, XOBJ, control statements, and GOFF
84+	32720 (maximum size)	V, VB, GOFF object modules
n/a	32720 (maximum size)	U, load modules
n/a	4096	U, program objects

The SYSLMOD data set (the MODLIB file)

It is the target library for your SAVEWorkmod API calls when ACCESS=BIND on your CREATEWorkmod API call. That is, SYSLMOD is the library that contains your bound modules. As such, it must be a partitioned data set, a PDSE, or a z/OS UNIX System Services file.

Although a member name can be specified on the SYSLMOD DD statement, it is used only if a name is not specified on the SAVEWorkmod SNAME parameter. (See SAVEW: Save workmod.) Therefore, a member name should not be specified if you expect to save more that one member in a binder dialog. For additional information on allocation requirements for SYSLMOD, see SYSLMOD DD statement in z/OS MVS Program Management: User's Guide and Reference.

The SYSPRINT data set (the print file)

The binder prints diagnostic messages to this data set. The binder uses a logical record length of 121 and a record format of FBA and allows the system to determine an appropriate block size.

Table 3 shows the data set requirements for SYSPRINT.

Table 3. SYSPRINT DCB parameters
LRECL	BLKSIZE	RECFM
121	121	FA
121	32670 (maximum size)	FBA
125		VA or VBA

The SYSTERM data set (the TERM file)

SYSTERM defines a data set for error and warning messages that supplements the SYSPRINT data set. It is always optional. SYSTERM output consists of messages that are written to both the SYSTERM and SYSPRINT data sets, and it is used mainly for diagnostic purposes.

Table 4 shows the data set requirements for SYSTERM.

Table 4. SYSTERM DCB parameters
LRECL	BLKSIZE	RECFM
80	32720 (maximum size)	FB

The SYSDEFSD data set (the SIDEFILE file)

When a module (call it module A) is enabled for dynamic linking through the DYNAM(DLL) binder option, a complementary file can be generated to go along with it. Module A becomes a DLL, and the complementary file becomes its side file. The side file is saved in the data set represented by the SYSDEFSD ddname. The side file contains the external symbols of DLL A, known as exports. These external symbols can be referenced by other DLLs and are known as imports to these modules. If module A does not export any symbols, no side file is generated for it. This applies to any DLL.

SYSDEFSD can be a sequential data set, a PDS, a PDSE, or a z/OS UNIX System Services file. If it is a sequential data set, the generated side files for multiple DLLs are appended one after another, provided that the DISP=MOD parameter is supplied in the SYSDEFSD ddname specification. If SYSDEFSD is a PDS or a PDSE, the side file is saved as a member with the same name as the DLL to which it belongs. Refer to the processing notes of the SAVEW API for additional information.

The SYSDEFSD DD statement is optional. However, when the ddname is absent, the binder issues a warning message if at bind time a program generates export records and the DYNAM(DLL) binder option has been specified.

Exit list

ENTRY_NAME:: 'MESSAGE ', 'INTFVAL ', or 'SAVE '.
ENTRY_LENGTH:: 12.
ENTRY_ADDRESS:: The location of a three-word area containing three addresses. See the message list addresses in Message exit, the save list addresses in Save exit and the interface validation list addresses in Interface validation exit for the contents of the three addresses.

Option list

ENTRY_NAME:: The option keyword (for example, 'LIST ', 'MAP ', 'CALLERID'). Option keywords cannot be truncated and negative options cannot be specified (NOLIST, NOPRINT, and so on). If INTENT=ACCESS, these keywords are not allowed: ALIGN2, CALL, CALLIB, EDIT, LET, MAP, OVLY, RES, TEST, XCAL, and XREF.
ENTRY_LENGTH:: The length of the option value as a character string; it can be zero.
ENTRY_ADDRESS:: The address of the character string encoded with the option's value. The address can be zero. The maximum length of the option value string is 256 bytes. Use commas and parentheses if a sublist is required.

Return and reason codes

The common binder API reason codes are shown in Table 1.

Return Code	Reason Code	Explanation
00	00000000	Normal completion.
04	83000112	The binder encountered an unsupported option in the OPTIONS file. The option is ignored.
04	83000204	The binder was unable to open the trace data set during initialization. Processing continues without trace.
08	83000108	An option value is missing or contains an invalid setting.
08	83000111	An OPTIONS option was encountered in the options file. The option is ignored.
08	83000200	The binder was unable to open the PRINT data set during initialization. Processing continues without PRINT.
08	83000201	One or more invalid options were passed on STARTD. Those options were not set, but processing continues.
12	83000203	The binder was unable to open the TERM data set during initialization. Processing stops.
08	83000205	The current time was not available from the operating system. Time and date information in printed listings and IDR records will be incorrect.
08	83000206	The binder was unable to open the SYSTERM data set because its DDNAME was not specified in the FILES parameter of STARTD. Processing continues without SYSTERM.
12	83000207	The binder was unable to open the SYSPRINT data set because its DDNAME was not specified in the FILES parameter of STARTD. Processing continues without SYSPRINT.

Environment variables

When the binder API is used by a program running in the z/OS UNIX subsystem, the environ parameter may be used to pass the C/C++ runtime variable of that name to the binder, in order to give the binder access to the array of environment variables. If a user sets binder environment variables (those documented below) in the UNIX shell, this is the only way the binder can get access to them. For further information about the C runtime 'environ' variable, refer to z/OS C/C++ Runtime Library Reference.

Although it is not recommended, you may also construct your own 'envars' parameter using the same format as that of the C runtime variable. In this case, 'envars' must be the address of an array of pointers. Each pointer is the address of a null-terminated string representing an individual environment variable in the form 'keyword=value'. The last array entry must be a null pointer.

The following UNIX shell environment variables are recognized by the binder. They are specified in the form:

export  NAME=value

where NAME is the name of the environment variable.

IEWBIND_PRINT: the pathname or ddname to be used for SYSPRINT.
IEWBIND_TERM: the pathname or ddname to be used for SYSTERM.
IEWBIND_OPTIONS: the binder option string. These will be appended to options passed explicitly through the STARTD API call (and will take precedence). There are additional environment variables defined for the binder diagnostic data sets. See the "Binder Serviceability Aids" chapter in z/OS MVS Program Management: User's Guide and Reference for more information on passing them on STARTD.

Parameter list

If your program does not use the IEWBIND macro, place the address of the STARTD parameter list in general purpose register 1.


PARMLIST   DS    0F
           DC    A(STARTD)                  Function code
           DC    A(RETCODE)                 Return code
           DC    A(RSNCODE)                 Reason code
           DC    A(DIALOG)                  Dialog token
           DC    A(FILELIST)                File list
           DC    A(EXITLIST)                Exit list
           DC    A(OPTLIST)                 Option list
           DC    A(PARMSTR)                 Parameters
           DC    A(ENVARS)                  Environment variables
STARTD     DC    H'01'                      STARTD function code
           DC    H'version'                 Interface version number

Note: X'80000000' must be added to the last parameter. For version 1, that will be OPTLIST. For other versions it may be either PARMSTR or (beginning with version 6) ENVARS.