Data-areas and data-values

Data-areas and data-values are the basic argument types. The difference between them is the direction in which information flows when a task executes a command.

A data-value is always, and exclusively, a sender: it conveys data to CICS that CICS uses to process the command. A data-area is a receiver; CICS uses it to return information to the caller. For example, in the command:

    EXEC CICS INQUIRE PROGRAM (TAXPGM)
              USECOUNT (UCNT) END-EXEC

PROGRAM is a sender option and TAXPGM is a data-value; it tells CICS where to find the name of the program you are inquiring about. USECOUNT is a receiver option, and UCNT is a data-area; CICS returns the information you requested (the use count for this program) there.

In general, you can use any area (variable) for a data-area, provided that:

The data type (format) is correct. The area must be long enough and, in high-level languages, the associated variable must be defined to have the correct length and internal representation. The data types that CICS uses are discussed in Data types.
The program logic allows the value to be changed (CICS stores into data-areas).
CICS re-entrancy rules allow the value to be changed. CICS loads only one copy of any given program, no matter how many tasks are using it. To prevent tasks executing the same program from interfering with one another, CICS keeps a separate copy of program areas that may change during execution (sometimes called working storage) for each task. This means that any area that may be modified, including data-area arguments to CICS commands, must reside either in such an area of the program or in storage outside the program which the application design allows the program to modify.
Some of this storage is allocated automatically; this category includes the WORKING-STORAGE section in COBOL programs, AUTOMATIC storage in PL/I and C/370, and areas appended to the DFHEISTG DSECT in assembler. It can also be allocated explicitly with a CICS GETMAIN command or a language facility such as a PL/I ALLOCATE statement, in this or a preceding program. This category includes the LINKAGE section in COBOL, BASED and CONTROLLED storage in PL/I, and other DSECTs in assembler. See Multithreading: Reentrant, quasi-reentrant, and threadsafe programs for more detail about CICS re-entrancy rules.
The program that issues the command has write access to the area. CICS changes the content of data-areas and, therefore, you cannot use storage that you are not allowed to change.
Write access is affected by the storage protection key in which the program is running, and by the transaction isolation status of its task. See the discussion of these subjects in Transaction isolation and Setting address space storage limits for a CICS region, and the TRANISOLATE option of a TRANSACTION definition in TRANSACTION attributes.
The MVS restrictions on addressing mode that apply to all CICS commands are observed. These are enforced automatically in high-level languages but, in assembler, the program must be in primary addressing mode, and the primary address space must be the home address space. All arguments for options must reside in the primary address space.
Note: CICS does not always preserve access registers across CICS commands or macro invocations. If your program uses access registers, it should save them before invoking a CICS service, and restore them before reusing them.

Any area that can be used for a data-area can also be used for a data-value. In addition, you can use areas not allowed for data-areas, because CICS never changes a data-value. In particular, you can use:

Constants, including literals. In the example above, for instance, you could use a literal instead of a variable for the program name:
```
EXEC CICS SET TDQUEUE ('TAX')
          TRIGGERLEVEL(1) END-EXEC
```
When you use a numeric literal in a command, the translator ensures a constant of the correct type and length, provided the literal is capable of being converted to such a constant, as in TRIGGERLEVEL above. In COBOL and assembler, the translator also ensures character literals of the correct length, padding with blanks if the literal is shorter than the length the argument requires. In C/370 and PL/I, however, you must do this yourself:
```
EXEC CICS SET TDQUEUE ('TAX ')
          TRIGGERLEVEL(1);
```
Other program areas not in working storage, such as static storage in PL/I.
Areas to which your program has read but not write access (the link-pack area, for example).

Note: Sometimes an option is used both to send and receive information, although this usage occurs more often in API than SPI commands. When it does, the argument must be a data-area, because CICS stores into it.