Application programming for CICS function shipping

Your application can run in the CICS® intercommunication environment and use function shipping to access a resource owned by, or accessible to, another CICS system, without being aware of the location of the resource being accessed. If you are writing a program to access resources in a remote system, you code it in much the same way as if the resources were on the local system. The location of the resource being accessed is specified in the resource definition. Optionally, you can use the SYSID option on EXEC commands to select the system on which the command is to be executed. In this case, the resource definitions on the local system are not referenced, unless the SYSID option names the local system.

The commands that you can use to access remote resources are:
  • File control commands
  • DL/I calls or EXEC DLI commands
  • Temporary storage commands
  • Transient data commands

For information about interval control commands, see Application programming for asynchronous processing.

When your application issues a command against a remote resource, CICS ships the request to the remote system, where a mirror transaction is initiated. The mirror transaction executes the request on your behalf, and returns any output to your application program. The mirror transaction is like a remote extension of your application program. For more information about this mechanism, see The mirror transaction and transformer program.

Although the same commands are used to access both local and remote resources, there are restrictions that apply when the resource is remote. Also, some errors that do not occur in single systems can arise when function shipping is being used. For these reasons, you should always know whether resources that your program accesses can possibly be remote.

Programming considerations for file control

Function shipping allows you to access files located on a remote system.

If you use the SYSID option to access a remote system directly, you must observe the following two rules:
  1. For a file referencing a keyed data set, KEYLENGTH must be specified if RIDFLD is specified, unless you are using relative byte addresses (RBA) or relative record numbers (RRN).

    For a remote BDAM file, where the DEBKEY or DEBREC options have been specified, KEYLENGTH must be the total length of the key.

  2. If the file has fixed-length records, you must specify the record length (LENGTH).

These rules also apply if the definition of the file to this CICS does not specify the appropriate values.

Programming considerations for temporary storage

You can use function shipping to send data to or receive data from temporary storage queues located on remote systems.

The systems programmer can use TSMODEL resource definitions to define temporary storage models that direct matching EXEC CICS requests to remote systems. TSMODEL resource definitions do not support the use of the SYSID option on the WRITEQ TS, READQ TS, and DELETEQ TS commands to specify the remote system explicitly.

For MRO and IPIC sessions, the MAIN and AUXILIARY options of the WRITEQ TS command can be used to select the required type of storage.

For APPC sessions, the MAIN and AUXILIARY options are ignored; unless a TSMODEL or exit directs it otherwise, auxiliary storage is always used in the remote system.

Programming considerations for transient data

Function shipping allows you to access intrapartition or extrapartition transient data queues located on remote systems. Definitions of remote transient data queues can be made by the system programmer. You can, however, use the SYSID option on the WRITEQ TD, READQ TD, and DELETEQ TD commands to specify the system on which the request is to be executed.

If the remote transient data queue has fixed-length records, you must supply the record length if it is not specified in the transient data resource definition that has been installed.