Command mapping for APPC basic conversations

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

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

`ALLOCATE`	`EXEC CICS GDS ALLOCATE + EXEC CICS GDS CONNECT PROCESS`
`LU_NAME(vble)`	`SYSID on ALLOCATE`
`MODE_NAME(vble)`	`MODENAME on ALLOCATE`
`MODE_NAME('SNASVCMG')`	`MODENAME on ALLOCATE`
`TPN(vble)`	`PROCNAME on CONNECT PROCESS (with PROCLENGTH)`
`TYPE(BASIC_CONVERSATION)`	`Supported by GDS`
`TYPE(MAPPED_CONVERSATION)`	`Not supported`
`RETURN_CONTROL(WHEN_SESSION_ALLOCATED)`	`Default on ALLOCATE`
`RETURN_CONTROL(WHEN_CONWINNER_ALLOCATED)`	`Not supported`
`RETURN_CONTROL (WHEN_CONVERSATION_GROUP_ALLOCATED)`	`Supported`
`RETURN_CONTROL(IMMEDIATE)`	`NOQUEUE/NOSUSPEND on ALLOCATE`
`SYNC_LEVEL`	`SYNCLEVEL on CONNECT PROCESS` `0 ─ None` `1 ─ Confirm` `2 ─ Syncpoint`
`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 by GDS ASSIGN`
`RETURN_CODE`	`Supported`

BACKOUT

EXEC CICS SYNCPOINT ROLLBACK

RETURN_CODE

Supported

CONFIRM

EXEC CICS GDS CONFIRM

RESOURCE

CONVID

RETURN_CODE

Supported

REQUEST_TO_SEND_RECEIVED

Returned in CDBSIG

CONFIRMED

EXEC CICS GDS ISSUE CONFIRMATION

RESOURCE

CONVID

RETURN_CODE

Supported

DEALLOCATE

EXEC CICS GDS SEND LAST
+ EXEC CICS SYNCPOINT
+ EXEC CICS GDS FREE

TYPE(SYNC_LEVEL) None

EXEC CICS GDS SEND LAST WAIT
+ EXEC CICS GDS FREE

TYPE(SYNC_LEVEL) Confirm

EXEC CICS GDS SEND LAST CONFIRM
+ EXEC CICS GDS FREE

TYPE(SYNC_LEVEL) Syncpt

EXEC CICS GDS SEND LAST
+ EXEC CICS SYNCPOINT
+ EXEC CICS GDS FREE

TYPE(FLUSH)

  EXEC CICS GDS SEND LAST WAIT 
+ EXEC CICS GDS FREE

TYPE(CONFIRM)

  EXEC CICS GDS SEND LAST CONFIRM 
+ EXEC CICS GDS FREE

TYPE(ABEND_PROG)
   Depends on setting of CDBFREE by
   previous command:

    CDBFREE = X'00

  EXEC CICS GDS ISSUE ABEND 
+ EXEC CICS GDS FREE

    CDBFREE = X'FF

EXEC CICS GDS FREE

TYPE(ABEND_SVC) Not supported at API (option set 11)

TYPE(ABEND_TIMER) Not supported at API (option set 11)

TYPE(LOCAL) EXEC CICS GDS FREE

LOG_DATA(vble) Not available at API. CICS inserts the appropriate values

RETURN_CODE Supported

FLUSH

EXEC CICS GDS WAIT

GET_ATTRIBUTES

EXEC CICS GDS EXTRACT PROCESS
or EXEC CICS GDS ASSIGN
or EXEC CICS ASSIGN

RESOURCE

CONVID

SYNC_LEVEL

SYNCLEVEL on GDS EXTRACT PROCESS
  0 ─ None
  1 ─ Confirm
  2 ─ Syncpoint

UOW_IDENTIFIER

See note

OWN_FULLY_QUALIFIED_LU_NAME

See note

PARTNER_LU_NAME

GDS ASSIGN PRINSYSID

PARTNER_FULLY_QUALIFIED_LU_NAME

See note

MODE_NAME

See note

USERID

ASSIGN USERID

Note: These values are not normally required in CICS applications and are not available at the API.

RETURN_CODE

Supported

GET_TYPE

EXEC CICS GDS ASSIGN (+ return code test)

RESOURCE

PRINCONVID

TYPE(vble)

RETCODE
clear = GDS (BASIC)
03 04 = wrong conversation level

POST_ON_RECEIPT

Not supported

PREPARE_FOR_SYNCPT

EXEC CICS GDS ISSUE PREPARE

RESOURCE

CONVID

RETURN_CODE

Supported

PREPARE_TO_RECEIVE

EXEC CICS GDS SEND INVITE

TYPE(SYNC_LEVEL) none

EXEC CICS GDS SEND INVITE WAIT

TYPE(SYNC_LEVEL) confirm

EXEC CICS GDS SEND INVITE CONFIRM

TYPE(SYNC_LEVEL) syncpt

EXEC CICS GDS SEND INVITE
+ EXEC CICS SYNCPOINT

TYPE(FLUSH)

EXEC CICS GDS SEND INVITE WAIT

TYPE(CONFIRM)

EXEC CICS GDS SEND INVITE CONFIRM

LOCKS(SHORT)

Defaulted

LOCKS(LONG)

Not supported

RETURN_CODE

Supported

RECEIVE_AND_WAIT

EXEC CICS GDS RECEIVE
(for both LL and BUFFER)

RESOURCE CONVID field

FILL(BUFFER) BUFFER option

FILL(LL) LLID option

LENGTH(vble) Input MAXFLENGTH option

LENGTH(vble) Output FLENGTH option

RETURN_CODE Supported

REQUEST_TO_SEND_RECEIVED Returned in CDBSIG

DATA INTO or SET option

WHAT_RECEIVED
            CONFIRM
            CONFIRM_DEALLOCATE
            CONFIRM_SEND
            DATA
            DATA_COMPLETE
            DATA_INCOMPLETE
            LL_TRUNCATED
            SEND
            TAKE_SYNCPT
            TAKE_SYNCPT_DEALLOCATE
            TAKE_SYNCPT_SEND

CICS Settings
  CDBCONF + CDBRECV  
  CDBCONF + CDBFREE  
  CDBCONF
  FLENGTH field ¬= 0  [+ CDBRECV]
  CDBCOMPL [+ CDBRECV]
  ¬CDBCOMPL [+ CDBRECV]
  RETCODE = X'0310....' 
  ¬CDBRECV  
  CDBSYNC + CDBRECV 
  CDBSYNC + CDBFREE
  CDBSYNC

Notes:

Mapping of RECEIVE_AND_WAIT to EXEC CICS GDS 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, and then acted on one by one. If the same data area is used for CONVDATA on successive GDS commands, the flags are overwritten and lost.

APPC does not work this way; a 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.

APPC allows a RECEIVE_AND_WAIT to be issued immediately after an ALLOCATE verb. When you are writing basic conversations in CICS, however, you must supply the PREPARE_TO_RECEIVE explicitly, as follows:

ALLOCATE                 EXEC CICS GDS ALLOCATE
                        +EXEC CICS CONNECT PROCESS
(Required by CICS)       EXEC CICS GDS SEND INVITE WAIT
RECEIVE_AND_WAIT         EXEC CICS GDS RECEIVE

REQUEST_TO_SEND

EXEC CICS GDS ISSUE SIGNAL

RESOURCE

CONVID field

RETURN_CODE

Supported

SEND_DATA

EXEC CICS GDS SEND

RESOURCE

CONVID field

DATA

FROM option

LENGTH

FLENGTH option

RETURN_CODE

Supported

REQUEST_TO_SEND_RECEIVED

Returned in CDBSIG

ENCRYPT

Not supported

SEND_ERROR

EXEC CICS GDS ISSUE ERROR

RESOURCE

CONVID field

TYPE(PROG)

Default

TYPE(SVC)

Not supported

LOG_DATA

Not supported

RETURN_CODE

Supported

REQUEST_TO_SEND_RECEIVED

Returned in CDBSIG

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).

Notes:

EXEC CICS SYNCPOINT is not a GDS command.
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 GDS 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.

_TEST

_{Check CDB flags}

RETURN_CODE

Not supported

TEST(POSTED)

Check CDB flags

TEST(REQUEST_TO_SEND_RECEIVED)

Check CDBSIG

WAIT

Not supported

dfhp636.html | Timestamp icon

Last updated: Thursday, 27 June 2019

Command mapping for APPC basic conversations

Subtopics