The parenthesized arguments that follow options in an API command are specified as follows:

• data-value
• data-area
• CICS-value data area (or cvda)
• pointer-value (or ptr-value)
• pointer-ref (or ptr-ref)
• name
• label
• hhmmss

Table 2. Arguments used in COBOL

In COBOL, you need not code the LENGTH option unless you want the program to read or write data of a length that is different from that of the referenced variable. To avoid truncation of data, compile COBOL programs with the NOTRUNC option.

Nota:

BLL cells and SERVICE RELOAD statements are not supported in the COBOL products that are used with TXSeries for Multiplatforms and IBM^(R) CICS for Windows.
Therefore, you must modify any COBOL programs that use BLL cells or SERVICE RELOAD statements before migrating.
For further information about migrating, see the TXSeries for Multiplatforms Application Programming Guide.

Replacing arguments when programming with C or C++

You can replace the arguments as follows:

Table 3. Argument values used in C or C++

Many commands involve the transfer of data between the application program and CICS. In most cases, the LENGTH option must be specified if SET is used; the syntax of each command and its associated options show whether this rule applies.

Replacing arguments when programming with PL/I

You can replace the arguments as follows:

• "data-value" can be replaced by any PL/I expression that can be converted to the correct data type for the argument. The data type can be specified as one of the following:
  • Halfword binary: FIXED BIN(15)
  • Fullword binary: FIXED BIN(31)
  • Character string: CHAR(n) where "n" is the number of bytes.

  "data-value" includes "data-area" as a subset.

• "data-area" can be replaced by any PL/I data reference that has the correct data type for the argument. The data type can be specified as one of the following:
  • Halfword binary: FIXED BIN(15)
  • Fullword binary: FIXED BIN(31)
  • Character string: CHAR(n) where "n" is the number of bytes.

  If the data type is unspecified, "data-area" can refer to an element, array, or structure; for example, FROM(P->STRUCTURE) LENGTH(LNG). The reference must be to connected storage.

  The data area must also have the correct PL/I alignment attribute: ALIGNED for binary items, and UNALIGNED for strings.

  If you use a varying data string without an explicit length, the data that is passed begins with two length bytes, and its length is the maximum length that is declared for the string. If you explicitly specify a length in the command, the data that is passed has this length; that is, the two length bytes followed by data up to the length that you specified.

• "ptr-value" (which includes "ptr-ref" as a subset) can be replaced by any PL/I expression that can be converted to POINTER.
• "ptr-ref" can be replaced by any PL/I reference of type POINTER ALIGNED.
• "name" can be replaced by either of the following:
  • A character string in single quotation marks (that is, a literal constant).
  • A PL/I expression or reference whose value can be converted to a character string with a length that is equal to the maximum length that is allowed for the name. The value of the character string is the name that is to be used by the argument.

  "filename", as used in FILE(filename), specifies the name of the file.
  It has 1 through 8 characters, which can be from A through Z, 0 through 9, $, @, and #, (lowercase characters are converted to uppercase).

  "systemname", as used in SYSID(systemname), specifies the name of the system to which the request is directed.
  It has 1 through 4 characters, which an be from A through Z, 0 through 9, $, @, and #, (lowercase characters are converted to uppercase).

• "label" can be replaced by any PL/I expression whose value is a label.
• "hhmmss" can be replaced by a decimal constant or an expression that can be converted to a FIXED DECIMAL(7,0). The value must be of the form 0HHMMSS+ where:

  HH

  represents hours 00 through 99.

  MM

  represents minutes 00 through 59.

  SS

  represents seconds 00 through 59.

If a DEFAULT DESCRIPTORS statement adds the UNALIGNED attribute to the ENTRY declarations that were generated by the CICS translator, data-area or pointer-reference arguments to CICS commands must also be UNALIGNED.
Similarly for the ALIGNED attribute, data-area or pointer-reference arguments must be ALIGNED.

Many commands involve the transfer of data between the application program and CICS.

In most cases, the length of the data that is to be transferred must be provided by the application program.
However, if a data area is specified as the source or target, it is not necessary to provide the length explicitly, because the command-language translator generates a default length value of either STG(data-area) or CSTG(data-area), as appropriate.

Data types used in C or C++

Nota:

Refer to for a description of the product path name.

The data types that are contained in cicstype.h are as follows:

Table 4. Data types contained in cicstype.h

Restrictions on the use of MBCS data

Some languages require characters to be represented by multiple bytes in what is called a multibyte character set (MBCS).
CICS supports application programs that use MBCS code pages.
This support is implemented with the cicstran -g option when the source code is translated.
See the TXSeries for Multiplatforms Application Programming Guide for information about cicstran.

Particular command options, however, accept only values that are received from the ASCII (single byte) character set.
In general, these are the options that correspond to the names of resources that CICS manages, such as files and transient data queues.

Where the application programming information documents the length as a number of bytes, such as 16-bit binary or 32-bit binary, that option is capable of accepting MBCS data.
Where the length is documented as a number of characters, the option accepts only ASCII.

Nota:

CICS for AIX and CICS for HP-UX are the only systems that supporta MBCS data.