EVEMPINT: EVESCCCI Parameter List Copy Book

The EVEMPINT copy book describes the CICS Automation program-to-program interface parameter list on the CICS® side.

It consists of two parts: one part describes the input data for CICS transactions, and the other part describes the format of output requests from CICS transactions.

The following data area is passed to a started CICS transaction as result of a NetView CONVERSE or SEND request. The same data area is passed in the response area as result of a NetView RESPONSE, ACK, or NACK response. See EVESNCCI: NetView to CICS Communication Interface.

Note: The started transaction must obtain the input data using an EXEC CICS RETRIEVE command.

Name	Disp.	Length	Contents and description
INTIDENT	000	08	Provides an eye-catcher and a block format level.
INTREQID	008	16	This field contains the request identifier which is used to relate a response to a specific request. For a CONVERSE request from NetView, it contains the domainid\|\|opid concatenation specified on the EVESNCCI command. For responses from NetView, it contains the request identifier allocated by the EVESCCCI routine on a CICS CONVERSE request. This field is not used for a SEND request.
INTFNAME	024	08	Contains the function name specified with the EVESNCCI FUNCTION= keyword.
INTRTYPE	032	01	The response type: C for CONVERSE, S for SEND, R for RESPONSE, A for ACK, and N for NACK.
	033	03	Reserved (binary zeros).
INTDATAL	036	04	Contains the length of the request or response data. This field may have a 0 (zero) value. For an ACK response, this field is 0 (zero).
INTSDATA	040	nn	The request or response data, if any. The length of the response data is contained in the INTDATAL field.

The following fields are set by the caller of the EVESCCCI routine.

Name	Disp.	Length	Contents and description
OUTIDENT	000	08	Provides an eye-catcher and a block format level. Must be set to POUT0001.
OUTREQID	008	16	This field is used as a request identifier to relate a response to a specific CONVERSE request. For CICS CONVERSE requests this field is set by the EVESCCCI routine. For CICS responses, the field must be set by the caller (copied from INTREQID). This field is not used for SEND requests.
OUTFNAME	024	08	Specifies the function name. The EVENTASK initialization member must contain a SERVER=REQUEST entry (for CONVERSE or SEND) or a SERVER=RESPONSE entry (for RESPONSE) specification. For responses, this field is normally copied from the transaction input data (INTFNAME field) Note: If the name is less than eight characters, pad it with blanks.
OUTRTYPE	032	01	Specifies the type of command as REQUEST, SEND, RESPONSE, ACK, or NACK. REQUEST (also referred to as CONVERSE) and SEND are requests. RESPONSE, ACK, and NACK are responses. REQUEST starts a command processor or a command list in NetView. A response is expected. SEND also starts a command processor or a command list in NetView, but no response is expected. RESPONSE is used to send data to a NetView task. ACK signals the successful completion of a CONVERSE request. No data is provided. NACK signals the unsuccessful completion of a CONVERSE request. Data may optionally be provided (maximum of 100 bytes). It is recommended for health checking.
	033	01	Reserved (binary zeros)
OUTWAITC	034	02	Specifies the number of seconds (binary value) to wait for a response on a CONVERSE request. If the response does not arrive within the specified time interval, the timeout return code is passed to the caller. If binary zero is specified, the default wait interval (30 seconds) is used. The maximum binary value that can be specified is 999. The field must contain binary zeros for all requests other than CONVERSE.
OUTDATAL	036	04	This field must be set to the length of the CONVERSE or SEND request data area or to the length of the RESPONSE or NACK response area. The maximum length of a CONVERSE or SEND request area or a RESPONSE response area is 32656 bytes. The maximum length of a NACK response area is 100 bytes.
OUTDATAA	040	04	Specifies the address of the CONVERSE or SEND request area or the address of the RESPONSE or NACK response area. If the request data address is located below the line, the response area (if any) is allocated below the line as well. If no data is passed on the CONVERSE request, the length field (OUTDATAL) must be zero. The address field is still used to determine the location of the response area in this case.

The following fields are set by EVESCCCI upon return to the caller:

Name	Disp.	Length	Contents and description
OUTRESPA	044	04	Address of response area allocated by EVESCCCI. It may contain a RESPONSE, ACK, or NACK response. This field is only returned on a successful CONVERSE request (OUTRTRNC=0). It is the responsibility of the caller of EVESCCCI to free the response area using EXEC CICS FREEMAIN.
OUTRESPL	048	04	Contains the length of the response area addressed by the OUTRESPA field.
OUTRTRNC	052	04	Contains the return code which will have one of the following binary values: 000 Successful request. 004 Timeout on CONVERSE. 008 Program-to-program interface not available (see OUTABNDC for error codes). A transaction dump is provided depending on the error code. 012 Incorrect parameter list. No transaction dump is provided. 016 Internal processing error (see OUTABNDC for error codes). A transaction dump is provided.
OUTABNDC	056	04	This field contains an error code for return codes 008 and 016. For return code 008 the field will have one of the following character values: C003 The CICS component of the program-to-program interface is not active. Use the COPS transaction to start it. No transaction dump is provided. An error message is logged. C015 A CICS LOAD of or LINK to a required module was not successful. Ensure that EVESPERR and EVESPMSG have been properly installed and are enabled. A transaction dump is provided. An error message is logged. C017 No CICS storage is available. No transaction dump is provided. C2xx A program-to-program interface request error occurred, where xx contains the program-to-program interface request return code. For error codes C220, C222, C223, C225, C231, C233, C236, C240, and C290, a transaction dump is provided and an error message is logged. For return code 016 the field will have one of the following character values: A* A CICS abend has occurred. A transaction dump is provided. An error message is logged for most A* errors. C012 An unexpected error has occurred on a READQ command. A transaction dump is provided. An error message is logged. C016 An unexpected error has occurred on a POST command. A transaction dump is provided. An error message is logged. C018 An unexpected error has occurred on a FREEMAIN command. A transaction dump is provided. C961 Internal error. Incorrect TS item length. A transaction dump is provided. An error message is logged. C962 Internal error. The RQE chain is corrupted. A transaction dump is provided. An error message is logged.

When a RESPONSE response (R) is sent, function is used to locate the name of a command processor or command list in the EVENTASK initialization member. This command is scheduled under a task (also defined in the initialization member) with the following command text:

Name	Disp.	Length	Contents and description
	000	8	Command processor or command list name
	008	8	(8 blanks)
RHDRCVID	016	8	Program-to-program interface receiver identification
RHDSNDID	024	8	Generic applid (Program-to-program interface sender identification)
RHDDOMID	032	8	domainid
RHDTSKID	040	8	opid
RHDPRCNM	048	8	Program-to-program interface sender’s JOB or STC name
RHDFNAME	056	8	function
RHDRTYPE	064	1	R
	065	7	******* (7 asterisks)
RHDSDATA	072	n	Response data (n = OUTDATAL)

Examples of Usage

Example 1

****************************************************************
*        ISSUE A CONVERSE REQUEST                              *
****************************************************************
*
         XC    CISPOUTP,CISPOUTP   ZERO PARAMETER LIST
         LA    R6,CISPOUTP         ADDRESS PARAMETER LIST
         USING OUTDSECT,R6         ESTABLISH ADDRESSABILITY
         SPACE 1
         MVC   OUTIDENT,=C'POUT0001' SET EYE CATCHER/BLOCK LEVEL
         MVC   OUTFNAME,=CL8'TESTCLST' SET FUNCTION NAME
         MVI   OUTRTYPE,OUTRTYPC   SET CONVERSE REQUEST TYPE
         LA    R1,L'CONVTEXT       LENGTH OF VARIABLE DATA
         ST    R1,OUTDATAL         SET LENGTH OF VARIABLE DATA
         LA    R1,CONVTEXT         ADDRESS OF VARIABLE DATA
         ST    R1,OUTDATAA         SET ADDRESS OF CONVERSE DATA
         MVC   CISHWORD,=Y(OUTHL)  LENGTH OF PARAMETER LIST
*
         EXEC  CICS LINK,          REQUEST PROGRAM LINK, TO            *
               PROGRAM('EVESCCCI'), CPDS COMMUNICATION INTERFACE       *
               COMMAREA(CISPOUTP), PARAMETER LIST                      *
               LENGTH(CISHWORD)    PARAMETER LIST LENGTH
*
         L     R15,OUTRTRNC        PICK UP THE RETURN CODE
*        Process the return code and error code!
*
         L     R4,OUTRESPA         ADDRESS RESPONSE AREA
         USING INTDSECT,R4         ESTABLISH ADDRESSABILITY
*
         LA    R14,INTSDATA        ADDRESS RESPONSE DATA
         L     R15,INTDATAL        LENGTH  RESPONSE DATA
*        Do some meaningful processing!
*
CONVTEXT DC    C'CONVERSE TEXT FROM CICS'
*
         DFHEISTG ,
*
CISPOUTP DS    CL(OUTHL)           RESPONSE PARAMETER LIST
CISHWORD DS    H                   PARAMETER BLOCK LENGTH
*
         DFHEIEND ,
*
         EVEMPINT ,                DEFINE INTERFACE DSECT

Example 2

This assembler example shows the processing of a NetView CONVERSE request in CICS.

****************************************************************
*        RETRIEVE TRANSACTION INPUT DATA                       *
****************************************************************
*
         EXEC  CICS RETRIEVE,      GET INPUT DATA              *
               SET(R4),            RETURN ADDRESS HERE         *
               LENGTH(CISHWORD)    RETURN LENGTH HERE
*
         USING INTDSECT,R4         ESTABLISH ADDRESSABILITY
*
         LA    R14,INTSDATA        ADDRESS REQUEST DATA
         L     R15,INTDATAL        LENGTH  REQUEST DATA
*        Do some meaningful processing!
*
****************************************************************
*        RETURN A 'NORMAL' RESPONSE                            *
****************************************************************
*
         XC    CISPOUTP,CISPOUTP   ZERO PARAMETER LIST
         LA    R6,CISPOUTP         ADDRESS PARAMETER LIST
         USING OUTDSECT,R6         ESTABLISH ADDRESSABILITY
*
         MVC   OUTIDENT,=C'POUT0001' SET EYE CATCHER/BLOCK LEVEL
         MVC   OUTREQID,INTREQID   SET REQUEST IDENTIFIER
         MVC   OUTFNAME,INTFNAME   SET FUNCTION NAME
         MVI   OUTRTYPE,OUTRTYPR   SET RESPONSE RESPONSE TYPE
         LA    R1,L'RESPTEXT       LENGTH OF VARIABLE DATA
         ST    R1,OUTDATAL         SET LENGTH OF VARIABLE DATA
         LA    R1,RESPTEXT         ADDRESS OF VARIABLE DATA
         ST    R1,OUTDATAA         SET ADDRESS OF RESPONSE DATA
         MVC   CISHWORD,=Y(OUTHL)  LENGTH OF PARAMETER LIST
*
         EXEC  CICS LINK,          REQUEST PROGRAM LINK, TO    *
               PROGRAM('EVESCCCI'), CPDS COMMUNICATION INTERFACE *
               COMMAREA(CISPOUTP), PARAMETER LIST              *
               LENGTH(CISHWORD)    PARAMETER LIST LENGTH
*
         L     R15,OUTRTRNC        PICK UP THE RETURN CODE
*        Process the return code and error code!
*
RESPTEXT DC    C'RESPONSE TEXT FROM CICS'
*
         DFHEISTG ,
*
CISPOUTP DS    CL(OUTHL)           RESPONSE PARAMETER LIST
CISHWORD DS    H                   LENGTH OF PARAMETER BLOCK
*
         DFHEIEND ,
*
         EVEMPINT ,                DEFINE INTERFACE DSECT