CICS-value data areas (CVDA)

Some API commands have options that give the status or definition of a resource. For example, the STATE option on the CONNECT PROCESS command returns the state of the current conversation. Also, the INQUIRE and SET commands have many options that refer to resource status or definition. These options all have values that are CICS-supplied and are known as CICS-value data areas. They are shown in the syntax of commands with cvda in parentheses after the option name. In other contexts, uppercase letters (CVDA) are used.

You pass a CVDA value to CICS® in one of two ways, depending on the conditions:

In flexible form

You can use the DFHVALUE translator built-in function to assign a CVDA value to the 32-bit binary data area that is specified on the command, as in the following COBOL example:

MOVE DFHVALUE(EMPTYREQ) TO AREA-A.
EXEC CICS SET FILE(filename)
              EMPTYSTATUS(AREA-A)
              END-EXEC.

In short form

If the required CVDA value is always the same for a particular command, you can specify this value directly as an option on the command, as in the following COBOL example:

EXEC CICS SET FILE(filename)
              EMPTYREQ
              END-EXEC.

When an API command returns a CVDA value, define a 32-bit binary data area and pass this data area onto the appropriate command option. You can then use the DFHVALUE translator built-in function to test the returned value, as in the following COBOL example:

EXEC CICS CONNECT PROCESS ....
                  STATE(AREA-A)
                  END-EXEC.
IF AREA-A = DFHVALUE(ALLOCATED) THEN ...

Note: When using the Command-Level Interpreter (CECI) or the Execution Diagnostic Facility (EDF), CICS displays CVDAs on the screen as numeric values rather than as their corresponding symbolic names.

For a complete list of the CVDA symbolic names that are recognized by CICS and their associated numeric values, see CVDAs recognized by the translator.

For more information about the STATE option, see STATE.