|
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:
[symbol] |
IEWBIND |
FUNC=INCLUDE [,VERSION=version]
[,RETCODE=retcode]
[,RSNCODE=rsncode] ,WORKMOD=workmod ,{INTYPE={DEPTR|SMDE},DDNAME=ddname,DEPTR=deptr | INTYPE=NAME,{DDNAME=ddname[,MEMBER=member]
|PATHNAME=pathname} | INTYPE=POINTER,DCBPTR=dcbptr,DEPTR=deptr | INTYPE=TOKEN,EPTOKEN=eptoken}
[,ATTRIB={YES | NO}]
[,ALIASES={YES | NO}][,IMPORTS={YES | NO}]
|
- 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: - The binder supports all data sets allocated in the extended addressing
space (EAS) of an extended address volume (EAV).
- 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: - 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.
- 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.
- 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)
- 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.
- The binder supports all data
sets allocated in the
extended addressing space (EAS) of an extended address volume (EAV).
- 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}
- 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. The
values for ALIASES can be abbreviated as Y or N. NO is the default.
- IMPORTS={YES | NO}
- Indicates whether or not the import statements are to be included
from the input module.
Processing notes
If ATTRIB=YES,
the following
attributes are copied from the input directory: AC, AMODE, DC, LONGPARM,
OL, REUS, RMODE, SSI, TEST, ENTRY POINT, DYNAM, and MIGRATABLE. If
INTENT=ACCESS, the following additional attributes are copied: EDITABLE,
EXECUTABLE, OVLY, and PAGE-ALIGNED. You cannot set the EXECUTABLE,
MIGRATABLE, and PAGE-ALIGNED attributes with either SETO or STARTD.
When INTENT=ACCESS is specified on CREATEW,
only one data set can be included in the workmod and the data set
must be a program object or load module.
If INTENT=ACCESS and ALIASES=YES,
the aliases and any associated addressing modes are included. If INTENT=BIND and ALIASES=YES,
the aliases are included, but the associated addressing modes are
not.
If INTENT=ACCESS and ATTRIB=YES,
the SIGN option value is preserved in the included module,
which means the signature and the directory bit that indicates the
presence of the signature are preserved on an INCLUDE API call.
When INTENT=BIND, the ddname can refer to a concatenation
of data sets or to a z/OS UNIX System Services file. These
data sets must be either all libraries or all sequential data sets.
If the ddname refers to a library and the member name is included
with the library name, it is processed sequentially and can only
be concatenated with other library members or sequential data sets.
Each library member must contain either a single program module or
a mixture of object modules and control statements. Sequential data
sets can only contain object modules and control statements.
The
processing of INCLUDE can be modified by
the ALTERW function. CSECTs and symbols can be replaced
or deleted in an included module when specified on earlier ALTERW calls
or equivalent control statements. The scope of such alterations extends
only to the first end-of-module condition encountered in the included
file. Additional modules can not be included into the workmod once
it has been bound.
Return and reason codes
The common binder API
reason codes are shown in Table 1.
Return Code |
Reason
Code |
Explanation |
---|
00 |
00000000 |
Normal completion. File included successfully. |
04 |
83000515 |
Unsupported control statement encountered in included
file. File included successfully. |
04 |
83000525 |
An unusual
condition was encountered while processing
a REPLACE or CHANGE control statement. |
04 |
83000526 |
An unusual condition was encountered in an input
module, while converting it into workmod format. For example, this
reason code will be returned if a two-byte relocatable adcon was seen. |
08 |
83000502 |
One or more editing requests (delete, change or
replace operations) failed during inclusion of the module. The module
was included successfully, but some of the requested changes were
not made. |
08 |
83000505 |
The included module
was marked not editable,
and has been deleted. |
08 |
83000507 |
A format error
has been encountered in a module
being included. The module was not added to the target workmod. |
08 |
83000510 |
Errors were encountered in the included module.
The module is rejected. |
08 |
83000511 |
A control
statement in an included file attempted
to include the file containing the statement, or include another file
that, in turn, included the original file. The recursive include has
been rejected. |
08 |
83000514 |
The requested member
could not be found in the
library, or the library could not be found. Request rejected. |
08 |
83000516 |
A format error has been encountered in one or
more control statements being included. The erroneous statements have
been ignored. |
08 |
83000517 |
A NAME control statement
was encountered, but
no target library (MODLIB) had been specified. The statement was ignored. |
08 |
83000518 |
A NAME control statement was encountered in a
secondary input file. The statement was ignored. |
08 |
83000519 |
Errors (invalid data) were found in a module being
brought in by an INCLUDE control statement. The module was not included. |
08 |
83000520 |
The data set or library member specified by an
INCLUDE control statement could not be found. The data set or library
member was not included. |
08 |
83000521 |
An I/O error
occurred while trying to read an
input data set (or directory) specified on an INCLUDE control statement.
The data set (or member) was not included. |
08 |
83000522 |
The input data set specified on an INCLUDE control
statement could not be opened. The data set (or member) was not included. |
08 |
83000527 |
Identify data could not be processed because the
section was not included prior to identify statement. |
08 |
83000528 |
The DE parameter value; the TTR or K (concatenation)
field is invalid. |
12 |
83000101 |
Not all the
parameters required for the specified
INTYPE (as described above) were provided. The request has been rejected. |
12 |
83000103 |
The workmod was specified with INTENT=BIND, but
the INTYPE was other than DDNAME. The request has been rejected. |
12 |
83000500 |
The INCLUDE call has attempted to include a second
module when the processing intent is ACCESS. The request has been
rejected. |
12 |
83000503 |
An I/O error occurred
while trying to read the
input data set or its directory. The input is not usable. |
12 |
83000504 |
The module was successfully included, but the
ALIASES or ATTRIB option could not be honored because the directory
was not accessible. |
12 |
83000506 |
An attempt
has been made to include an object
module into a workmod specified as INTENT=ACCESS. Request rejected. |
12 |
83000507 |
A format error has been encountered in a module
being included. The module was not added to the target workmod. |
12 |
83000509 |
An attempt has been made to include a file containing
control statements but the workmod specified INTENT=ACCESS. The request
has been rejected. |
12 |
83000512 |
The designated
source for the current INCLUDE
contained more than one module but the target workmod was specified
with INTENT=ACCESS. The request has been rejected. |
12 |
83000513 |
The file could not be opened. Request rejected. |
12 |
83000523 |
For intent access, the requested module contained
a format error and has not been placed in workmod. Request rejected. |
If the INCLUDE brings in control
statements, the processing of
these control statements might generate calls to other binder functions.
The errors and their corresponding reason codes from the functions
invoked by the generated calls are propagated back to the caller of
the INCLUDE function. The functions can include: - ADDA
- ALIGNT
- ALTERW
- BINDW
- CREATEW
- DELETW
- INSERTS
- ORDERS
- PUTD
- RESETW
- SAVEW
- SETL
- SETO
- STARTS
Parameter list
If
your program does not use the IEWBIND macro, place the address
of the INCLUDE parameter list in general purpose register 1.
Table 1. INCLUDE parameter list |
|
|
|
---|
PARMLIST |
DS |
0F |
|
|
DC |
A(INCLUDE) |
Function code |
|
DC |
A(RETCODE) |
Return code |
|
DC |
A(RSNCODE) |
Reason code |
|
DC |
A(WORKMOD) |
Workmod token |
|
DC |
A(INTYPE) |
Intype |
|
DC |
A(DDNAME) |
ddname or pathname. Pathname is only valid if
INTYPE=N. |
|
DC |
A(MEMBER) |
Member name. A(0) should be coded if PATHNAME
is specified. |
|
DC |
A(DCBPTR) |
Pointer to DCB |
|
DC |
A(DEPTR) |
Pointer to BLDL entry |
|
DC |
A(EPTOKEN) |
EPTOKEN |
|
DC |
A(0) |
Reserved |
|
DC |
A(ATTRIB) |
ATTRIB option |
|
DC |
A(ALIASES) |
ALIASES option |
|
DC |
A(IMPORTS+X'80000000') |
IMPORTS option and end-of-list indicator |
INCLUDE |
DC |
H'40' |
Function code |
|
DC |
H'version' |
Interface version number |
INTYPE |
DC |
CL1'N' |
INTYPE
source option 'N' = Name
'P' = Pointer
'T' = Token
|
ATTRIB |
DC |
CL1'Y' |
ATTRIB option 'Y' = Yes
'N' = No
|
ALIASES |
DC |
CL1'Y' |
ALIASES option 'Y' = Yes
'N' = No
|
IMPORTS |
DC |
C'Y' |
Whether imports in input should be included 'Y' = Yes
'N' = No
|
|
|
|
|
Note: X'80000000'
must be added to the ALIASES parameter (for Version
1 through 4) and to the IMPORTS parameter (for Version 5).
|