Command mapping for APPC basic conversations

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:
  1. 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.

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

Return codes for APPC basic conversations

APPC RETURN_CODE CICS return codes
OK CDBERR and RETCODE are zero
ALLOCATION_ERROR
  Local allocation failures:
CICS is unable to allocate a session for an ALLOCATE command.
    ALLOCATION_FAILURE_NO_RETRY
RETCODE = 01....

The second and subsequent bytes give further information

    ALLOCATION_FAILURE_RETRY
For temporary problems, CICS waits in the ALLOCATE command until the problem has cleared and then continues.

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

  Remote allocation failures:
These are 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
CDBERRCD = 10086034
    PIP_NOT_ALLOWED
CDBERRCD = 10086031
    PIP_NOT_SPECIFIED_CORRECTLY
CDBERRCD = 10086032
    SECURITY_NOT_VALID
CDBERRCD = 080F6051
    SYNC_LEVEL_NOT_SUPPORTED_BY_PGM
CDBERRCD = 10086041
    SYNC_LEVEL_NOT_SUPPORTED_BY_LU
RETCODE = 030C

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
CDBERRCD = 10086021
    TRANS_PGM_NOT_AVAIL_NO_RETRY
CDBERRCD = 084C0000
    TRANS_PGM_NOT_AVAIL_RETRY
CDBERRCD = 084B6031
BACKED_OUT CDBERRCD = 08240000
DEALLOCATE_ABEND_PROG CDBERRCD = 08640000
DEALLOCATE_ABEND_SVC CDBERRCD = 08640001
DEALLOCATE_ABEND_TIMER CDBERRCD = 08640002
DEALLOCATE_NORMAL CDBFREE + ¬CDBERR
PARAMETER_ERROR RETCODE = 01 0C ..

This return code relates ONLY to the ALLOCATE command (for CICS). It is given when an invalid LU name or MODE name has been specified. The third byte gives additional information.

PROG_ERROR_NO_TRUNC CDBERRCD = 08890000 (RECEIVE Only)
PROG_ERROR_TRUNC CDBERRCD = 08890001
PROG_ERROR_PURGING CDBERRCD = 08890000
RESOURCE_FAILURE_RETRY CDBERRCD = A000
RESOURCE_FAILURE_NO_RETRY CDBERRCD = A000
SVC_ERROR_NO_TRUNC CDBERRCD = 08890100 (RECEIVE Only)
SVC_ERROR_TRUNC CDBERRCD = 08890101
SVC_ERROR_PURGING CDBERRCD = 08890100
UNSUCCESSFUL

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.

RETCODE = 01 04 04

Control returned to the program because a session was not immediately available.

Note:
In all cases, where a value for CDBERRCD is given, CDBERR will be set to X'FF'. It is intended that the program should first test CDBERR and then examine CDBERRCD if additional information is required.
[[ Contents Previous Page | Next Page Index ]]