EXEC CICS command format and programming considerations

EXEC CICS commands are used in applications that are written in Assembler, C, COBOL, or PL/I. The general format of an EXEC CICS command is EXECUTE CICS (or EXEC CICS) followed by the name of the required command, and possibly by one or more options.

For the equivalent commands in Java applications, see JCICS API mapping to EXEC CICS API.

EXEC CICS command format

The command format is as follows: 
EXEC CICS command option(arg)....
where:
  • command describes the operation required (for example, READ).
  • option describes any of the many optional facilities available with each function. Some options are followed by an argument in parentheses. You can write options (including those that require arguments) in any order.
  • arg (short for argument) is a value such as data-value or name. A data-value can be a constant; this means that an argument that sends data to CICS® is generally a data-value. An argument that receives data from CICS must be a data-area.

    Some arguments described as data-area can both send and receive data. In these cases, you must ensure that the data-area is not in protected storage.

Example of an EXEC CICS command
EXEC CICS READ
          FILE('FILEA')
          INTO(FILEA)
          RIDFLD(KEYNUM)
          UPDATE
You must add the appropriate end-of-command delimiter at the end of each EXEC CICS command, depending on the programming language.
Table 1. End-of-command delimiter by language
Language End-of-command delimiter
C/C++ Semicolon (;)
COBOL END-EXEC statement
PL/I Semicolon (;)
Restriction: In the C language, a null character can be used as an end-of-string marker, but CICS does not recognize this; you must therefore never have a comma or period followed by a space (X'40') in the middle of a coding line.

User code comments

If you want to add comments against EXEC CICS commands, you can do this, in Assembler only, by using a period or a comma as a delimiter after the last argument.

Example
EXEC CICS ADDRESS EIB(MYUEIB),        @F1A

If a period or a comma is used with an EXEC CICS command, the following line must begin between column 2 and column 16, with the continuation character in column 72. The following line cannot start after column 17. If there is no comma or period added, the following line must begin at or after column 2 and end by column 71, with the continuation character in column 72.

Common options for all EXEC CICS commands

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions.

You can use the RESP option with any command to test whether a condition was raised during its execution. With some commands, when a condition can be raised for more than one reason, if you have already specified RESP, you can use the RESP2 option to determine exactly why a condition occurred. The use of RESP implies NOHANDLE. For more information on the values of RESP, see EXEC interface block fields.

You can use the NOHANDLE option with any command to specify that you want no action to be taken for any condition or attention identifier (AID) resulting from the execution of that command. Using the C or C++ language implies NOHANDLE on all commands.

To learn about how you can handle exception conditions by using the NOHANDLE or RESP option on EXEC CICS commands, see Handling exception conditions by inline code.

NOHANDLE
Take no action for any condition or AID resulting from the execution of a command. This option turns off the CICS default exception handling on a specific EXEC CICS command call.
Example
The following example shows an EXEC CICS command that uses the NOHANDLE option. The command returns the address of the CWA in R3, if successful.
EXEC CICS ADDRESS CWA(R3) NOHANDLE
RESP(xxx)
This option also turns off the CICS default exception handling in the same way as the NOHANDLE option, but updates a user-defined fullword binary data area (xxx). On return from the command, it contains a value that corresponds to the condition that might be raised, or to a normal return, that is, xxx=DFHRESP(NORMAL). You can test this value by means of DFHRESP. For details, see Handling exception conditions by inline code.

Because the use of RESP implies NOHANDLE, use care when you use RESP with the RECEIVE command. NOHANDLE overrides both the HANDLE AID and the HANDLE CONDITION command, with the result that PF key responses are ignored.

RESP2(yyy)
yyy is a user-defined fullword binary data area. On return from the command, it contains a value that further qualifies the response to certain commands. Unlike the RESP values, RESP2 values have no associated symbolic names and there is no translator built-in function that corresponds to DFHRESP, so you must test the fullword binary value itself.
Example
The following example shows an EXEC CICS call in COBOL that uses the RESP and RESP2 options. 
EXEC CICS WRITEQ TS FROM(abc)
                    QUEUE(qname)
                    NOSUSPEND
                    RESP(xxx)
                    RESP2(yyy)
                    END-EXEC.

NOHANDLE, RESP, and RESP2 options are not explicitly included in the individual command syntax diagrams and option descriptions.

EXEC CICS command restrictions

Some general restrictions apply to all EXEC CICS commands that access user data.

  • The program must be in primary addressing mode when invoking any CICS service. The primary address space must be the home address space. All parameters passed to CICS must reside in the primary address space.
  • If your program uses access registers, CICS preserves only access registers 2 through 13, because CICS code can use access registers 0, 1, 14 and 15 for z/OS® macro calls.

EXEC CICS command syntax notation

In CICS documentation, EXEC CICS commands are presented in a standard way. You interpret the syntax by following the arrows from left to right. For an explanation of the syntax convention used in documentation, see Conventions and terminology used in the CICS documentation.

The EXEC CICS that always precedes each command's keyword is not included, nor any end-of-command delimiter.