Command mapping for APPC mapped conversations

The APPC verbs for mapped conversations are implemented by equivalent CICS application programming commands.

See Return codes for APPC mapped conversations for details of the corresponding return code mapping.

This table has two columns. The headers are in the first row.

`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:

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. 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 around this difference in philosophy when translating APPC verbs into CICS commands.
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, before 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