CICS Node Error Program and Timeout Considerations for Natural

#### Search Results

Search

# CICS Node Error Program and Timeout 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 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 and timeout considerations.

The following topics are covered:

- Session Termination Not under Control of Natural CICS Interface

- Recovery Mechanisms

- NCIZNEP Setup

- NCIZNEP Functionality

- Timeout Handling

- API USR4006N for Session Retrieval or Cancellation

See also:

- For information on installing a CICS node error program, refer to the corresponding section in Installing Natural CICS Interface on z/OS in the Natural Installation documentation.

## 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.

4. A user has been inactive in the Natural terminal session for the period specified with the `TIMEOUT` parameter in the CICS segment of the RACF user profile.

## 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. Therefore, we strongly recommend that you set `COMARET=ON`.

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).

If an active and running Natural session is canceled

- using `CEMT SET TASK(...) FORCEPURGE`

- using `CEKL SET TASK(...) FORCEPURGE`

- by a CICS monitoring product

- by flushing the Natural session using SYSTP

the respective CICS task is terminated immediately with CICS abend AKEH without NCIZNEP being executed for session cleanup.

## NCIZNEP Setup

CICS provides the DFHZNEP default node error program (NEP) that is called when a user disconnects a terminal from the CICS region. Furthermore, CICS provides the DFHZNEPX sample program that is designed for customized error handling in order to invoke user-supplied error processors.

Natural CICS Interface provides the Natural-specific `NCIZNEP` node error program. You can use the `XNCINEP2` sample node error program in order to set up DFHZNEP and execute `NCIZNEP` to terminate a lost session. `XNCINEP2` can be used instead of the sample program DFHZNEPX.

`XNCINEP2` performs the following functions:

- 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.

- Calls the `NCIZNEP` module via `EXEC CICS LINK` which performs a Natural session cleanup.

The `XNCINEP2` sample program is supplied in the source library of Natural CICS Interface. If DFHZNEPX has already been customized, copy the relevant source code from `XNCINEP2` into DFHZNEPX and insert it into an appropriate position before the trailing `EXEC CICS RETURN` call in DFHZNEPX, considering other products or components for which error processing is performed.

## 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. See the installation procedure for Natural CICS Interface and the section CICS Startup Parameters in Installing Natural CICS Interface on z/OS in the Natural Installation documentation.

- Requirements for MRO/CICSPlex Environments

- Special Considerations for Adabas System Coordinator

### 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 Natural session can only be purged in the AOR where a transaction is started to purge the task.

- 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 for the `NCIZNEP` module as described in Installing Natural CICS Interface on z/OS 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.

## Timeout Handling

If a user session is timed out, the resources held by the Natural session are not released by CICS. A user session is timed out, for example, if the user has been inactive in the Natural terminal session for the period specified with the `TIMEOUT` parameter in the CICS segment of the RACF user profile.

In the case of a timeout due to the setting of the `TIMEOUT` parameter in the RACF user profile, the action that CICS performs is determined by the value of the `GNTRAN` system initialization parameter. Natural resources are not properly released if either `GNTRAN=NO` is set or the executed "good night" program does not call the `NCIZNEP` module.

To make sure that all resources held by Natural are properly released

1. For the `GNTRAN` parameter, specify a CICS transaction ID for which the `PROGRAM` attribute specifies `XNCIGNIT`.

2. Use the `XNCIGNIT` sample node error program supplied in the source library of Natural CICS Interface (see also Natural CICS Sample Programs) and define it in CICS.

   `XNCIGNIT` must be assembled and linked with the CICS `EXEC` interface modules DFHELII and DFHEAI0.

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

You must perform the following for MRO/CICSPlex environments:

- In the TOR, define and install the `XNCIGNIT` sample program and the CICS transaction ID for which the `PROGRAM` attribute specifies `XNCIGNIT`.

- In the `XNCIGNIT` sample node error program, add the `SYSID` parameter to the `EXEC CICS LINK` statement that executes `NCIZNEP`. `SYSID` must specify the system name of an AOR that relates to the TOR. You can specify any AOR, because a CICS task is not active for a session in an AOR when the session is timed out.

## API USR4006N for Session Retrieval or Cancellation

The USR4006N application programming interface (API) allows you to retrieve or cancel Natural sessions based on selection criteria, such as the period of inactivity of terminal sessions.

It can happen that all sessions are read sequentially to find one or more sessions that match a specified criterion because USR4006N is not able to randomly select sessions by a specific criterion. Therefore, we recommend that you execute USR4006N only occasionally, and only if you want to remove all Natural sessions that satisfy a specific criterion in a single run. Alternatively, you can use the `NCIZNEP` module and the `XNCIGNIT` sample node error program which operate on a single Natural session only and need not access all sessions.

### On this page

- Session Termination Not under Control of Natural CICS Interface
- Recovery Mechanisms
- NCIZNEP Setup
- NCIZNEP Functionality
- Timeout Handling
- API USR4006N for Session Retrieval or Cancellation