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 and timeout considerations.
The following topics are covered:
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.
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:
A non-Natural program called by Natural issues an
EXEC CICS ABEND CANCEL command to terminate the CICS
task abnormally.
Some CICS monitor products offer tools to purge CICS tasks, thus bypassing any abnormal termination exit set by the application.
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.
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.
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.
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 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.
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).
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.
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
For the GNTRAN parameter, specify a
CICS transaction ID for which the PROGRAM attribute specifies
XNCIGNIT.
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.
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.