INCLUDE: Include module

INCLUDE brings data into the workmod. The source is usually a data set that can contain a program object, a load module, or a combination of object modules and control statements. In some cases, the program module might be included from virtual storage rather than an external data set. Multiple INCLUDE calls cause all included program objects, load modules, and object modules to be merged in the specified workmod. You can specify a z/OS UNIX System Services file as the DDNAME parameter value on an INCLUDE statement.

The syntax of the INCLUDE call is:

FUNC=INCLUDE

Specifies the source of modules to be included in a workmod.

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

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

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.

WORKMOD=workmod — RX-type address or register (2-12)

Specifies the location of an 8-byte area that contains the workmod token for this request.

INTYPE={NAME | DEPTR | SMDE | POINTER | TOKEN}

Specifies whether the input is identified by a name, a PDS2 directory entry pointer, an SMDE format directory entry pointer, a DCB pointer, or an entry point token.

The parameters applicable for each INTYPE are:

INTYPE=DEPTR
       DDNAME=ddname
       DEPTR=deptr
INTYPE=NAME
       DDNAME=ddname
         MEMBER=memberIO
       PATHNAME=pathname
INTYPE=POINTER
       DCBPTR=dcbptr
       DEPTR=deptr
INTYPE=SMDE
       DDNAME=ddname
       DEPTR=deptr
INTYPE=TOKEN
       EPTOKEN=eptoken

The values are as follows:

NAME

The input is obtained from a sequential data set, a program library, or a z/OS UNIX System Services file.

The DDNAME-MEMBER parameter combination, or PATHNAME, must be specified when INTYPE=NAME.

• If DDNAME refers to a program library, MEMBER must also be specified. NAME is required when INTENT=BIND.
• If PATHNAME is specified, it must be an absolute or relative z/OS UNIX System Services pathname that resolves to the desired file (member) name. Note that MEMBER cannot be specified with PATHNAME.

DEPTR

The input is accessed using DDNAME and DEPTR. The directory entry is in PDS2 format.

SMDE

The input is accessed using the DDNAME and DEPTR. The directory entry is in SMDE format.

POINTER

The input is obtained from a member in a partitioned data set. DCBPTR and DEPTR must both be specified. This value is only valid when the processing intent specified on the CREATEW call is ACCESS.

TOKEN

The input is represented by a token from the CSVQUERY macro. EPTOKEN must be specified. This value is only valid when the processing intent specified on the CREATEW call is ACCESS. The program module has already been loaded into virtual storage. Use this option instead of POINTER for modules in PDSE libraries.

The values for INTYPE can be abbreviated as N, D, S, P, or T .

DDNAME=ddname — RX-type address or register (2-12)

Specifies the location of an 8-byte varying character string that contains the ddname associated with the sequential data set or program library to be included in the workmod. If a program library is specified, MEMBER must also be specified. The DDNAME-MEMBER parameter combination is mutually exclusive with PATHNAME.

Note:

1. The binder supports all data sets allocated in the extended addressing space (EAS) of an extended address volume (EAV).
2. The binder supports the following dynamic allocation (DYNALLOC or SVC 99) options for all data sets: S99TIOEX(XTIOT), S99ACUCB (NOCAPTURE), and S99DSABA (DSAB above the line).

MEMBER=member — RX-type address or register (2-12)

Specifies the location of an 8-byte varying character string that contains the member name or alias of the library member to be included in the workmod.

PATHNAME=pathname — RX-type address or register (2-12)

Specifies the location of a 1023-byte varying character string that contains the absolute or relative path name of a z/OS UNIX System Services file. The path name must begin with "/" (absolute path) or "./" (relative path) and is limited to a maximum of 1023 characters. Note that PATHNAME must resolve to the file that is included. PATHNAME is mutually exclusive with the DDNAME-MEMBER parameter combination.

DCBPTR=dcbptr — RX-type address or register (2-12)

Specifies the location of a 4-byte pointer that contains the address of a DCB for the partitioned data set or PDSE containing the input module to be included. You code the DCB with the parameters DSORG=PO, MACRF=R, and RECFM=U | F. The DCB must be opened for input or update before calling the INCLUDE function.

Note:

1. The binder is sensitive to the state of the DCB pointed to by the DCBPTR. The DCB must not be closed and reopened while the binder accesses the corresponding data set during a dialog. Once it is opened initially for an INCLUDE, it must remain open until after the binder's ENDD call takes place.
2. When you alter your DCB as described above, using RESETW (or DELETEW followed by CREATEW) is not enough to reaccess your data set at a later time during the same binder dialog. This only causes the data set's information to remain with the dialog, and such information is no longer valid once the DCB is closed. An attempt to reuse the altered DCB in the same binder dialog can produce unpredictable results.
3. In addition to a caller-created DCB, the following three specific system-provided DCBs can be used here:
   • A linklist DCB (from CVTLINK or DLCBDCB@)
   • A tasklib DCB (from TCBJLB)
   • An EXEC PGM=*.referback DCB (from the top of the DEB chain)
4. If you haven't set a new DCBE with the EADSCB=OK option, the system assumes that the program cannot handle the track address and issues a new ABEND code.
5. The binder supports all data sets allocated in the extended addressing space (EAS) of an extended address volume (EAV).
6. The binder supports the following dynamic allocation (DYNALLOC or SVC 99) options for all data sets: S99TIOEX(XTIOT), S99ACUCB (NOCAPTURE), and S99DSABA (DSAB above the line).

DEPTR=deptr — RX-type address or register (2-12)

Specifies the location of a 4-byte pointer that contains the address of a single directory entry for the partitioned data set or PDSE member to be included. The directory entry can be in the PDS2 format or in the SMDE format. If INTYPE=S, it must be SMDE. If INTYPE=D or P, it must be PDS2. The PDS2 format is returned by BLDL while the SMDE format is returned by DESERV. The DEPTR, when used with DCBPTR, will only locate the first data set in a concatenated DD. INTYPE=D or S must be used to locate other data sets in a concatenated DD. This parameter is required for INTYPEs of D, S, or P. DEPTR is valid only if INTENT=ACCESS.

Note: When specifying a directory entry pointer for a directory entry in PDS2 format, the directory entry must contain the full 72 bytes of data.

EPTOKEN=eptoken — RX-type address or register (2-12)

Specifies the location of an 8-byte area containing the entry point token received with the CSVQUERY macro. EPTOKEN is required when the program module has already been loaded in virtual storage. EPTOKEN is valid only if INTENT=ACCESS.

The binder can retrieve a module identified by an entry point token only if the module was loaded. EPTOKEN cannot be used to retrieve a module in LPA or LLA. EPTOKEN can be used for programs loaded from the UNIX shell by BPX1LOD.

ATTRIB={YES | NO}

Specifies whether to include the program module attributes with the program module. These attributes override attributes set at the dialog level by SETO or STARTD and any attributes set by prior INCLUDE calls. They do not override attributes set at the workmod level by SETO. The values for ATTRIB can be abbreviated as Y or N.

ALIASES={YES | NO | KEEP}

Specifies whether to include the program module aliases with the program module. Aliases can be included only if you are including a module from a library. If the ddname specified points to a sequential data set, a z/OS UNIX System Services file, or a specific member of a PDS or PDSE library, aliases cannot be included. When KEEP is specified, aliases are kept in an inactive state. Aliases can later be activated through ADDA, by adding it to the list of aliases to be written with the saved module. The values for ALIASES can be abbreviated as Y, N, or K. NO is the default.

IMPORTS={YES | NO}

Indicates whether or not the import statements are to be included from the input module.