CSLOMSUB: Subscribe to unsolicited messages

A message is defined as unsolicited when it is not generated as a response to an input message. For example, system informational messages are unsolicited messages. In an IMS 15 IMSplex environment, a command response is considered an unsolicited message if it is returned to a SPOC from which the command did not originate.

All unsolicited output messages are routed to the OM's Output exit routine, which can modify the output. SPOCs can subscribe to the OM using the CSLOMSUB request to have the unsolicited output messages, modified or not, routed to them. To identify unsolicited output messages that should not be directed to OM, you can edit a table that includes messages from OM, RM, SCI, CQS, and the IMS control region that should be ignored.

You must specify an SCI Input exit routine on the SCI registration request (CSLSCREG) to receive unsolicited output messages.

To understand if OM has terminated, specify an SCI Notify exit routine on the SCI registration request, specifying either the RETNAME or RETTOKEN parameter. The SCI Notify exit is called whenever there is a change in status of any member of the IMSplex. Save the RETNAME or RETTOKEN value from the SCI registration and use it to look for a match that indicates that the OM has terminated. The SPOC client can then subscribe to another OM.

This request is supported in Assembler and PLX.

CSLOMSUB request parameters

PARM=parm

PARM=(r1-r12)

Specifies the CSLOMSUB parameter list. The length of the parameter list must be equal to the parameter list length equate (EQU) value that is defined by OSUB_PARMLN.

MBRLIST=memberlist

MBRLIST=(r1-r12)

Specifies a member list that identifies the command processing clients (such as IMS control regions) in the IMSplex from which to receive unsolicited output messages. Do not specify the MBRLIST= parameter if you specify the TYPELIST parameter. If you do not specify either the TYPELIST or MBRLIST parameter, the default member list is all the command processing clients in the IMSplex.

Use commas to separate the client names.

MBRLISTLEN=memberlistlen

MBRLISTLEN=(r1-r12)

Specifies the length of the member list that is specified on the MBRLIST parameter.

TYPELIST=typelist

TYPELIST=(r1-r12)

Specifies a type list that identifies the valid IMSplex member types from which to receive unsolicited output messages. Do not specify the TYPELIST parameter if you specify the MBRLIST parameter. For valid IMSplex member types, see the TYPE= parameter description in CSLSCREG: registration request. If you do not specify either TYPELIST or MBRLIST parameter, the default list is all command processing clients in the IMSplex.

Use commas to separate the client names.

TYPELISTLEN=typelistlen

TYPELISTLEN=(r1-r12)

Specifies the length of the type list that is specified by the TYPELIST= parameter.

RETNAME=omname

RETNAME=(r1-r12)

Specifies an 8-byte output field to receive the name of the OM to which the subscription request is sent.

RETTOKEN=omscitoken

RETTOKEN=(r1-r12)

Specifies a 16-byte output field to receive the OM SCI token that is returned to the caller. This is the SCI token for the target OM address space to which SCI sent the request.

RETCODE=returncode

RETCODE=(r1-r12)

Specifies a 4-byte field to receive the output return code. OM return codes are defined in the CSLORR. SCI return codes are defined in CSLSRR.

OM or SCI provides the return code. The value of the high-order byte in the return code identifies whether SCI (X'01') or OM (X'02') provided the return code.

RSNCODE=reasoncode

RSNCODE=(r1-r12)

Specifies a 4-byte field to receive the output reason code. OM return codes are defined in the CSLORR. SCI return codes are defined in the CSLSRR.

SCITOKEN=scitoken

SCITOKEN=(r1-r12)

Specifies a 16-byte field that contains the SCI token, which uniquely identifies this connection to SCI. The SCI token is returned by a successful CSLSCREG FUNC=REGISTER request.

CSLOMSUB return and reason codes

The return and reason codes shown in the following table can be returned on a CSLOMSUB request.

Usage notes

If a SPOC subscribes to OM to receive unsolicited output messages, the default is to send all messages to that subscriber. You can prevent IMS, CQS, and CSL messages from being sent as unsolicited output by populating and maintaining a table of messages by using the following macros.

Macro

Description

CSLZUMT

Use this macro to populate table CSLZUMTU with CSL messages that should not be routed to subscribers as unsolicited messages.

CQSUOMT

Use this macro to populate table CQSUOMTU with CQS messages that should not be routed to subscribers as unsolicited messages.

DFSUOMT

Use this macro to populate table DFSUOMTU with IMS messages that should not be routed to subscribers as unsolicited messages.

Samples of the CQSUOMTU, CSLZUMTU, and DFSUOMTU tables are provided in the IMS sample library.

An example of the CSLZUMT macro is shown in the following example. In this example, messages CSL2020I and CSL2021E are added to the CSLZUMTU table, and are therefore prevented from being sent as unsolicited output messages to subscribed clients.

CSLZUMT MESSAGE=CSL2020I
CSLZUMT MESSAGE=CSL2021E

You can also specify MESSAGE=SUPPRESS in the CQSUOMTU, CSLZUMTU, and DFSUOMTU tables. For example, if the you code the following in message table DFSUOMTU, messages DFSxxxxx and DFSyyyyy will be sent to OM, message DFSzzzzz will not be sent to OM, and any other messages will not be sent to OM because of the MESSAGE=SUPPRESS statement:

DFSUOMT MESSAGE=DFSxxxxx,SEND=YES 
DFSUOMT MESSAGE=DFSyyyyy,SEND=YES 
DFSUOMT MESSAGE=DFSzzzzz,SEND=NO 
DFSUOMT MESSAGE=SUPPRESS

Another way to control which unsolicited output messages are sent to OM from IMS is to use the new UOM=MTO | NONE | ALL parameter for the DFSDFxxx and DFSCGxxx IMS PROCLIB members.

• With UOM=MTO specified, messages that are destined for the MTO only or system console (or both) only will be sent to OM. Messages being sent to other destinations, such as end user terminals, will not be sent to OM.
• With UOM=NONE specified, no messages will be sent to OM.
• With UOM=ALL specified, all messages will be sent to OM.