|
The data associated with an option is called its argument.
Five different types appear in the syntax diagrams:
- data-area
- data-value
- ptr-ref (for pointer-reference)
- ptr-value (pointer-value)
- cvda (CICS-value data area)
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 the CICS Application Programming Guide 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 the CICS Application Programming Guide and the CICS System Definition Guide, and the
TRANISOLATE option of a TRANSACTION definition in the CICS Resource Definition Guide.
- The MVS/ESA™ 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.
A pointer-reference (abbreviated ptr-ref in the diagrams) is a special case of a data-area.
It also is a receiver field, but CICS uses it to return a pointer to the data requested, rather than the data itself; that is, CICS
stores the location (address) of the data in the argument you provide.
A pointer-value (abbreviated ptr-value) is the pointer counterpart of a data-value; that is, you send information
to CICS in a pointer-value, but you provide the address of the data (a pointer to it), rather than the data itself.
The rules listed for data-areas therefore apply to pointer-references, and those for data-values to pointer-values.
Each language provides a type definition for pointers, and facilities for expressing address literals that can be used for pointer-values;
internally, pointers are stored in fullword binary form.
See the FREEMAIN command in the CICS Application Programming Reference manual for more information about the distinction between data
and pointers.
A CVDA (CICS-value data area) is still another special case: it is an argument to which CICS has assigned a specific and limited
set of meaningful values.
These values are named, both to make them intuitive and easy to remember and to keep the interface between user programs and CICS symbolic, so that
version and platform changes do not require program modifications.
Some CVDAs send information to CICS.
A sender CVDA is a special case of a data-value, and the rules for data-values apply.
Others return information from CICS, and you must use the rules for data-areas.
If there is any question about the direction in which the information is flowing, you can tell from the verb used in the option description.
Specifies means that you are sending information to CICS (that is, data-value rules apply); returns indicates that CICS will return
information in the argument (data-area rules apply).
CICS provides the code that converts CVDA value names to the corresponding numeric representations.
(Internally, CVDAs are stored as fullword binary numbers, and you must always provide a fullword binary area for options that receive
CVDA values.)
One way to send a CVDA value is simply to name the appropriate value (the name of the option is implied in the name of the value).
For example:
EXEC CICS SET PROGRAM (TAXPGM)
DPLSUBSET .
END-EXEC
Sets the EXECUTIONSET option value to DPLSUBSET.
EXECUTIONSET determines the set of commands which the program is allowed to use.
It has two possible values: DPLSUBSET, which restricts a program to the commands allowed in a program invoked by a distributed program link, and FULLAPI,
which does not restrict the command set.
The alternative is to use the CICS-provided DFHVALUE function, which relates the internal representation to the value name.
For example, this code is equivalent to the COBOL statement above:
MOVE DFHVALUE(DPLSUBSET) TO TAXAPI.
EXEC CICS SET PROGRAM (TAXPGM)
EXECUTIONSET(TAXAPI)
END-EXEC.
This technique is easier to use when program logic is complex.
You also use DFHVALUE when your program needs to interpret a value returned as a CVDA.
For example, if you needed to perform logic based on the EXECUTIONSET value, you would write something like this:
EXEC CICS INQUIRE PROGRAM (TAXPGM)
EXECUTIONSET (TAXAPI)
END-EXEC.
IF TAXAPI = DFHVALUE(FULLAPI)
PERFORM STND-INIT
ELSE
PERFORM REMOTE-INIT
END-IF
Appendix A. CICS-value data areas used by all commands lists all of the CVDA value names with corresponding numeric values.
These are for reference only, however; you should use value names and DFHVALUE in your code, to keep it version- and
platform-independent.
Here are examples in all the CICS-supported languages which show the use of CVDAs and the DFHVALUE function.
In each case, the code provided:
Only the code and definitions related to this part of each program are shown.
COBOL version
WORKING-STORAGE SECTION.
01 FILE-STATUS-INFO.
02 UOPST PIC S9(8) COMP.
02 UUPD PIC S9(8) COMP.
02 INFILE PIC X(8).
. . .
CICS-REQUESTS.
MOVE 'PAYROLL ' TO INFILE.
EXEC CICS INQUIRE FILE(INFILE)
OPENSTATUS(UOPST)
END-EXEC. .
IF UOPST = DFHVALUE(CLOSED)
MOVE DFHVALUE(UPDATABLE) TO UUPD
EXEC CICS SET FILE(INFILE)
UPDATE(UUPD)
NOTDELETABLE
END-EXEC.
EXEC CICS RETURN.
C version
#define INFILE "PAYROLL "
main()
{
long int uopst, /* OPENSTATUS value */
long int uupd; /* UPDATE value */
. . .
EXEC CICS ADDRESS EIB(dfheiptr);
EXEC CICS INQUIRE FILE(INFILE)
OPENSTATUS(uopst);
if( uopst == DFHVALUE(CLOSED) )
{ uupd = DFHVALUE(UPDATABLE);
EXEC CICS SET FILE(INFILE)
UPDATE(uupd)
NOTDELETABLE; }
EXEC CICS RETURN;
}
PL/I version
DCL (UOPST,UUPD) FIXED BIN(31), /*OPEN,UPD STATUS*/
INFILE CHAR(8); /*FILE NAME */
. . .
INFILE='PAYROLL ';
EXEC CICS INQUIRE FILE(INFILE)
OPENSTATUS(UOPST):
IF UOPST = DFHVALUE(CLOSED) THEN DO;
UUPD = DFHVALUE(UPDATABLE);
EXEC CICS SET FILE(INFILE)
UPDATE(UUPD)
NOTDELETABLE; END;
EXEC CICS RETURN;
Assembler-language version
DFHEISTG
UOPST DS F *OPEN STATUS
UUPD DS F *UPDATE STATUS
INFILE DS CL8 *FILE NAME
. . .
MVC INFILE,=CL8'PAYROLL '
EXEC CICS INQUIRE FILE(INFILE) X
OPENSTATUS(UOPST)
CLC UOPST,DFHVALUE(CLOSED)
BNE OPENLAB
MVC UUPD,DFHVALUE(UPDATABLE)
EXEC CICS SET FILE(INFILE) X
UPDATE(UUPD) X
NOTDELETABLE
OPENLAB EXEC CICS RETURN
Data types
For most arguments, CICS uses one of five data types (formats):
- Doubleword binary (eight bytes)
- Fullword binary (four bytes)
- Halfword binary (two bytes)
- Packed decimal (variable number of bytes)
- Character string (variable number of bytes)
The first four are all used for numeric data, but they differ in length and internal format; the last is for text.
The names used in this book are those used in assembler language.
Data-areas and data-values may require any of these formats.
The option text tells you which one to use.
CVDAs are always fullword binary.
Pointers are also stored in this form, although you generally define them explicitly as pointers or addresses.
There are a few exceptions to these types, including the component identifier arguments in the INQUIRE and SET TRACETYPE commands,
which are bit strings, options where the user determines the data format, and options for which CICS requires a specific structure.
These exceptions are rare in the SPI, however, and are always noted in the option description text.
The data types are the same regardless of the language of the program issuing the command.
However, the way you define data of a particular type varies with the language.
The rules are summarized in the language sections that follow, but there are other considerations unique to each language.
You should refer to the relevant language manual for information, although some language-specific information may be found in the
CICS Application Programming Guide.
COBOL argument values
In COBOL, you can use any data name of the correct data type for any argument.
For a data-value, you can also use a constant that can be converted to the correct type.
The ADDRESS special register can be used for both pointer-references and pointer-values, and the LENGTH
special register can be used for length arguments that take a data-value.
The table that follows indicates how to define the correct data type.
| Data type |
COBOL definition |
| Halfword binary |
PIC S9(4) COMP |
| Fullword binary (including CVDA) |
PIC S9(8) COMP |
| Doubleword binary |
PIC S9(18) COMP |
| Pointer |
USAGE IS POINTER |
| Character string (n characters long) |
PIC X(n) |
| Packed decimal (n decimal digits) |
PIC S9(n) COMP-3 |
C, and C++ argument values
In C, and C++, you can use any data reference of the correct data type for a data-area, data-value, or CVDA, provided the
reference is to contiguous storage.
In addition, for a data-value, you can use any C expression that can be converted to the correct data type.
The table below shows how to define the correct data type.
| Data type |
C definition |
| Halfword binary |
short int |
| Fullword binary (including CVDA) |
long int |
| Doubleword binary |
long long int |
| Character string (n characters long) |
unsigned char[n] |
| Packed decimal |
Not used--see note |
Note:
Packed decimal arguments are not supported in C, and C++.
Whenever there is an option that takes such an argument, there are other options that convey or return the same information in a format
supported by C, and C++.
|
Pointer-reference and pointer-value arguments can be any C, or C++ pointer reference, and pointer-values can also be any C, or C++
expression that can be converted to an address.
CICS calling sequences pass arguments by reference (the MVS™ convention), rather than by value (the C convention).
Ordinarily, the translator makes the necessary adjustments, but there are some situations in which you need to prefix your argument
with an ampersand (&).
See the C discussion in the CICS Application Programming Guide for details on arguments and other aspects of writing CICS
programs in C, and C++.
PL/I argument values
In PL/I, an argument can be any PL/I data reference of the correct data type, provided the reference is to connected storage.
In addition, a data-value, a pointer-value, or sender CVDA can be any PL/I expression that can be converted to the required type,
including one containing built-in functions like ADDR or LENGTH.
The table below shows how to define the correct data type:
| Data type |
PL/I definition |
| Halfword binary |
FIXED BIN(15) |
| Fullword binary (including CVDA) |
FIXED BIN(31) |
| Doubleword binary |
FIXED BIN(63) |
| Pointer |
POINTER |
| Character string (n characters long) |
CHAR(n) |
| Packed decimal (n decimal digits) |
FIXED DEC(n,0) |
PL/I requires that the data type, precision, length, and alignment attributes of a variable passed in a CALL statement match those of
the corresponding argument on the ENTRY statement for the called procedure.
If the attributes do not match, the PL/I compiler substitutes a dummy variable for the one specified in the CALL.
The translator generates ENTRY statements when it translates your CICS commands to PL/I CALLs and, if there is a mismatch between the ENTRY
statement specification for an argument and the variable you specify, CICS gets a dummy variable instead of yours.
Although the compiler issues a warning message when it makes such a substitution, it is easy to miss the message, and the execution results
are almost never what was intended.
This occurs even if there is no difference in the way the compiler implements a particular attribute value.
The ENTRY statements that the translator generates specify data type, precision, and length, using the values shown in the table above.
Therefore, to prevent the compiler from substituting dummy variables, you must specify these attributes explicitly for variables used in
CICS commands unless they happen to match the defaults.
(Defaults come from a DEFAULT statement if you have used one, and from the compiler defaults otherwise.)
In contrast, the generated ENTRY statements do not specify the alignment attribute, and therefore the defaults apply.
This means that alignment agreement between an argument in a CICS option and the ENTRY statement occurs only if the argument has
default alignment, and happens automatically if you do not override PL/I’s defaults.
Defaults at an installation can change and, therefore, the safest policy is to specify data type, length, and precision
explicitly for variables used in CICS commands, and to omit the alignment specification.
If you use variable-length character strings, you need to be aware of another aspect of PL/I. PL/I prefixes character strings
defined as VARYING with a two-byte length field.
If you name such a string as a data-value, the data CICS receives starts with this length prefix--usually an unintended result.
(The length sent to CICS is whatever you specify in the associated length option or, if you omit it, the maximum length for the
string plus two for the length prefix.)
Similarly, if you name the string as a data-area, CICS stores the information requested starting at the length prefix.
CICS does not prefix character data with length, and so this also is usually unintended.
Assembler-language argument values
In assembler language, an argument calling for a data-area, data-value, or CVDA can be any relocatable expression that refers to
data of the correct type, including register forms such as 20(0,11), and forms that use the macro-replacement facilities.
You can use literal constants, such as =F‘1’ or =AL2(100), for data-values and sender CVDAs, but you should not use
them--or any other storage that is not to be modified--for receiver arguments.
Pointer arguments, in contrast, are conveyed through a general register in CICS assembler programs and, therefore, they must be
absolute expressions.
For a pointer-value, you specify the number of the register that contains the address of the data (loading the register first if
it doesn’t already point to it). For a pointer-reference, you specify the register in which CICS is to return
the address of the data. For example, after execution of:
EXEC CICS INQUIRE TASK LIST
LISTSIZE(LISTLEN)
SET (9)
the address of the task list is in register 9.
Argument lengths
Arguments in character form can be variable in length; the USERDATA option in the ACQUIRE TERMINAL command is an example.
Where this occurs, CICS provides an option with which you can specify the length of the data, and you must do so if you
are coding in C/370.
In COBOL, PL/I, and assembler, however, you do not ordinarily need to specify this option because, if you omit it, the
translator generates the length option and supplies the correct value using the language facilities.
In COBOL, for example, if you write:
EXEC CICS ACQUIRE TERMINAL('ABCD')
USERDATA(LOGONMSG) END-EXEC
the translator adds the USERDATALEN option, as if you had written:
EXEC CICS ACQUIRE TERMINAL('ABCD')
USERDATALEN(LENGTH OF LOGONMSG)
USERDATA(LOGONMSG) END-EXEC
Note that the translator gets the length directly from the variable name, so you must use a name with the correct length associated if
you omit the length option.
In COBOL, PL/I and assembler language, if the translator option NOLENGTH is used, the translator does not default the length options.
Null values
CICS defines a null value for most types of data.
CICS sets receiver option values to the null value corresponding to the data type for the option if the option does not apply in a particular situation,
and you can use them in sender options to indicate that you want no change to an option value.
(See the Inquiry commands and SET commands for more about these uses.)
The null value for each data type is listed below:
| Data type |
Null value |
| Character string (n characters long) |
n blanks (X'40') |
| Halfword binary |
-1 (X'FFFF') |
| Fullword binary |
-1 (X'FFFFFFFF') |
| Doubleword binary |
-1 (X'FFFFFFFFFFFFFFFF') |
| Pointer (address) |
X'FF000000' |
| CVDA (in receiver option) |
DFHVALUE(NOTAPPLIC) (-1 or X'FFFFFFFF') |
| CVDA (in sender option) |
DFHVALUE(IGNORE) (-1 or X'FFFFFFFF') |
© Copyright IBM Corp.
|
