MSO/CICS Cooperative Processing Services

The CICS portion of the cooperative processing functions is provided in the IBI supplied module CMSOAPI. This module contains the functional code that supports the individual calls available to CICS transactions. When this module is link edited with a CICS transaction module, five functions become available to the module.

How to:

Use the CMSOLGN Function

Use the CMSORCV Function

Use the CMSOREC Function

Use the CMSOSTP Function

Use the CMSORSM Function

CMSOLGN: Logs a CICS user as an MSO FOCUS user and establishes a session between MSO FOCUS and CICS
CMSORCV: Interrogates MSO/CICS to identify the session that requires servicing, receiving data if sent.
CMSOREC: Reconnects to a session that is in an indeterminate state.
CMSOSTP: Stops or terminates the session. This cancels the users MSO FOCUS task.
CMSORSM: Sends data back to the FOCUS portion of a session or restarts a suspended MSO FOCUS session.

Syntax and descriptions of the functions follow:

Top of page

How to Use the CMSOLGN Function

This function starts an MSO session for the user by logging on to MSO. It defines the details of the MSO/CICS conversation processing that will take place.

CALL CMSOLGN(EIB, COMMAREA, MSONAME, USERWD, NEXTPROG, LOGONBUF)

where:

EIB: Is the CICS Exec data adapter control block.
COMMAREA: Is the CICS Communications Area.
MSONAME: Is the 4 byte name of the MSO CICS transaction. Each MSO transaction name corresponds to a single MSO region that may be connected to.
USERWD: Is the 4-byte user word to associate with an MSO session. It is an arbitrary 4-byte value that is returned by CMSOLGN. It represents a unique identifier for the conversation that this service just established. It will be returned when the CMSRCV is issued to identify the specific conversation that needs to be serviced
NEXTPROG: Is the 8-byte name of next program to call. It identifies the CICS user program that will be called when the CMSCOMM FUSELIB is invoked on the MSO side of the conversation. NEXTPROG is mutually exclusive with the LOGTRAN entry in the LOGONBUF control block. Only one of these parameters should be specified. They function identically. Cooperative processing support, that is, the ability to be called back at all, is enabled by specifying a NEXTPROG in CMSOLGN. Fill NEXTPROG with blanks or nulls if no callbacks are desired.
LOGONBUF: Is a required control block. It should be completely initialized to blanks (x'40') before individual fields are set. Some of the fields support the MSO Load Balancing feature.

An assembler copy file, CMSOAPIA, is supplied in MSO.DATA. This file maps the LOGONBUF. The fields and their meanings are listed in the table below. All fields are alphabetic.

Field Name	Length	Contents
LOGAPPL	8 bytes	A load balancing parameter that limits MSO region selection to those service groups that specify the same application name.
LOGSERV	8 bytes	Specifies the particular MSO Service Group that this user should be started in. It applies to load balancing as well as a single region MSO.
LOGTRAN	4 bytes	This defines the CICS transaction that will be invoked when the CICSCOMM FUSELIB routine is called in the MSO region. It is mutually exclusive with NEXTPROG in the invocation parameters. Only one should be specified.
LOGBREAK	4 bytes	Break key (PF/PAnn). Identifies the key that will unconditionally terminate the active MSO session.
LOGSUSP	4 bytes	Suspend key (PF/PAnn). Identifies the key that will cause the active MSO session to suspend operation. When this key is pressed, the LOGTRAN or NEXTPROG CICS transaction (whichever was specified) will be invoked in the CICS region.
LOGELVL	4 bytes	Error level (ALL,ERR,NONE). Controls what messages are displayed to the user when the MSO session ends. ALL - All messages are displayed ERR - Only error messages are displayed NONE - No messages are displayed
LOGGROUP	8 bytes	Logon group name. The load balancing group name. It controls the MSO load balancing group that the user will be started in.
LOGVALID	1 byte	Security check flag (N/Y). Y must be specified for the reconnect service (CMSOREC call) to work. In addition, UNIQUE=LOGONID must be specified in the MSO configuration file.
LOGINITM	1 byte	Suppress initialization message flag (N/Y). Y suppresses the MSO initialization message.
LOGFLAG1	1 byte	Reserved flag
LOGFLAG2	1 byte	Reserved flag
LOGRESV	20 bytes	Reserved
LOGACCT	40 bytes	Account. Specifies the MSO account field. This field will be recorded in the MSO SMF records when that feature is active.
LOGUPRM	256 bytes	Logon parameter. The content of this field is available to FOCEXECs via the MSOINFO subroutine. It is generally used to provide control information to the MSO profile exec so that specific FOCUS applications may be invoked in the MSO region.

Top of page

How to Use the CMSORCV Function

This function is used to interrogate the MSO/CICS control program. The returned parameters identify the particular conversation that had a status change, the current status of the conversation, and any data that may have been received from MSO. It is usually the first MSO/CICS Cooperative Processing service used in the transaction that is triggered by the CICSCOMM subroutine (NEXTPROG or LOGTRAN).

The FUNCTION field is set based on either an event in the MSO region or if an event in the CICS region caused the status. The FUNCTION codes that are returned are described in CMSORCV Function Codes.

CALL CMSORCV(EIB, COMMAREA, FUNCTION, CONNID, USERWD, INLEN, OUTLEN, BUFFER, ERRNUM)

where

EIB: Is the CICS Exec data adapter control block.
COMMAREA: Is the CICS Communications Area.
FUNCTION: Is the 4-byte callback function code. See CMSORCV Function Codes.
CONNID: Is the 4-byte connect id of MSO session. This value, together with USERWD, uniquely defines each MSO/CICS session.
USERWD: Is the 4-byte user word to associate with an MSO session. This value, together with CONNID, uniquely defines each MSO/CICS session.
INLEN: Is the 4-byte length of buffer inbound from FOCUS.
OUTLEN: Is the 4-byte length of return buffer expected by FOCUS.
When using the CMSORSM, the LENGTH parameter may not exceed the value of OUTLEN. If it does, the data presented to the MSO FOCEXEC is truncated to the value of OUTLEN.
BUFFER: Is the 256 byte inbound data buffer.
ERRNUM: Is the 4-byte FOCUS ending error number (function FIN) or 4. This field is a binary number and is mapped by the CMSOAPIA member of MSO.DATA. Possible returned values are described in section CMSORCV Function Codes.

Top of page

How to Use the CMSOREC Function

This function re-establishes a MSO/CICS session based upon the current user's CICS id. The connect id may be supplied if known. Otherwise, the function uses a connect id of 0 and the userid to identify the session. This condition may be caused by the user powering off their terminal while an MSO/CICS session is active and then logging on to CICS again.

Security flag - If the security flag in the logon buffer is set to yes, then the resuming or reconnecting userid is validated against the known userid. The reconnection is rejected if they do not match. If present, userid determination is subject to the MSCXUID exit. The default for the security flag in the logon buffer is no.

CALL CMSOREC(EIB, COMMAREA, MSONAME, CONNID, NEXTPROG)

where:

EIB: Is the CICS Exec data adapter control block.
COMMAREA: Is the CICS Communications Area.
MSONAME: Is the 4-byte name of MSO transaction.
CONNID: Is the 4-byte connect id of MSO session.
NEXTPROG: Is the 8-byte name of next program to call.

Top of page

How to Use the CMSOSTP Function

This function stops an MSO/CICS session immediately. MSO must have passed control to the CICSCOMM FUSELIB program before a stop can be issued. A CMSOSTP received while MSO is still in control is treated as a protocol error.

CALL CMSOSTP(EIB, COMMAREA, MSONAME, CONNID, NEXTPROG)

where:

EIB: Is the CICS Exec data adapter control block.
COMMAREA: Is the CICS Communications Area
MSONAME: Is the 4-byte name of MSO transaction.
CONNID: Is the 4-byte connect id of MSO session.
NEXTPROG: Is the 8 byte name of next program to call. This field specifies a CICS transaction to start if the current invocation fails and cannot be associated with a known session. If a session is identified then the nextprog that was specified in the CMSOLGN service for the identified session is called.

Top of page

How to Use the CMSORSM Function

This function sends data to an MSO FOCUS session that previously issued the CICSCOMM FUSELIB routine or resumes an existing MSO/CICS session that was suspended by the user with the suspend key. Data may be sent in both cases but will be ignored if the session is in a suspended state. A CMSORSM received while MSO is still in control is a protocol error. If there is data, a buffer is allocated which is freed by MSOCICS.

CALL CMSORSM(EIB,COMMAREA,MSONAME,CONNID,NEXTPROG,LENGTH,BUFFER)

where:

EIB: Is the CICS Exec data adapter control block.
COMMAREA: Is the CICS Communications Area.
MSONAME: Is the 4-byte name of MSO transaction.
CONNID: Is the 4-byte connect id of MSO session.
NEXTPROG: Is the 8-byte name of next program to call.
LENGTH: Is the 4-byte length of outbound buffer. Data sent to MSO FOCUS is truncated to the original length specified by INLEN on the MSO FOCEXEC call to CICSCOMM.
BUFFER: Is the outbound data buffer (up to 256 bytes).

Information Builders