Function shipping. IBM iSeries
Reklāma
Reklāma
When a request to process a transaction is transmitted from one CICS system to another, transaction identifiers can be translated from local names to remote names. However, a transaction identifier specified in an EXEC CICS RETURN command is not translated when it is transmitted from the transaction-owning system to the terminal-owning system.
Function shipping
You code a program to access resources in a remote system in much the same way as if they were on the local system. You can use: v
File control
commands to access files on remote systems v
Temporary storage
commands to access data from temporary storage queues on remote systems v
Transient data
commands to access transient data queues on remote systems
Three additional exception conditions can occur with remote resources. They occur if the remote system is not available (SYSIDERR), if a request is invalid
(ISCINVREQ), or if the mirror transaction
2 abends (ATNI for ISC connections).
Distributed program link (DPL)
The distributed program link function in CICS/400 adds to the distributed transaction functions available in CICS by enabling a CICS program (the client program) to call another CICS program (the server program) in a remote CICS system. There are several reasons why you might want to design your application to use distributed program link. Some of these are: v
To separate the end-user interface (for example, BMS screen handling) from the application business logic, such as accessing and processing data, to enable parts of the applications to be ported from host to workstation more readily v
To obtain performance benefits from running programs closer to the resources they access, and thus reduce the need for repeated function shipping requests v To offer a simple alternative, in many cases, to writing distributed transaction processing (DTP) applications
You can specify that the program to which an application is linking is remote by specifying the remote system name either on the EXEC CICS LINK command or by using the SYSID parameter of the ADDCICSPPT or CHGCICSPPT CL commands.
The basic flow in distributed program link is described in the
CICS Family:
Interproduct Communication
Client system
The CICS system running an application program that issues a link to a program in another CICS system
Server system
The CICS system to which a client system ships a link request
Client program
The application program that issues a remote link request
2. A CICS-supplied transaction that recreates a request that is function shipped from one system to another, issues the request on the second system, and passes the acquired data back to the first system.
176
CICS for iSeries Application Programming Guide V5
Server program
The application program specified on the link request, and which is executed in the server system
Figure 33. Illustration of distributed program link
Using the distributed program link function
The distributed program link function provides a number of options. You can specify: v
The name of the remote system (the server system). v
The name of the server program, if it is known by a different name in the server system. v That you want to run the linked program locally, but restrict it to the distributed program link subset of the application programming interface (API) for testing purposes. (Server programs cannot use the entire CICS API when executed
remotely; the restrictions are listed in Figure 38 on page 185).
v
That the server system will take a syncpoint independently from the client. v
The name of the transaction you want the program to run under in the server system. v
The data length of the COMMAREA being passed.
A server program can itself issue a distributed program link and act as a client program with respect to the program it links to.
respectively, in support of the distributed program link facility.
Chapter 15. Intercommunication considerations
177
Note:
The full syntax of the EXEC CICS LINK command is given page 380.
Table 9. Options on EXEC CICS LINK command supporting DPL
Option Description
DATALENGTH
SYSID
SYNCONRETURN
TRANSID
Specifies the length of the contiguous area of storage (from the start of the COMMAREA) that the application is sending to a server program.
Specifies the name of the connection to the server system to which you want the client system to ship the program link request.
Note:
SYSID specified on the EXEC CICS LINK command overrides the remote SYSID specified in the PPT entry.
Specifies that you want the server system to take a syncpoint on successful completion of the server program.
Note:
This option is unique to the EXEC CICS LINK command and cannot be specified on the PPT.
Specifies the name of the transaction that the server system is to attach for execution of the server program.
Note:
TRANSID specified on the EXEC CICS LINK command overrides any remote TRANSID specified on the
PPT.
Table 10. ADDCICSPPT and CHGCICSPPT CL command parameters supporting DPL
SYSID
APISET
TRANSID
Keyword
RMTPGMID
Description
Specifies the name of the connection to the server system
(SYSID) to which you want the client system to ship the program link request.
Specifies the name by which the program is known in the server system (if different from the local name).
Specifies whether the program is restricted to the distributed program link subset of the CICS API.
Note:
This option is unique to the PPT and cannot be specified on the EXEC CICS LINK command.
Specifies the name of the transaction that the server system is to attach for execution of the server program.
Examples of distributed program link
A COBOL example of a distributed program link command is shown in Figure 34.
The numbers down the right-hand side of the example refer to the numbered sections, following the figure, which give information about each option.
EXEC CICS LINK PROGRAM(’DPLPROG’)
1
COMMAREA(DPLPROG-DATA-AREA)
2
LENGTH(24000)
DATALENGTH(100)
SYSID(’CICR’)
TRANSID(’AC20’)
SYNCONRETURN
2
2
3
4
5
END-EXEC.
Figure 34. COBOL example of a distributed program link
1
The program name of the server program
A program may have different names in the client and server systems. The
178
CICS for iSeries Application Programming Guide V5
name you specify on the EXEC CICS LINK command depends on whether or not you specify the SYSID option, and also on whether the PPT entry in the client system specifies the RMTPGMID parameter.
If the program link command specifies a remote system on the SYSID option,
CICS ships the link request to the server system without reference to the PPT entry in the client system. In this case, the program name specified on the link command must be the name by which the program is known in the server system.
If you do not specify the SYSID option on an EXEC CICS LINK command, however, the local name of the program is used. CICS looks up the PPT entry in the local (client) system. If the program is remote, CICS ships the request to the system specified in the SYSID parameter using the name by which the program is known in the server system. This is the RMTPGMID value if one was specified; otherwise the local name is used.
If the system name (SYSID) on the EXEC CICS LINK command is the same name as the client system, CICS initially processes the request as though it is a local link. CICS checks the local PPT entry and, if it specifies a remote system name, the client system ships the request to the system specified in the SYSID parameter. In this case, the remote system name on the PPT entry overrides the
SYSID name on the program link command. If SYSID is not specified in the
PPT entry, or it names the local system name, CICS invokes the program in the client system (a local link).
2
The communication data area (COMMAREA)
To improve performance, you can specify the DATALENGTH option on the
EXEC CICS LINK command. This allows you to specify the amount of
COMMAREA data you want the client system to pass to the server program.
Typically, you use this option when a large COMMAREA is required to hold data that the server program is to return to the client program, but only a small amount of data needs to be sent to the server program by the client program, as in the example.
3
The remote system ID (SYSID)
The SYSID option on the EXEC CICS LINK command enables you to specify a
4-character name for the server system to which you want the client system to ship a program link request. This is the name of the terminal control system table (TCS
®
) entry installed in the client system defining the connection with the server system. (CICS uses the connection name in a table look-up to obtain the netname of the server system.) The name of the server system you specify on the SYSID parameter can be the name of the client system in which case the program is run locally.
If the server system is unable to load or run the requested program (DPLPROG in our example), CICS returns the PGMIDERR condition to the client program in response to the link request. Note that EIBRESP2 values are not returned over the link for a distributed program link request where the error is detected in the server system. For errors detected in the client system, EIBRESP2 values
are
returned.
4
The remote transaction (TRANSID) to be attached
The TRANSID option is available on both the EXEC CICS LINK command and also on the ADDCICSPPT and the CHGCICSPPT CL commands. This enables you to tell the server system what transaction identifier to use when it attaches the mirror task under which the server program runs. If you specify the
TRANSID option, you must define the transaction in the server system, and associate it with the supplied mirror program AEGFSMIR. This option allows
Chapter 15. Intercommunication considerations
179
you to specify your own attributes on the transaction definition for the purpose of performance and fine tuning. For example, you could vary the task priority and transaction class attributes.
You are recommended to specify the transaction identifier of the client program as the transaction identifier for the server program. This enables any statistics and monitoring data you collect to be correlated correctly under the same transaction.
The transaction identifier used on a distributed program link request is passed to the server program as follows: v
If you specify your own transaction identifier for the distributed program link request, this is passed to the server program in the EIBTRNID field of the EIB. v
If you do not specify a transaction identifier for the DPL request, CICS copies the transaction identifier under which the client program is running, into the EIBTRNID field of the server program.
5
The synchronization option for the server program
When you specify the SYNCONRETURN option, it means that the resources on the server are committed in a separate logical unit of work immediately before returning control to the client; that is, an implicit syncpoint is issued for
the server just before the server returns control to the client. Figure 35 on page
181 shows an example of using distributed program link with the
SYNCONRETURN option. The SYNCONRETURN option is intended for use when the client program is not updating any recoverable resources, for example, when performing screen handling. However, if the client does have recoverable resources, they are not committed at this point. They will be committed when the client itself reaches a syncpoint or in the implicit syncpoint at client task end. You must ensure that the client and server programs are designed correctly for this purpose, and that you are not risking data integrity. For example, if your client program has shipped data to the server that results in the server updating a database owned by the server system, you only specify an independent syncpoint if it is safe to do so, and when there is no dependency on what happens in the client program. This option has no effect if the server program runs locally in the client system unless APISET(*DPLSUBSET) is specified. In this case, the syncpoint rules governing a local link apply.
Without the SYNCONRETURN option, the client commits the logical unit of work for both the client and the server resources, with either explicit commands or the implicit syncpoint at task end. Thus, in this case, the server resources are committed at the same time as the client resources are
committed. Figure 36 on page 182 shows an example of using distributed
program link without the SYNCONRETURN option.
180
CICS for iSeries Application Programming Guide V5
Figure 35. Using distributed program link with the SYNCONRETURN option
Note:
This includes three logical units of work: one for the client and two for the server. The client resources are committed separately from the server.
Chapter 15. Intercommunication considerations
181
Figure 36. Using distributed program link without the SYNCONRETURN option
Note:
The implicit or explicit syncpoint causes all client and server resources to be committed. There is only one logical unit of work because the client is responsible for determining when both the client and server resources are committed.
You need to consider the case when the client has an EXEC CICS HANDLE
ABEND command. When the client is handling abends in the server, then the client gets control when the server abends. This is also true when the
SYNCONRETURN option has been specified on the EXEC CICS LINK command.
In this case, it is recommended that the client issue an abend after doing the minimum of cleanup. This causes both the client logical unit of work and the server logical unit of work to be backed out.
Programming considerations for distributed program link
There are some factors you should consider 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 system 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.
182
CICS for iSeries Application Programming Guide V5
Sharing resources between the client program and server program
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: v A client task cannot function ship requests and then use distributed program link with the SYNCONRETURN option in the same client logical unit of work.
The distributed program link would fail with an INVREQ response. In this case
EIBRESP2 is set to 14. v
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 would fail with an INVREQ response. In this case,
EIBRESP2 is set to 15. v
Any function-shipped requests that follow a DPL request with the
SYNCONRETURN option run in a separate logical unit of work from the server logical unit of work. v Any function-shipped requests running that follow a DPL request with the
TRANSID option to the same server system will run under the transaction code specified on the TRANSID option, instead of under the default mirror transaction code. The function-shipped requests will be committed as part of the overall client logical unit of work when the client commits. v
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 the book, the
CICS Family: API Structure
book and the
CICS for iSeries
Intercommunication
book 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 37. Example of mixing DPL and DTP
Restricting a program to the distributed program link subset
Note:
For a description of the naming convention used in this section, see
“Conventions and terminology used in this book” on page xiii.
Chapter 15. Intercommunication considerations
183
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
You can specify, in the program resource definition only, that you want to restrict a program invoked by a local EXEC CICS LINK command to this subset with the
APISET(*DPLSUBSET) option. The use of any prohibited commands can then be detected before an application program is used in a distributed environment. The
APISET(*DPLSUBSET) option should be used for early testing purposes only, and should never be used in production.
When the server program is running locally the following considerations apply: v
If APISET(*DPLSUBSET) is specified on the server program then the
SYNCONRETURN option causes an implicit syncpoint to be taken in the local server program, prior to 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, you should note that SYNCONRETURN is intended for use when the client has no recoverable resources. v
If APISET(*FULLAPI) is specified on the server program then the
SYNCONRETURN option is ignored. v 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 EXEC CICS 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 “ASSIGN” on page 327 for details.
Exception conditions for EXEC CICS LINK command
There are some exception conditions on the EXEC CICS LINK command that relate
specifically to DPL. See page 380 for a description of these exception conditions.
Exception conditions returned to the client program:
Condition codes returned to a client program describe such events as “remote system not known” or “failure to commit” in the server program. There are different reasons, identified by
EIBRESP2 values, for raising the INVREQ and LENGERR conditions on an EXEC
CICS LINK command. The ROLLEDBACK, SYSIDERR, and TERMERR conditions
may also be raised. See page 380 for details.
The PGMIDERR condition is raised on the EXEC CICS HANDLE ABEND
PROGRAM, EXEC CICS LOAD, EXEC CICS RELEASE, and EXEC CICS XCTL commands if the local program definition specifies that the program is remote.
This exception is qualified by an EIBRESP2 value of 9.
Exception conditions returned to the server program:
The INVREQ condition covers the use of prohibited API commands. INVREQ is returned, qualified by an
EIBRESP2 value of 200, to a server program if it issues one of the prohibited
commands summarized in Figure 38 on page 185. If the server program does not
handle the INVREQ condition, the default action is to abend the mirror transaction under which the server program is running with abend code ADPL.
184
CICS for iSeries Application Programming Guide V5
Lejupielādēt
Publiskā saite ir atjaunināta
Ir atjaunināta publiskā saite uz jūsu tērzēšanu. You may view and manage your chat links after registration here.
Dokumenta publiskā saite
Reklāma
