Preparing for CICS Socket Listener

The EntireX CICS® Socket Listener is a remote connector on z/OS or z/VSE to call CICS mainframe programs. This document covers the following topics:

Overview
Installing the CICS Socket Listener
Configuring the IBM Standard Listener
User Transaction Support
Automatic Syncpoint Handling
User Exit

Overview

The CICS Socket Listener is used by the RPC Server for CICS Socket Listener. Apart from installation there is no configuration necessary in CICS. Configuration is done with the RPC Server for CICS Socket Listener. See Configuring an RPC Server Instance > CICS using the Command Central GUI | Command Line.

graphics/overview-rpc.png

The implementation for CICS is based on the CICS standard listener provided by IBM. With this listener you can launch CICS transaction via TCP/IP. The launched transaction takes the TCP connection and continues the communication with the launching process.

Depending on your platform, more information on configuring the IBM standard listener for CICS can be found under the following IBM documentation:

z/OS Communications Server: IP CICS Socket Guide
z/VSE TCP/IP Support

Installing the CICS Socket Listener

The CICS Socket Listener is installed

together with the RPC Server for CICS, see Installing the RPC Server for CICS, or
separately, see EntireX CICS® Socket Listener in the z/OS | z/VSE Installation documentation

Configuring the IBM Standard Listener

Depending on your platform, more information on configuring the IBM standard listener for CICS can be found under the following IBM documentation:

z/OS Communications Server: IP CICS Socket Guide
z/VSE TCP/IP Support

Start of instruction set To start/stop the IBM standard listener

Use the CICS supplied transaction EZAO. The listener is automatically started/stopped when CICS is started or stopped.

Start of instruction set To configure the IBM standard listener

Use the CICS-supplied transaction EZAC,ALT,LISTENER.
- For SECEXIT, define EXXRFECS.
- Make sure the PORT number of the IBM standard listener corresponds to the configuration parameter CICS port. See Configuring an RPC Server Instance > CICS using the Command Central GUI | Command Line.

User Transaction Support

User transaction support means that CICS programs executed by RPC requests run in separate CICS tasks (the user transactions). A user transaction is started for each CICS program within a standard non-conversational RPC request. If you are running multiple CICS programs within an RPC conversation, the user transaction remains active and processes all CICS programs belonging to the conversation. The user transaction is terminated if the non-conversational RPC request or the RPC conversation is finished, or if an executing CICS program issues a CICS ABEND. The name of the user transaction can be customized. User transaction support, is useful, for example, for accounting purposes.

Start of instruction set To run the CICS programs in a separate user transaction

Define your user transaction ID in the RPC Server for CICS Socket Listener, for example:
```
cics.sl.user.transaction.id=UTSK
```
For more information see Configuring the CICS Socket Listener Side.
Create the CSD for the user transaction ID.
In this CSD definition, specify EXXRFECU for the PROGRAM attribute. To define, for example, UTSK as user transaction ID, use the following commands:
```
DEFINE TRANSACTION(UTSK) GROUP(...)
DESCRIPTION(CICS Socket Listener user transaction)
PROGRAM(EXXRFECU)
```

Automatic Syncpoint Handling

After each non-conversational RPC request (or the end of a series of conversational RPC requests), an implicit CICS COMMIT (or CICS ROLLBACK if an error occurs) is executed by the CICS Socket Listener. If you are running with user transaction support, syncpoint handling is executed by CICS itself when the user transaction terminates.

User Exit

To enable a user exit, use the property cics.sl.userexit to specify the class name of the user exit implementation. The class will be loaded using the standard classpath. You can specify a separate classpath with the property cics.sl.userexit.classpath. Note that for the classpath, a file or HTTP URL must be specified, for example file://myexit.jar or http://host/path/to/my/exit.

Your user exit class must implement the Java interface com.softwareag.entirex.cics.socketlistener.IUserExit. This Java interface has the following method:

/**
   * Read and modify the CICS Socket Listener request payload before sending the request.
   * Get access to the ConfigurationParameters.
   *
   * The payload layout:
   *
   * Name (16 bytes, for example Commarea, LargeBuffer or the name of a container)
   * Data-length (4 bytes)
   * Data (number of bytes defined in the previous parameter)
   *
   * Channel container data may contain multiple blocks (one for each input container)
   *
   * @param requestPayload CICS Socket Listener Payload to be sent to CICS, containing a java.nio.ByteBuffer
   * @param properties CICS Socket Listener Configuration Parameters with access to the user transaction ID and several
   * Bridge framework parameters, like IDL program name, IDL library name, target program name etc.
   */
  void beforeSend(Payload requestPayload, ConfigurationParameters properties);