General rules

You write an XCICS program in much the same way as you write any other program. You can use COBOL, C, Java, or PL/I to write XCICS application programs. Most of the processing logic is expressed in standard language statements, but you use XCICS commands, or the Java class libraries to request CICS services.

This book describes the use of the CICS compatible command level programming interface, 'EXEC CICS', that can be used in COBOL, C or PL/I programs. These commands are defined in detail in the XCICS Command Reference.

Also Java interface APIs are described in the Java Programming chapter.User can write XCICS programs in much the same way as he writes any other program. He can use COBOL, C,  Java and PL/I to write XCICS application programs.

XCICS is source level compatible with IBM CICS (tm), so, in almost all cases, user can directly recompile its mainframe sources and let it run in the XFRAME environment.

EXEC CICS blocks

For COBOL, C and PL/I, XCICS commands must be specified in the IBM-like EXEC CICS instruction block.

In COBOL the EXEC block is terminated by END-EXEC.

In PL/I and C language, the EXEC CICS block is terminated by ";".

I.E.

COBOL:
MOVE A TO B
EXEC CICS HANDLE CONDITION
MAPFAIL (MAPF-01)
END-EXEC.
 
C language:
memcpy(b, t, 20);
EXEC CICS SEND TEXT FROM(t) LENGTH(20);

Exceptional Conditions Handling

CICS “EXCEPTIONAL CONDITIONs” or “CONDITIONs”, are defined to catch CICS errors.

Conditions may occur at any time during execution of a command and, unless it is specified otherwise in application programs.

If no handling has been set, a default action for each condition is taken automatically by XCICS. Usually, these default actions terminate tasks abnormally.

There are three possible states in which an application program can be, in respect with a particular condition detected during the attempted execution of a particular command, as follows:

HANDLE CONDITION active

In this case, control goes to the label in the program defined earlier by a HANDLE CONDITION command.

This state occurs later the execution of a HANDLE CONDITION.

Take no action

The control returns to the next instruction following the command which execution failed.

This state occurs after the execution of an INGNORE CONDITION. If there is no current HANDLE CONDITION command that includes a label.

This state also occurs during execution of a command including one of the options NOHANDLE or RESP.

Default action

For most conditions this is to terminate the task abnormally.

This state occurs if a HANDLE CONDITION has never been executed. This state also occurs after executing aHANDLE CONDITION without label or PUSH HANDLE.

Alternative to the HANDLE Command.

The NOHANDLE, RESP and RESP2 options (described below) are supplied as an alternative to the HANDLE command just described.

These commands too are fully supported by XCICS.

NOHANDLE Option

You can use the NOHANDLE option with any command to specify that you want no action to be taken for any condition or AID resulting from the execution of that command.

RESP Option

You can use the RESP option with any command to test the response to the execution of the command.

RESP (xxx)

“xxx” is a user-defined fullword binary data area. At the return from the command, it contains a value corresponding to the condition that may have been raised, or to a normal return, that is xxx = DFHRESP(NORMAL)

Handle Exceptional Condition (HANDLE CONDITION)

You use this command to specify the label to which control is to be passed if a condition occurs.

You must include the name of the condition and, optionally, a label to which control is to be passed if the condition occurs.

HANDLE CONDITION <condition> [(label)]

Ignore Exceptional Conditions (IGNORE CONDITION)

You use this command to specify that no action is to be taken if the condition occurs (that is, control to the instruction following to the command that has failed.

IGNORE CONDITION <condition>

Supported conditions

The following conditions can be referred in the HANDLE CONDITION and IGNORE CONDITION statements:

Suspend Condition Handling (PUSH and POP)

The commands PUSH and POP enable the suspension of all current HANDLE CONDITION, HANDLE AID, and HANDLE ABEND commands. This can be useful, for example, during a branch to a subroutine embedded in a main program.

PUSH HANDLE
POP HANDLE