HLI: IFAM2 CICS processing

Overview

This topic describes special requirements of CICS programs for application programmers who are using the Host Language Interface facility.

See HLI: Job requirements for information about HLI jobs running in IFAM2 under CICS.

See CICS interface configuration for information about the Model 204 CICS interface components.

CICS program link-editing requirements

The version of IFENTPS that is link-edited with your program must be assembled specifically for either macro- or command-level program code. To do this, set the conditional assembly flag &IFCALLR in the CICFG copy member.

IFENTPS requires that register 13 contain the following address.

For...	Register 13 must contain...
Macro-level module	18-word register save area
Command-level module	DFHEISTG storage area

CICS application program work areas

Before issuing any IFAM2 call, ensure that you can address the following CICS areas:

Common System Area (CSA)
Task Control Area (TCA)
Transaction Work Area (TWA)

Transaction work area (TWA)

The IFAM2 interface requires 88 bytes of CICS TWA area. When preparing an application program, ensure that the 88 bytes of the Transaction Work Area (TWA) are reserved for the CICS/Model 204 interface. The Model 204 TWA area may be displaced within the TWA area if application programs require the TWA area.

The area that Model 204 uses may be displaced within the TWA by setting the &IFTWADP in the CICFG copy member. The &IFTWADP value in the CICFG copy member specifies the number of bytes to displace the Model 204 TWA area. The value must be expressed in multiples of four because the Model 204 TWA area fullword-aligns.

Note: Both IFENTPS and IFPS must be assembled with the same CICFG copy member values. The TWA area is used to pass parameters between the two and, thus, must refer to the same area.

Your installation might include several compatible versions of IFENTPS and IFPS for applications that use different TWA areas. The CICS load module name that IFENTPS is linked to and its name in the CICS load library can be specified in &IFAM2LM within the CICFG copy member. During installation, take care that IFENTPS and IFPS are generated in compatible sets.

For example, consider a version of IFENTPS that has its TWA area displaced by 20 bytes and needs to link to a version of IFPS that also expects its TWA area to be displaced by 20 bytes. If the reference to the TWA area is the same, both a macro-level and a command-level version of IFENTPS can refer to the same copy of IFPS.

COBOL example of addressing the CICS areas

The following excerpt from a COBOL program illustrates how you can address the CICS areas (CSA, TCA, and TWA) for the interface from command-level CICS. You can also use this interface with macro-level CICS.

IDENTIFICATION DIVISION. . . . DATA DIVISION. WORKING-STORAGE SECTION. . . . LINKAGE-SECTION. 01 DYNAMIC-STORAGE-POINTERS. 05 FILLER PIC S9(8) COMP. 05 CSA-POINTER PIC S9(8) COMP. 05 TCA-POINTER PIC S9(8) COMP. 05 TWA-POINTER PIC S9(8) COMP. COPY DFHCSADS. COPY DFHTCADS. 01 TWA-AREA. 05 M204-INTERFACE-PORTION PIC X(88). 05 YOUR-TWA-PORTION PIC X(?). PROCEDURE DIVISION. EXEC CICS ADDRESS CSA(CSA-POINTER) END-EXEC. SERVICE RELOAD DFHCSADS. MOVE CSACDTA TO TCA-POINTER. SERVICE RELOAD DFHTCADS. EXEC CICS ADDRESS TWA(TWA-POINTER) END-EXEC. CALL 'IFCSA' USING DFHCSADS.

COBOL2 example of addressing the CICS areas

The following excerpt from a COBOL2 program illustrates how you can address the CICS areas (CSA and TWA) for the interface from command-level CICS.

IDENTIFICATION DIVISION. . . . DATA DIVISION. WORKING-STORAGE SECTION. * * * 01WK-ADR. 03CSA-POINTERPOINTER. 03TWA-POINTERPOINTER. * * * LINKAGE-SECTION. COPY DFHCSADS. * PROCEDURE DIVISION. * * EXEC CICS ADDRESS CSA(WKPTR1) END-EXEC. EXEC CICS ADDRESS TWA(WKPTR2) END-EXEC. SET ADDRESS OF DFHCSADS TO CSA-POINTER. SET ADDRESS OF TWA-AREA TO TWA-POINTER. CALL 'IFCSA' USING DFHCSADS.

Temporary storage queue

A temporary storage queue is created for each Host Language Interface transaction when the IFSTRT or IFDIAL call is issued. No other user program can use this queue. The name of the queue is:

CCAIxxxx

where xxxx is equal to EIBTRMID.

CICS abend handling

The Model 204 IFAM2 interface provides automatic abend handling that operates along with your application program abend handler, if any.

Whenever an abend occurs, open CRAM channels must be cleaned up and CICS resources must be released. If the IFAM2 abend handler is not in effect, the user application abend handler must perform these tasks. If the IFAM2 abend handler is in effect, the IFAM2 abend handler supersedes any user abend handler and performs these tasks automatically.

This section provides an overview of IFAM2 abend handling, followed by examples of suggested abend handling.

How to deactivate IFAM2 abend handling

To deactivate the automatic IFAM2 abend handling, set the &IFABEND parameter in the CICFG copy member to NO.

Protecting against abend exposure

Because CICS cancels abend handlers for pseudo conversational waits, an exposure gap in abend protection occurs after each pseudo conversational wait. During the time an application restarts after a pseudo conversational wait and before its next IFAM2 call, the transaction can abend without invoking the IFAM2 abend handler.

To prevent such an exposure, the application program must establish an abend handler immediately upon entering the program. This abend handler must call IFFNSH to close all CRAM channels and release all CICS resources, and must contain any application-specific logic. The program examples in the next section show coding that protects against this abend exposure.

If the application does not require its own abend handler, it can use the IFAM2 call, IFABXIT, which establishes the IFAM2 abend handler. IFABXIT is specific to the CICS environment and is for the convenience of the programmer.

Call IFABXIT as soon as possible after entering the program but only after the initial IFCSA call, which still must be the first call of any IFAM2 application session. The IFABXIT call protects the application against hung CRAM channels in the event of an abend prior to the first functional IFAM2 call.

How IFAM2 abend handling operates

The Model 204 IFAM2 abend handler is set by the first IFAM2 CICS call (other than IFCSA) and remains active until an IFHNGUP or IFFNSH call occurs, the transaction ends, or a pseudo conversational wait is entered. After a pseudo conversational wait, the abend handler is reset on the next IFAM2 call.

When it is invoked, the IFAM2 abend handler supersedes any user abend handler, operating differently in the macro- and command-level environments:

Macro-level coded applications cannot use the PUSH and POP commands. Applications that need their abend handler to be in effect after an IFAM2 call must reset their abend handler after returning from each IFAM2 call.
For command-level applications, the IFAM2 interface issues a PUSH HANDLE command to save the existing application's abend handler before establishing the IFAM2 abend handler.
In the event of an abend, the IFAM2 interface releases all CRAM channels and CICS resources. It issues a POP HANDLE command to restore the application's abend handler and then issues an abend call. The abend call drives the application's abend handler.

CICS abend handling: macro-level program

The following table shows recommended IFAM2 abend handling for a macro-level program.

This example assumes that the application's abend handler calls IFFNSH to clean up open IFAM2 CRAM channels and CICS resources.

CICS Macro-level program
Step	Program flow	Abend handler in effect
1.	Transaction start	No abend handler active
2.	IFCSA call	No abend handler active
3.	Next IFAM2 call	IFAM2 abend handler active
4.	Pseudo conversational wait	IFAM2 abend handler canceled
5.	Transaction restart	No abend handler active, exposure from CRAM channel recovery
6.	DFHPC TYPE=ABEND (or IFABXIT)	User abend handler active (IFAM2 abend handler active)
7.	IFAM2 call	IFAM2 abend handler active
8.	DFHPC TYPE=ABEND	User abend handler reset

The following points describe each step in the program flow:

The transaction program starts. Because no Model 204 CRAM channels are open and CICS resources are not allocated, there is no exposure.
An IFCSA call is issued. Prior to Model 204 Version 3.1, IFCSA had to be the first call of any IFAM2 application session. For Model 204 Version 3.1 and later, the IFCSA call is not required. For upward compatibility, the IFCSA call is allowed, but performs no function.
The first IFAM2 call after IFCSA is issued. During this call, the IFAM2 interface, IFENTPS, establishes the Model 204 abend handler. This remains in effect until the program ends or enters a pseudo conversational wait.
The transaction enters a pseudo conversational wait. CICS cancels the abend handler.
The transaction program resumes. No abend handler is active until the application program issues the first IFAM2 call. If an abend occurs, the CRAM channels are not closed, resulting in hung CRAM channels. Any CICS resources, such as storage and queue entries, are not released.
The transaction establishes its own abend handler as the first CICS call upon entry. Because the user abend handler is coded with an IFFNSH call, an abend within the user program calls the IFAM2 interface to close existing CRAM channels and release CICS resources.
Note: An alternative is to call IFABXIT, establishing the IFAM2 abend handler before any functional IFAM2 call.
An IFAM2 call is issued. The IFAM2 abend handler goes into effect.
The transaction reestablishes its own abend handler. Macro-level applications requiring their own abend handlers must reset their own abend handlers after each IFAM2 call.

CICS abend handling: command-level program

The following table shows recommended IFAM2 abend handling for a command-level program.