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

- 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:
- DFH$DFIL--FILEA record descriptor
- DFH$DL86--L860 record descriptor
- Data declarations
-
The following
data declarations are provided by CICS for C and C++:
- Execution interface block definitions (EIB)
- BMS screen attributes definitions: C and C++ versions of the DFHBMSCA,
DFHMSRCA, and DFHAID files are supplied by CICS, and may 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 have to include DLIUIB if
the CALL DLI interface is used.)
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:
- CICS does not support extended precision floating point.
- C and C++ languages do not support packed decimal data. The application
has access to packed decimal data using the character string data type. No
C or C++ standard library functions are available to perform arithmetic on
this data, but you may write your own.
- You can easily use HOURS, MINUTES, and SECONDS options. You may define
expiration times using TIME or INTERVAL options if you provide functions to
handle them in your application.
- You can enter all CICS keywords in mixed case, except for CICS keywords
on #pragma directives, which must be in upper case only.
- 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.
- 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
may work but impact the performance or execution of CICS.
- CDUMP
- CSNAP
- CTEST
- CTRACE
- CLOCK
- CTDLI
- SVC99
- SYSTEM
- SETLOCALE
For further information see the relevant User’s Guide. Native C or C++ functions are implemented in the C or C++ runtime
library.
- Native C or C++ file operations operate only on files opened with type=memory specified. I/O to CICS-supported access methods
must use the CICS API.
- 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.
- 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.
- 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.
- Take care not to use field names, which, though acceptable to the assembler,
cause the C or C++ compiler to abend. These include $, #, and @.
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;
- Develop the code, strictly adhering to threadsafe programming principles
and techniques
- Compile the C or C++ program with the XPLINK option set on
- Indicate in the PROGRAM resource definition that the program is threadsafe
- Consider the use of CICSVAR in CEEUOPT or in #pragma,
(see note 3 in Defining runtime options for Language Environment for details).
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.
[[ Contents Previous Page | Next Page Index ]]