C and C++ programming restrictions and requirements

Some restrictions and requirements apply to a C or C++ program that is used as a CICS® application program.

Functions and commands that cannot be used

The following EXEC CICS commands, which are related to nonstructured exception handling, are not supported for C and C++ applications:
  • HANDLE ABEND LABEL(label)
  • HANDLE AID
  • HANDLE CONDITION
  • IGNORE CONDITION
  • PUSH HANDLE
  • POP HANDLE
The translator diagnoses use of these commands. HANDLE ABEND PROGRAM commands are allowed.

CICS does not support the system() function, but two CICS commands, LINK and XCTL , provide equivalent function.

CICS does not support extended precision floating point.

C++ does not support packed decimal data. The application has access to packed decimal data using the character string data type. No C++ standard library functions are available to perform arithmetic on this data, but you can write your own. When using CICS commands that have options to specify time (for example, the DELAY or POST commands), it is advisable to use the HOURS, MINUTES, and SECONDS options. You can define times by using the TIME or INTERVAL options, which are packed decimal data types, if you provide functions to handle them in your application.

C and C++ do not support the use of CICS commands in macros.

Native C or C++ file operations operate only on files that are opened with type=memory specified. I/O to CICS-supported access methods must use the CICS API.

All native C and C++ functions are allowed in the source program, but the following functions are not recommended. Some are not executable and result in return codes or pointers indicating that the function has failed. Some might work but can impact the performance or execution of CICS.
  • CDUMP
  • CSNAP
  • CTEST
  • CTRACE
  • CLOCK (The clock() function returns a value (time_t) of -1.)
  • CTDLI
  • SVC99
  • SYSTEM
  • SETLOCALE

Coding requirements

  • You can enter all CICS keywords in mixed case, except for CICS keywords on #pragma directives, which must be in upper case only.
  • Where CICS expects a fixed-length character string such as a program name, map name, or queue name, you must pad the literal with blanks up to the required length if it is shorter than expected. For EXEC DLI commands, the SEGMENT name is padded by the translator if a literal is passed.
  • Do not use field names that might be acceptable to the assembler, but that cause the C or C++ compiler to abend. These names include $, #, and @.
  • C++ uses '//' for single line comments. Do not put such a comment in the middle of an EXEC CICS command. For example, the following code is not valid: 
    EXEC CICS SEND TEXT FROM(errmsg)
LENGTH(msglen) // Send error message to screen
RESP(rcode)
RESP2(rcode2);
    The following code examples are valid: 
    EXEC CICS SEND TEXT FROM(errmsg)
LENGTH(msglen)
RESP(rcode)
RESP2(rcode2); //Send error message to screen
    EXEC CICS SEND TEXT FROM(errmsg)
LENGTH(msglen) /* Send error message to screen */
RESP(rcode)
RESP2(rcode2);

Condition handling

In a C or C++ application, every EXEC CICS command is treated as if the NOHANDLE or RESP option is specified. Therefore, the set of system action transaction abends that result from a condition occurring, but not being handled, is not possible. Control always flows to the next instruction, and the application is responsible for testing for a normal response.

COMMAREA

The address of the communication area is not passed as an argument to a C or C++ main function. This means that C and C++ functions must use ADDRESS COMMAREA to obtain the address of the communications area.

EIB

The address of the EXEC interface block (EIB) is not passed as an argument to a C or C++ main function. This means that C and C++ functions must use ADDRESS EIB to obtain the address of the EIB. See Accessing the EIB from C and C++ for more information.

LENGTH

If you do not specify the LENGTH option on commands that support LENGTH (for example, READ , READNEXT , READPREV , and WRITE commands), the translator does not supply a default value. In effect, NOLENGTH is implicit for C programs.

OVERFLOW conditions

If you want any OVERFLOW condition to be indicated in the RESP field on return from a SEND MAP command with the ACCUM option, you should specify the NOFLUSH option.

Addressing mode

All C and C++ language programs running under CICS must be link-edited with the attributes AMODE(31), RMODE(ANY). They can reside above the 16 MB line.
Consequently, when you pass parameters to a program that is produced by the Cross-System Product (CSP) interactive application generator, you must do one of the following:
  • Pass parameters below 16 MB
  • Re-link the CSP load library with AMODE(31)

64-bit addressing mode (AMODE(64)) is not supported for C and C++ language programs.

64-bit residency mode

CICS does not support 64-bit residency mode (RMODE(64)) and treats any RMODE(64) programs as RMODE(31). That is, RMODE(64) programs are loaded into 31-bit (above-the-line) storage, not 64-bit (above-the-bar) storage.

Return value

If you terminate a C or C++ program with an exit() function or the return statement instead of a CICS RETURN command, the value passed through the exit() function is saved in the EIBRESP2 field of the EIB on return from the program.
Note: If a program uses DPL to link to a program in another CICS region, EIBRESP2 values from the remote region are not returned to the program doing the DPL.

Data declarations

The following data declarations are provided by CICS for C and C++:
  • Execution interface block definitions (EIB). The EIB declarations are enclosed in #ifndef and #endif lines, and are included in all translated files. The C or C++ compiler ignores duplicated declarations. The inserted code contains definitions of all the fields in the EIB, coded in C and C++.
  • BMS screen attributes definitions: C and C++ versions of the DFHBMSCA, DFHMSRCA, and DFHAID files are supplied by CICS, and can be included by the application programmer when using BMS.
  • DL/I support: a C language version of DFHDIB is included by the DLI translator if the translator option has been specified. (You must include DLIUIB if the CALL DLI interface is used.)

Fetch function

Language Environment® -conforming programs support the fetch() and release() functions. Modules to be fetched must be defined as PROGRAM resources to CICS, either explicitly or implicitly through autoinstall.

Locale functions

All locale functions are supported for locales that have been defined in the CSD. The setlocale() function returns NULL if the locale is not defined.

Debugging functions

The dump functions csnap(), cdump(), and ctrace() are supported. The output is sent to the CESE transient data queue. The dump cannot be written if the queue does not have a sufficient record length (LRECL). An LRECL of at least 161 is recommended.

iscics function

The iscics() function can be useful if you are adapting an existing program, or writing a new program, that is designed to run outside CICS as well as under CICS. The function returns a non-zero value if your program is currently running under CICS, or zero if it is not. This function is an extension to the C library.

String handling functions

The string handling functions in the C or C++ standard library use a null character as an end-of-string marker. Because CICS does not recognize a null as an end-of-string marker, you must take care when using C or C++ functions, for example strcmp, to operate on CICS data areas.

argc and argv arguments

Two arguments, argc and argv, are normally passed to a C or C++ main function. argc denotes how many variables have been passed; argv is an array of zero-terminated variable strings. In CICS, the value of argc is 1, argv[0] is the transaction ID, and argv[1] is NULL.