CICS Node Error Program Considerations for Natural

An active Natural session uses CICS resources such as thread storage, roll facility entries (that is, records in a VSAM RRDS file, in a CICS temporary storage queue or main memory) as well as swap pool slots or Roll Server slots. These resources are allocated by Natural CICS Interface and correctly released whenever a session under control of Natural CICS Interface terminates normally or abnormally.

If a Natural session termination is not controlled by Natural CICS Interface, a node error program helps to correctly release the acquired resources.

This document discusses CICS node error program considerations.

The following topics are covered:

See also:

Session Termination Not under Control of Natural CICS Interface

In the following situations, Natural CICS Interface does not receive control at session termination and, therefore, cannot properly release the resources still held by the session:

  1. A non-Natural program called by Natural issues an EXEC CICS ABEND CANCEL command to terminate the CICS task abnormally.

  2. Some CICS monitor products offer tools to purge CICS tasks, thus bypassing any abnormal termination exit set by the application.

  3. A user disconnects a terminal from the CICS region (by switching the power off or using an adequate session manager function) while the respective Natural session is not active in CICS (pseudo-conversational screen I/O) at that time.

Recovery Mechanisms

Natural CICS Interface provides some recovery mechanisms to recover from such situations.

For example:

Whenever a new Natural session is to be started, Natural checks whether another session with the same terminal ID is active. If such a session exists, it is logically terminated, and all its resources are released prior to starting the new session.

However, if COMARET=OFF is set in the NTCICSP macro, the information to resume a Natural session is kept in a CICS temporary storage record where the terminal ID is part of the storage queue name. As a result, another CICS user who tries to start a Natural session with this terminal ID will resume the old session rather than starting a new session.

CICS provides the node error program (NEP) exit interface DFHZNEP, which is called when a user disconnects a terminal from the CICS region. The session is lost if the user disconnects the terminal while the respective Natural session is not active in CICS. You can then use DFHZNEP to execute the Natural-specific NCIZNEP node error program and terminate the lost session. This program is delivered with Natural CICS Interface (see also Natural CICS Sample Programs).

NCIZNEP Functionality

NCIZNEP tries to resume a session asynchronously and subsequently terminate it logically based on the session restart information (NEXTTRANSID and restart data in COMMAREA or CICS temporary storage) of a terminal session with pending pseudo-conversational screen I/O.

Upon completion, NCIZNEP cleans the parameter input indicating to the caller (usually DFHZNEP) whether it has successfully completed its work and launches the cleanup task for the Natural session.

If more than one Natural CICS Interface version is active in a CICS system, cleanup processing performed by the called Natural version-specific node error program can fail, because the Natural session to be terminated is hosted by a different Natural CICS Interface version. Upon execution completion of NCIZNEP, DFHZNEP can test whether the operation was successful. If the operation was not successful, NCIZNEP will call another node error program related to a different Natural CICS Interface version.

If a user disconnects a terminal from the CICS region while the respective Natural session is not active in CICS, DFHZNEP can receive control more than once for various internal error codes, since each internal error code is related to a specific CICS error message.

If you want NCIZNEP to attempt to immediately purge a currently active Natural session for which NCIZNEP receives control, specify PURGE=YES for the NCIZNEP module link. See the installation procedure for Natural CICS Interface and the section CICS Startup Parameters in Installing Natural CICS Interface on z/OS or Installing Natural CICS Interface on z/VSE in the Natural Installation documentation.

Requirements for MRO/CICSPlex Environments

In general, the following is required for MRO/CICSPlex environments:

  • DFHZNEP and NCIZNEP must be installed in the TOR.

  • The NCIZNEP module must be defined in CICS with EXECKEY(CICS).

For MRO/CICSPlex environments where you want NCIZNEP to purge a currently active Natural session, consider the following additional requirements:

  • The NCIZNEP module must also be defined in the CICS AORs associated with a TOR.

  • A transaction ID must be defined for the NCIZNEP module in the CICS TOR and the AORs with the attributes TASKDATAKEY(CICS) and PRIORITY(255)

  • The transaction ID must also be specified with the NEPTRAN parameter in the CICS startup parameters in the NCIZNEP module as described in Installing Natural CICS Interface on z/OS or Installing Natural CICS Interface on z/VSE in the Natural Installation documentation.

  • The Natural transactions for which you want to purge currently active Natural sessions have to be defined in CICS with the attribute SPURGE(YES).

Special Considerations for Adabas System Coordinator

If you want to call the node error programs NCIZNEP (for Natural CICS Interface) and CORNEP (for Adabas System Coordinator) from DFHZNEP, you should consider that both NCIZNEP and CORNEP may attempt to release Adabas-related resources at the same time. In order to avoid interferences due to concurrent execution, always call NCIZNEP before CORNEP and slightly delay the start time of CORNEP to make sure that NCIZNEP has completed before CORNEP starts executing.

For more information, see the Adabas System Coordinator Installation documentation.

Sample Node Error Program

The source library of Natural CICS Interface contains the XNCINEP2 sample node error program for CICS which provides the following options:

  • XNCINEP2 enables an error processor to receive control for all possible error codes passed to DFHZNEP. If XNCINEP2 receives control, it issues a CICS trace request that shows with which error codes DFHZNEP has been invoked on certain actions and related TCTTE error information.

  • XNCINEP2 calls the NCIZNEP module via EXEC CICS LINK, which performs a Natural session cleanup.

If DFHZNEP has already been customized for an installation using the IBM supplied sample program DFHZNEPX, copy the relevant source code from XNCINEP2 into DFHZNEPX and insert it before the trailing EXEC CICS RETURN call in DFHZNEPX.