Command mapping for APPC mapped conversations

The following tables show the mapping between APPC verbs and CICS® commands for mapped conversations. See Return codes for APPC mapped conversations for details of the corresponding return code mapping.

MC_ALLOCATE
EXEC CICS ALLOCATE
+ EXEC CICS CONNECT PROCESS
LU_NAME(vble) SYSID on ALLOCATE
MODE_NAME(vble) MODENAME on ALLOCATE
TPN(vble) PROCNAME on CONNECT PROCESS (with PROCLENGTH)
RETURN_CONTROL(WHEN_SESSION_ALLOCATED) Default on ALLOCATE
RETURN_CONTROL(WHEN_CONWINNER_ALLOCATED) Not supported
RETURN_CONTROL
   (WHEN_CONVERSATION_GROUP_ALLOCATED)
Not supported
RETURN_CONTROL(IMMEDIATE) NOQUEUE/NOSUSPEND on ALLOCATE
SYNC_LEVEL SYNCLEVEL on CONNECT PROCESS
   0 - None
   1 - Confirm
   2 - Syncpoint
CONVERSATION_GROUP_ID Not supported
SECURITY(NONE) Not supported
SECURITY(SAME) Default on ALLOCATE
SECURITY(PGM(USED_ID(vble) Not supported
            (PASSWORD(vble)))
Not supported
PIP(NO) Supported by PIPLENGTH(0)
PIP(YES(vble1,vble2 ... vblen)) Supported by PIPLIST+PIPLENGTH
RESOURCE Returned in CONVID field
RETURN_CODE Supported

BACKOUT EXEC CICS SYNCPOINT ROLLBACK
RETURN_CODE Supported
MC_CONFIRM EXEC CICS CONFIRM
RESOURCE CONVID
RETURN_CODE Supported
REQUEST_TO_SEND_RECEIVED Returned in EIBSIG
MC_CONFIRMED EXEC CICS ISSUE CONFIRMATION
RESOURCE CONVID
RETURN_CODE Supported
MC_DEALLOCATE
  EXEC CICS SEND LAST
+ EXEC CICS SYNCPOINT
+ EXEC CICS FREE
RESOURCE CONVID
TYPE(SYNC_LEVEL) None
  EXEC CICS SEND LAST WAIT
+ EXEC CICS FREE
TYPE(SYNC_LEVEL) Confirm
  EXEC CICS SEND LAST CONFIRM
+ EXEC CICS FREE
TYPE(SYNC_LEVEL) Syncpt
  EXEC CICS SEND LAST
+ EXEC CICS SYNCPOINT
+ EXEC CICS FREE
TYPE(FLUSH)
  EXEC CICS SEND LAST WAIT
+ EXEC CICS FREE
TYPE(CONFIRM)
  EXEC CICS SEND LAST CONFIRM
+ EXEC CICS GDS FREE
TYPE(ABEND_PROG)
   Depends on setting of EIBFREE by
   previous command:
    EIBFREE = X'00
  EXEC CICS ISSUE ABEND
+ EXEC CICS FREE
    EIBFREE = X'FF
EXEC CICS FREE
TYPE(LOCAL) EXEC CICS FREE
RETURN_CODE Supported
MC_FLUSH
EXEC CICS WAIT 
or EXEC CICS SEND WAIT
RESOURCE CONVID
RETURN_CODE Supported
MC_GET_ATTRIBUTES
EXEC CICS EXTRACT PROCESS 
or EXEC CICS ASSIGN
RESOURCE CONVID on EXTRACT PROCESS
SYNC_LEVEL
SYNCLEVEL on EXTRACT PROCESS
  0 - None
  1 - Confirm
  2 - Syncpoint
PARTNER_LU_NAME ASSIGN PRINSYSID
PARTNER_FULLY_QUALIFIED_LU_NAME See note
MODE_NAME See note
CONVERSATION_STATE(vble) STATE on EXTRACT PROCESS
CONVERSATION_CORRELATOR See note
CONVERSATION_GROUP_ID Not supported
Note:
These values are not normally required in CICS applications and are not available at the API.
RETURN_CODE Supported
GET_TYPE (Examine EIBRSRCE)
RESOURCE EIBRSRCE
TYPE(vble)
EIBRSRCE set - mapped
EIBRSRCE not set - not mapped
MC_POST_ON_RECEIPT Not supported
MC_PREPARE_FOR_SYNCPT EXEC CICS ISSUE PREPARE
RESOURCE CONVID
RETURN_CODE Supported
MC_PREPARE_TO_RECEIVE EXEC CICS SEND INVITE
TYPE(SYNC_LEVEL) none EXEC CICS SEND INVITE WAIT
TYPE(SYNC_LEVEL) confirm EXEC CICS SEND INVITE CONFIRM
TYPE(SYNC_LEVEL) syncpt
  EXEC CICS SEND INVITE
+ EXEC CICS SYNCPOINT
TYPE(FLUSH) EXEC CICS SEND INVITE WAIT
TYPE(CONFIRM) EXEC CICS SEND INVITE CONFIRM
LOCKS(SHORT) Defaulted
LOCKS(LONG) Not supported
RETURN_CODE Supported
MC_RECEIVE_AND_WAIT
EXEC CICS RECEIVE [NOTRUNCATE] 
RESOURCE CONVID field
LENGTH(vble) Input MAXFLENGTH option
RETURN_CODE Supported
REQUEST_TO_SEND_RECEIVED Returned in EIBSIG
DATA INTO or SET option
MAP_NAME Not supported
WHAT_RECEIVED
            CONFIRM
            CONFIRM_DEALLOCATE
            CONFIRM_SEND
            DATA_COMPLETE
            DATA_INCOMPLETE
            DATA_TRUNCATED
            
            FMH_DATA_COMPLETE
            FMH_DATA_INCOMPLETE
            FMH_DATA_TRUNCATED


            SEND
            TAKE_SYNCPT
            TAKE_SYNCPT_DEALLOCATE
            TAKE_SYNCPT_SEND
CICS Settings
  EIBCONF + EIBRECV  
  EIBCONF + EIBFREE  
  EIBCONF
  EIBCOMPL [+ EIBRECV]
 ¬EIBCOMPL [+ EIBRECV}
 ¬EIBCOMPL if NOTRUNCATE not 
   specified on RECEIVE
  EIBFMH + EIBCOMPL [+ EIBRECV]
  EIBFMH + ¬EIBCOMPL [+ EIBRECV]
  EIBFMH + ¬EIBCOMPL [+ EIBRECV]
   if NOTRUNCATE not specified
   on RECEIVE
 ¬EIBRECV + no other flags
  EIBSYNC + EIBRECV
  EIBSYNC + EIBFREE
  EIBSYNC     
Notes:
  1. Mapping of MC_RECEIVE_AND_WAIT to EXEC CICS RECEIVE is not always one to one.

    When a CICS RECEIVE command is issued, CICS returns all the information and data (the DATA, the WHAT_RECEIVED flags, and the RETURN_CODE) at once. On completion of a CICS command, more than one indicator may be set, as shown in the WHAT_RECEIVED mapping above. It may be necessary to perform more than one subsequent command to honor the actions required by the indicators. For this reason, the action flags must be saved when they are received (because the EIB can be overwritten by subsequent CICS commands), and then acted on one by one.

    APPC does not work this way; an MC_RECEIVE_AND_WAIT verb returns either data or information about the conversation state (as indicated by WHAT_RECEIVED), but never both.

    It is necessary to program round this difference in philosophy when translating APPC verbs into CICS commands.

  2. CICS EIBCOMPL settings are applicable only if NOTRUNCATE is specified on the CICS RECEIVE command.

    If NOTRUNCATE is specified, DATA_INCOMPLETE is indicated by a zero value in EIBCOMPL. CICS will save the remaining data for retrieval by subsequent RECEIVE NOTRUNCATE commands. EIBCOMPL is set when the last part of the data is passed back.

    If the NOTRUNCATE option is not specified, DATA_INCOMPLETE is indicated by the CICS LENGERR condition, and the data remaining after the RECEIVE is discarded.

MC_REQUEST_TO_SEND EXEC CICS ISSUE SIGNAL
RESOURCE CONVID field
RETURN_CODE Supported
MC_SEND_DATA EXEC CICS SEND
RESOURCE CONVID field
DATA FROM option
LENGTH LENGTH option
FMH_DATA(NO) Default
FMH_DATA(YES) See note
MAP_NAME(NO) Not supported
MAP_NAME(YES) Not supported
ENCRYPT(NO) Not supported
ENCRYPT(YES) Not supported
RETURN_CODE Supported
REQUEST_TO_SEND_RECEIVED Returned in EIBSIG
Note:
FMH_DATA(YES) permits the sending of LU6.1 FMHs within an APPC conversation (for example, when running a CICS program which was originally written for use on LU6.1). An LU6.1 FMH may be built either by using the EXEC CICS BUILD ATTACH command, prior to issuing the EXEC CICS SEND command, or by building the FMH within the program, putting it in the output area, and specifying the FMH option on the SEND command. Either of these two actions is equivalent to specifying FMH_DATA(YES)
MC_SEND_ERROR EXEC CICS ISSUE ERROR
RESOURCE CONVID field
RETURN_CODE Supported
REQUEST_TO_SEND_RECEIVED Returned in EIBSIG
SYNCPT EXEC CICS SYNCPOINT
RETURN_CODE
Zero - Control returned to program.
Non-zero -  CICS takes action to backout
       the UOW (and abend the task or set
       EIBRLDBK).
Note:
For certain specialized applications, the PREPARE flow (the first flow in syncpoint exchanges) may be sent for a particular conversation by using the command:
EXEC CICS ISSUE PREPARE       
This enables any outstanding messages in the network (for example, SEND ERROR) to be received before proceeding, or deciding not to proceed, with the full syncpoint.
MC_TEST Check EIB flags
RESOURCE EIBRSRCE
TEST(POSTED) Check EIB flags
TEST(REQUEST_TO_SEND_RECEIVED) Check EIBSIG
RETURN_CODE Not supported
WAIT Not supported

Return codes for APPC mapped conversations

APPC RETURN_CODE CICS return codes
OK EIBERR zero + INVREQ not raised
ALLOCATION_ERROR
  Local allocation failures:
CICS is unable to allocate a session for an ALLOCATE command.
    ALLOCATION_FAILURE_NO_RETRY
SYSIDERR raised

The second and subsequent bytes of EIBRCODE give further information

    ALLOCATION_FAILURE_RETRY
SYSBUSY raised if there is a HANDLE for it. Otherwise, CICS queues the request until a session is available

See also the UNSUCCESSFUL return code, which relates to the NOQUEUE option on the CICS ALLOCATE command.

  Remote allocation failures:
These will be returned to the program after the CONNECT PROCESS command has been issued, and the partner system has been unable to start the requested task. They may be returned on any subsequent command that relates to the session in use
CONVERSATION_TYPE_MISMATCH
TERMERR (EIBERRCD = 10086034)
    PIP_NOT_ALLOWED
TERMERR (EIBERRCD = 10086031)
    PIP_NOT_SPECIFIED_CORRECTLY
TERMERR (EIBERRCD = 10086032)
    SECURITY_NOT_VALID
TERMERR (EIBERRCD = 080F6051)
    SYNC_LEVEL_NOT_SUPPORTED_BY_PGM
TERMERR (EIBERRCD = 10086041)
    SYNC_LEVEL_NOT_SUPPORTED_BY_LU
INVREQ (EIBRCODE = E000000C)

Note: CICS remembers SYNC_LEVEL negotiated at bind time and does not permit a request to be sent for a sync level not supported by the remote LU.

    TPN_NOT_RECOGNIZED
TERMERR (EIBERRCD = 10086021)
    TRANS_PGM_NOT_AVAIL_NO_RETRY
TERMERR (EIBERRCD = 084C0000)
    TRANS_PGM_NOT_AVAIL_RETRY
TERMERR (EIBERRCD = 084B6031)
BACKED_OUT EIBSYNRB (EIBERRCD = 08240000)
DEALLOCATE_ABEND The transaction is abended with code AZCH (EIBERRCD = 08640000)
DEALLOCATE_NORMAL EIBFREE + ¬EIBERR
FMH_DATA_NOT_SUPPORTED TERMERR (EIBERRCD = 08890100)
MAP_EXECUTION_FAILURE
MAP_NOT_FOUND
MAPPING_NOT_SUPPORTED
Not applicable. Map requests are not sent because the option is not supported.
PARAMETER_ERROR This return code relates ONLY to the CICS ALLOCATE command. It is given when an invalid LU name or MODE name has been specified.
PARAMETER_ERROR (Invalid LU name)
SYSIDERR (EIBRCODE = D0 04 ..
                  or D0 0C ..)
PARAMETER_ERROR (Invalid mode name) CBIDERR raised for invalid PROFILE on ALLOCATE command.
PROG_ERROR_NO_TRUNC EIBERRCD = 08890000 (RECEIVE Only)
PROG_ERROR_PURGING CDBERRCD = 08890000
RESOURCE_FAILURE_RETRY EIBERRCD = A000
RESOURCE_FAILURE_NO_RETRY EIBERRCD = A000
UNSUCCESSFUL RETCODE = 01 04 04
This return code relates ONLY to the APPC ALLOCATE verb with RETURN_CONTROL(IMMEDIATE) specified. This is implemented in CICS with the NOQUEUE option on the ALLOCATE command. Control returned to the program because a session was not immediately available.
Note:
In all cases, where a value for EIBERRCD is given, EIBERR will be set to X'FF'. It is intended that the program should first test EIBERR and then examine EIBERRCD if additional information is required.
[[ Contents Previous Page | Next Page Index ]]