C and C++ programming considerations

All the EXEC CICS® commands available in COBOL, PL/I, and assembler language applications are also supported in C and C++ applications, with the exception of those commands related to nonstructured exception handling, see Nonstructured exception handling for more information.

C++ applications can also use the CICS C++ OO classes to access CICS services, instead of the EXEC CICS interface. See the CICS C++ OO Class Libraries manual, for more information about this interface.

Also note the following programming considerations:

Exception handling
nonstructured exception handling
The EXEC CICS commands related to nonstructured exception handling:
  • HANDLE ABEND LABEL(label)
  • HANDLE AID
  • HANDLE CONDITION
  • IGNORE CONDITION
  • PUSH HANDLE
  • POP HANDLE
are not supported in C and C++ applications. Use of these commands is diagnosed by the translator.
Condition handling
In a C or C++ application, every EXEC CICS command is treated as if it had the NOHANDLE or RESP option specified. This means that the set of "system action" transaction abends that result from a condition occurring but not being handled, is not possible in a C or C++ application. Control always flows to the next instruction, and it is up to the application to test for a normal response.
ABEND handling
HANDLE ABEND PROGRAM commands are allowed, but you cannot use PUSH HANDLE or POP HANDLE.
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 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.
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.
AMODE
All C and C++ language programs running under CICS must be link-edited with the attributes, AMODE(31), RMODE(ANY). They may reside above the 16MB line.
Invoking CSP programs
Consequently, when passing parameters to a program produced by the Cross-System Product (CSP) interactive application generator, you must either:
  • Pass parameters below 16MB, or
  • Re-link the CSP load library with AMODE(31).
Working storage
In C and C++, working storage consists of the stack and the heap. The location of the stack and heap, with respect to the 16MB line, is controlled by the ANYWHERE and BELOW options on the stack and heap run time options. The default is that both the stack and heap are located above the 16MB line.
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:
Start of change
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.
End of change
Sample programs
A set of sample application programs is provided in Table 1 to show how EXEC CICS commands can be used in a program written in the C or C++ language.
Table 1. Sample programs
Sample program Map set Map source Transaction ID
DFH$DMNU Operator instruction (3270) DFH$DGA DFH$DMA DMNU
DFH$DALL Update (3270) DFH$DGB DFH$DMB DINQ, DADD, DUPD
DFH$DBRW Browse (3270) DFH$DGC DFH$DMC DBRW
DFH$DREN Order entry (3270) DFH$DGK DFH$DMK DORD
DFH$DCOM Order entry queue print (3270) DFH$DGL DFH$DML DORQ
DFH$DREP Report (3270) DFH$DGD DFH$DMD DREP

The transaction and program definitions are provided in group DFH$DFLA in the CSD and should be installed using the command:

CEDA INSTALL GROUP(DFH$DFLA)

The following record description files are provided as C or C++ language header files:

Data declarations

The following data declarations are provided by CICS for C and C++:

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++.

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.
System function
CICS does not support the system() function, but two CICS commands, LINK and XCTL, provide equivalent function.
Macros
C and C++ do not support the use of CICS commands in macros.
Clock function
The clock() function returns a value (time_t) of -1.
Locale functions
All locale functions are supported for locales that have been defined in the CSD. CSD definitions for the IBM®-supplied locales are provided in member CEECCSD of the SCEESAMP library. 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
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 iscics() function may prove useful. It returns a non-zero value if your program is currently running under CICS, or zero otherwise. This function is an extension to the C library.
Restrictions
The following lists describe some of the restrictions that exist with C or C++ programs using Language Environment under CICS. You should check the relevant language guide for more specific details about those that apply to your installation:
Start of change

XPLink considerations for C and C++ programming

Extra Performance Linkage, (from here on it is abbreviated to XPLink), is a z/OS feature which provides high performance subroutine call and return mechanisms. This results in short and highly optimized execution path lengths.

Object Oriented programming is built upon the concept of sending 'messages' to objects which result in that object performing some actions. The message sending activity is implemented as a subroutine invocation. Subroutines, known as member functions in C++ terminology, are normally small pieces of code. The characteristic execution flow of a typical C++ program is of many subroutine invocations to small pieces of code. Programs of this nature benefit from the XPLink optimization technology.

MVS has a standard subroutine calling convention which can be traced back to the early days of System/360. This convention was optimized for an environment in which subroutines were more complex, there were relatively few of them, and they were invoked relatively infrequently. Object oriented programming conventions have changed this. Subroutines have become simpler but they are numerous, and the frequency of subroutine invocations has increased by orders of magnitude. This change in the size, numbers, and usage pattern, of subroutines made it desirable that the system overhead involved be optimized. XPLink is the result of this optimization.

PLEASE NOTE!

For z/OS 1.4 and above, and CICS TS 3.1 and above, the advice here that you CAN use the XPLINK compiler option with CICS application programs, overrides advice in z/OS and Language Environment manuals to the contrary.

z/OS and Language Environment manuals for C and C++ advise you that the XPLINK compiler option is not available to CICS application programs, because that used to be the case. Although these manuals are now being changed, you may be working with a copy of one of these manuals produced before this change.

The following topics cover:

XPLink, and the X8 and X9 TCBs

CICS provides support for C and C++ programs compiled with the XPLINK option by using the multiple TCB feature in the CICS Open Transaction Environment (OTE) technology. X8 and X9 mode TCBs are defined to support XPLink tasks in CICS key and USER key. Each instance of an XPLink program uses one X8 or X9 TCB.

To use XPLink, your C or C++ application code must be re-entrant and threadsafe. The same code instance can be executing on more than one MVS TCB and, without threadsafe mechanisms to protect shared resources, the execution behavior of application code is unpredictable. This cannot be too strongly emphasized.

Writing C and C++ programs, which are to be compiled with the XPLINK option, for the CICS environment

The application developer is expected to do the following to take advantage of CICS XPLink support;

All programs using CICS XPLink support must be re-entrant and threadsafe. Only the application developer can guarantee that the code for a particular application satisfies these requirements.

Passing control between XPLink and non-XPLink objects

Each transfer of control from XPLink objects to non-XPLink objects, or the reverse, causes a switch between the QR TCB and an open TCB, (either an X8 or an X9 TCB). In performance terms, TCB switching is costly, you must take this performance overhead into account.

An XPLink object can invoke a non-XPLink object using either the EXEC CICS interface or the Language Environment interface.

A non-XPLink object can only invoke an XPLink object using the EXEC CICS interface. Use of the Language Environment interface for such invocations is not supported.

Changing CICS definitions to obtain CICS support for objects compiled with the XPLINK option

CICS support for programs compiled with the XPLINK option requires only that you show in the PROGRAM resource definition that the program is threadsafe. This indication, and the XPLink "signature" in the load module, are the only things required to put the task on an X8 or X9 TCB.

In the selection of a suitable TCB for a particular program, XPLink takes precedence over the existence of the OPENAPI value for the API attribute on the PROGRAM resource definition.

.

Global User exits and XPLink

XPCFTCH
When the exit XPCFTCH is invoked for a C or C++ program that was compiled with the XPLINK option, a flag is set indicating that any modified entry point address, if specified by the exit, will be ignored.
XPCTA
When the exit XPCTA is invoked for a C or C++ program that was compiled with the XPLINK option, a flag is set indicating that a resume address, if specified by the exit, will be ignored.

Other Global User exits are unaffected by XPLink support.

End of change [[ Contents Previous Page | Next Page Index ]]