Using C for CICS Application Programs

CICS Considerations

This section provides a quick, overall look at how C interfaces with commonly used CICS components and features. Additional information is provided in subsequent chapters. In general, CICS sees SAS/C programs as assembler language programs. Therefore, SAS/C application programs are defined as assembler language programs to CICS in the processing program table (PPT).

Data Declarations for CICS

The following declarations may be needed, depending on your application:

execution interface block (EIB) definitions
basic mapping support (BMS) attribute definitions
DL/I support (DIB, DL/I header files).

When you use the SAS/C CICS Translator, the EIB and DIB are automatically included in your program. Include the header files for BMS and DL/I only if you are using those functions.

The header files necessary for these declarations were noted earlier in Header Files for SAS/C CICS Applications. The following sections introduce you to working with these components using C.

Using Global External Variables

CICS application programs typically require access to various CICS control blocks, notably the EIB, so that the programs can check return code values and so on. The SAS/C implementation provides several global external variables to address the most commonly referenced areas. This means you can bypass using either the ADDRESS EIB or the ADDRESS command to obtain control block information.

Note: In this context, global means these external variables are also shared with dynamically loaded modules. [cautionend]

The following global external variables are provided:

__commptr: points to the CICS COMMAREA (otherwise NULL).
__dibptr: points to the DL/I interface block.
__eibptr: points to the EIB.

The following examples illustrate how to use these variables.


Using __eibptr



.
.
.
switch(_eibptr->EIBRESP){
   case DFHRESP(NORMAL):
      break;
   case DFHRESP(NOTOPEN):
      return -1;
   default:
.
.
.
}


Defining your own __eibptr



.
.
.
struct EIBLK *my_eib_ptr;
EXEC CICS ADDRESS EIB(my__eib_ptr);
.
.
.
switch(my_eib_ptr->EIBRESP) {
.
.
.
}

Using __commptr
if (__commptr) { /* Because __commptr was not null, */ /* a COMMAREA was passed */ /* Perform "second" pass */ /* processing. */ EXEC CICS RECEIVE MAP... . . . } else { /* Because __commptr was null, */ /* no COMMAREA was passed; */ /* therefore, this must be */ /* the "first" pass. */ /* Display the main menu. */ EXEC CICS SEND MAP... . . . }


Using __dibptr



.
.
.
#define STATUS(code)

(memcmp(__dibptr->DIBSTAT,code,2)==0)
.
.
.

BMS Definitions

The BMS map language must be specified as assembler. The symbolic map (DSECT) must be processed by DSECT2C using this special compiler option: -d . To assist with this process under OS/390, the SAS/C Compiler and Library provides a DSECT2C cataloged procedure. Terminal Control and Basic Mapping Support provides complete documentation for SAS/C BMS considerations.

Supplying Arguments to main( )

The C main function can be passed arguments optionally. For CICS, the default arguments to main are similar to other traditional high-level languages under CICS, that is, a pointer to the execution interface block and a pointer to any COMMAREA (or a NULL pointer, if no COMMAREA exists). These arguments are supplied by the run-time library to main as an alternative to using the CICS global external variables described earlier in this chapter. To use this technique, code your program as follows:

main(struct EIBLK *eib_pointer, 
void *COMMAREA_pointer)
{
.
.
.
}

This is the default behavior by the run-time library if the linkage editor control statement ENTRY MAIN is used when linking your program. If a SAS/C program is invoked via a CALL statement to the MAIN entry point from another language, the CALL statement must pass pointers to the EIB and COMMAREA as the two parameters.

Alternatively, if you need to pass other parameters besides those of the EIB and COMMAREA, you can use the alternate entry points $MAINC and $MAINO. These entry points are primarily for use if your main program is invoked via a CALL statement from another language. When you use these entry points, the arguments to main are the more traditional argc and argv values. The argv vector is defined as follows:

/* pointer to transaction id  */
argv [0] char *tranid     
/* pointer to the EIB         */
argv [1] struct EIB *ptr  
/* pointer to any COMMAREA    */
argv [2] void *COMMAREA   
/* pointer to optional parm 1 */
argv [3] void *parm1      
.
.
.
/* pointer to optional parm n */
argv [n] void *parmn

When coding the CALL statement from another language, you can code the CALL statement specifying $MAINC or $MAINO directly. Again, the CALL statement must pass the EIB and COMMAREA pointers as the first two parameters followed, optionally, by other parameters. Note that the C run-time library processes this parameter list as a VL-style parameter list and does not convert the CICS pseudo-null COMMAREA pointer value of x'ff000000' to a NULL pointer. A pointer value of x'ff000000' always indicates the end of the parameter list. If you are passing optional parameters, you must pass a value of 0 if no COMMAREA is being passed to the called program. Because the library expects a VL-style parameter list when called through the entry points $MAINC/$MAINO, failing to pass one could cause the argc value to be incorrect or lead to other program failures.

For example, here is a short piece of COBOL code that calls the statically linked C routine named called1 :

PROCEDURE DIVISION.
 CALL 'CALLED1' USING DFHEIBLK DFHCOMMAREA.
 EXEC CICS RETURN END-EXEC.
 GOBACK.

And the following is representative of the way you can code the C routine called1 :

void called1()
{
   EXEC CICS ASKTIME;
}

The entry points $MAINC and $MAINO can also be used when a main program is invoked directly by CICS (either as the first program of a transaction or via a LINK or XCTL command). Select the entry point via the linkage editor control statement ENTRY $MAINC or ENTRY $MAINO. Note that ESA versions of CICS do not always construct VL-style parameter lists when calling programs directly; thus, you may get unpredictable results.

For more information about the entry points $MAINC and $MAINO, see Chapter 11, "Communication with Assembler Programs," in the SAS/C Compiler and Library User's Guide.

When the initial C function invoked by CICS is compiled with the indep compiler option, the arguments can have any type and, therefore, cannot be modified, or even inspected, by the library. In this case, _commptr is always set to NULL, argc is 0, and argv is NULL. For more information, see the SAS/C Compiler and Library User's Guide.

Handle Condition and Handle AID

Under CICS, your SAS/C program is responsible for handling conditions raised by CICS for each CICS command executed from your application. This means your program should test for a normal response; otherwise, a default system action occurs. You can test for a normal response by coding the RESP option on any CICS command, thereby testing the response code directly. Alternatively, you can code the HANDLE CONDITION and HANDLE AID commands as illustrated in the following sections.

HANDLE CONDITION

The standard syntax for this command is

EXEC CICS HANDLE CONDITION condition(label) ...

;

The SAS/C implementation is

EXEC CICS HANDLE CONDITION condition(function-name) ... ;

Here is an example:

EXEC CICS HANDLE CONDITION ERROR(errfunc);
   .
   .
   .
   void errfunc(int errcode)
   {
   .
   .  /* errcode is EIBRESP */
   .
   }

Normal return from the function is to the instruction immediately after the EXEC command that raised the condition. Note that your program can freely execute a longjmp() from the error handler.

HANDLE CONDITION and recursion

When you code the error-handling function, be careful not to issue a CICS command that could possibly raise an error condition. This could lead to recursion, for example, to an infinite loop or short-on-storage condition.

To avoid the possibility of recursion within the error-handling function, you can revert the error handling back to CICS with the following CICS command:

EXEC CICS HANDLE CONDITION ERROR;

Because no function is specified, you avoid the potential for recursion.

HANDLE AID

The syntax for this command is

EXEC CICS HANDLE AID option(label) ... ;

The SAS/C implementation is

EXEC CICS HANDLE AID option(function-name) ... ;

Here is an example:

EXEC CICS HANDLE AID PF1(help);
.
.
.
void help(int aid)
{
.
/* AID values are mapped in <dfhaid.h> */
.     
.
}

Standard return from the function is to the instruction immediately after the EXEC command that caused the AID to be transmitted to CICS.

Abend and Error Handling

All the error-handling, tracebacks, and messages you expect from the SAS/C Library are fully supported, including

signal handling
tracebacks
warning and error messages.

However, the label option of the EXEC CICS HANDLE ABEND command, coded as follows, is not supported:

EXEC CICS HANDLE ABEND LABEL(label);

If the label option is coded, the message LSCP038 is generated.

If your program issues any other variant of the command, it will completely override the run-time library's abend handling. In other words, any of the three following commands would override the run-time library's abend handling:

EXEC CICS HANDLE ABEND PROGRAM(name);
EXEC CICS ABEND CANCEL;
EXEC CICS PUSH HANDLE;

All abnormal termination messages are written to the transient data destination SASE. The output is prefixed with standard terminal and transaction identifier information.

SAS/C I/O Functions and CICS

Except for UNIX style I/O functions, all other SAS/C Library I/O functions for sequential input and output are supported for CICS applications. C also provides features for working with transient data and JES Spool File input and output, as well as support for DL/I and SQL. Handling Files provides details.

Environment Variable Support

With Release 6.00 of SAS/C, certain functions have been enhanced to support environment variables under CICS. Consult Chapter 4, "System Interface Functions and Environment Variables," and the function descriptions for getenv and putenv in SAS/C Library Reference, Volume 1 for details on this support.

Program Control

The CICS commands LOAD, RELEASE, LINK, RETURN, and XCTL are fully supported. COMMAREA is also fully supported and may be allocated anywhere that is convenient: the stack or the heap. Note that use of the XCTL or RETURN commands will terminate the C environment before execution of the command. This means that control will not return to the C program.

Interval and Task Control

The only SAS/C consideration in this area is to note that the sleep function is fully supported and recommended instead of DELAY. This is because sleep accepts an int argument rather than a packed decimal.

Debugging SAS/C CICS Applications

You can use the SAS/C Debugger with CICS in a remote session to debug your SAS/C application programs. This is documented in the SAS/C Debugger User's Guide and Reference. Also, the Execution Diagnostic Facility (EDF) is fully supported. Facilities such as CA-INTERTEST are also available, but no symbolic debugging is currently supported; that is, all debugging is done in assembler language mode.

Chapter Contents
Previous
Next
Top of Page