Consider the following factors when writing application
programs that use distributed program link.
Issuing multiple distributed program links from the
same client task
A client task cannot request distributed program
links to a single CICS server region using more than one transaction
code in a single client unit of work unless the SYNCONRETURN option
is specified. It can issue multiple distributed program links to one
CICS server system with the same or the default transaction code.
Sharing resources between client and server programs
The
server program does not have access to the lifetime storage of tasks
on the client, for example, the TWA. Nor does it necessarily have
access to the resources that the client program is using, for example,
files, unless the file requests are being function shipped.
Mixing DPL and function shipping to the same CICS
system
Great care should be taken when mixing function shipping
and DPL to the same CICS system, from the same client task. These
are some considerations:
- A client task cannot function ship requests and then use distributed
program link with the SYNCONRETURN option in the
same session (same logical unit of work or system initialization
parameter MROFSE=YES specified or IPCONN MIRRORLIFE set to UOW or
TASK). The distributed program link fails with an INVREQ response.
In this case EIBRESP2 is set to 14.
- A client task cannot function ship requests and then use distributed
program link with the TRANSID option in the same
client logical unit of work. The distributed program link fails with
an INVREQ response. In this case, EIBRESP2 is set to 15.
- Any function-shipped requests that follow a DPL request with the SYNCONRETURN option
runs in a separate logical unit of work from the server logical unit
of work.
- Any function-shipped requests running that follow a DPL request
with the TRANSID option to the same server region
runs under the transaction code specified on the TRANSID option,
instead of under the default mirror transaction code. The function-shipped
requests are committed as part of the overall client logical unit
of work when the client commits.
- Any function-shipped requests running before or after a DPL request
without the SYNCONRETURN or TRANSID options
are committed as part of the overall client logical unit of work when
the client commits.
See CICS function shipping for
more information about function shipping.
Mixing DPL and DTP to the same CICS system
Care
should be taken when using both DPL and DTP in the same application,
particularly using DTP in the server program. For example, if you
have not used the
SYNCONRETURN option, you must avoid
taking a syncpoint in the DTP partner which requires the DPL server
program to syncpoint.
Figure 1. Example of mixing
DPL and DTP
Restricting a program to the distributed program link
subset
When a program executes as the result of a distributed
program link, it is restricted to a subset of the full CICS API called
the distributed program link subset. The commands that are prohibited
in a server program are summarized in Table 1.
You
can specify, in the program resource definition only, that you want
to restrict a program invoked by a local LINK command to this subset
with the EXECUTIONSET(DPLSUBSET) option. The use of any prohibited
commands can then be detected before an application program is used
in a distributed environment.
When the server program is running
locally the following considerations apply:
- If EXECUTIONSET(DPLSUBSET) is specified on the server program
then the SYNCONRETURN option causes an implicit syncpoint
to be taken in the local server program, before returning control
to the client program. In this case, because the server program is
running locally, both the client and server resources are committed.
However, SYNCONRETURN is intended for use when the
client has no recoverable resources.
- If EXECUTIONSET(FULLAPI) is specified on the server program, the SYNCONRETURN option
is ignored.
- The TRANSID and DATALENGTH options
are ignored when processing the local link, but the format of the
arguments is checked, for example, the TRANSID argument cannot be
all blank.
Determining how a program was invoked
The
2-byte values returned on the STARTCODE option of
the ASSIGN command are extended in support of the
distributed program link function enabling the server program to find
out that it is restricted to the distributed program link subset.
See CICS API commands for programming information
about EXEC CICS commands.
Accessing user-related information with the ASSIGN
command
The values returned with the USERID and OPID keywords
of the ASSIGN command in the server program depend
on the way the ATTACHSEC option is defined for the
connection being used between the client CICS region and the server
CICS region. For example, the system could be defined so that the
server program could access the same USERID and OPID values as the
client program or could access different values determined by the ATTACHSEC option.
If
ATTACHSEC(LOCAL) is specified, the userid to which the OPID and USERID
parameters correspond is one of the following, in the order shown:
- The user ID specified on the USERID parameter
(for preset security) of the SESSIONS resource definition, if present
- The user ID specified on the SECURITYNAME parameter
of the connection resource definition, if present and no preset security
user ID is defined on the sessions
- The user ID specified on the DFLTUSER system
initialization parameter of the server region, if neither the sessions
nor connection definitions specify a user ID
If any value other than LOCAL is specified for ATTACHSEC,
the signed-on user ID is the one received in the attach request from
the client region.
For more information, see Intercommunication security
Another security-related
consideration concerns the use of the CMDSEC and RESSEC options
of the ASSIGN command. These are attributes of
the transaction definition for the mirror transaction in the server
region. They can be different from the definitions in the client region,
even if the same TRANSID is used.