Natural CICS Interface Functionality

This document describes the functionality of the Natural CICS Interface.

It covers the following topics:


Natural CICS Interface

The Natural CICS Interface is implemented in command level Assembler, thus allowing Natural to be compatible with the CICS Multiple Region Option and the debugging facility CEDF.

The Natural CICS Interface controls session initialization, roll-in restart (in pseudo-conversational mode), terminal I/O, database access, ABEND processing, Natural local buffer pool calls and the loading, linking to and releasing of external subroutines. In addition, all roll I/O operations are made from the Natural CICS Interface.

Natural Nucleus under CICS

The Natural nucleus is a combination of the reentrant Natural module and various support routines, which are delivered as source programs requiring site-dependent assemblies and as load modules.

The CICS-related components of the Natural nucleus are:

  • the Natural CICS Interface module NCISTART

    This is the entry routine, which in particular prepares the Natural CICS Interface Language Environment (LE) linkage; see Natural CICS Interface and IBM Language Environment (LE). The module is CICS version dependent.

  • the Natural CICS Interface module NCIROOT

    This module holds all CICS related logic as CICS services and CICS control block access. The module is CICS version dependent.

  • the Natural CICS parameter module NCIPARM

    This module holds Natural CICS Interface runtime and system environment generation options. The module is not CICS version dependent, although some of the parameters should be set depending on the CICS version.

  • the Natural CICS Interface object-only part NCINUC

    This module holds service routines called by the Natural nucleus and Natural CICS Interface system control logic. These routines are independent of CICS and CICS version and are dealing with CICS by calling CICS service routines in NCIROOT and NCISTART.

  • the Natural CICS Interface module NCIXCALL

    This module is a separate program in CICS, that is, it is not linked to the Natural nucleus, as it is invoked via EXEC CICS LINK from 3GL programs called by Natural; see Natural 3GL CALLNAT Interface in the Operations documentation. The module is CICS version dependent.

System Control under CICS

Natural features specific to CICS include the organization of dynamic storage in threads and the additional capability of handling these threads so that the Natural CICS System Control Program can more efficiently handle dynamic storage.

The Natural CICS System Control Program was initially developed to overcome the 64 KB GETMAIN limit under CICS. It provides complete storage allocation and management functions, including roll file I/O operations and relocation functions for pseudo-conversational users.

In order to enhance the pseudo-conversational processing capabilities of Natural with CICS, the System Control Program uses threads, a contiguous amount of storage which is set up for each user. This structure allows Natural to manage dynamic storage with minimal CICS involvement.

A complete understanding of system control can be attained from the following discussion of its structure and operation. Ensure that you understand this mechanism before starting the installation procedure of Natural under CICS.

OSCOR/GETVIS - Natural Components in CICS Dynamic or Operating System Storage

Scenario 1:

Single CICS Region

The diagram below shows the components of the Natural system that reside in CICS dynamic storage. The components are explained under the following headings:

Scenario 1 applies when running Natural locally in a single CICS application region under z/OS or z/VSE.

Note:
Note Concerning z/OS Systems: Additional scenarios are possible. The following three diagrams show combinations of z/OS systems, CICS regions, the Natural Roll Server and the Natural Authorized Services Manager.

Scenario 2:

Single z/OS With Single CICS Region, Single Roll Server

Scenario 3:

Single z/OS With Multiple CICS Regions, Single Roll Server and (Optional) Authorized Services Manager

Scenario 4:

Multiple z/OS With Multiple CICS Regions, Multiple Roll Servers/Authorized Services Managers

Parameter Settings Required for the Above Scenarios

Module Scenario 1 Scenario 2 Scenario 3 Scenario 4
NTBPI (BPI) TYPE=SWAP,SIZE= nnn n/a n/a n/a
NCMDIR CICSPLX NO NO YES/MODE YES/MODE
NCMDIR SIPSERV NO NO/YES yes yes
NCMDIR ROLLSRV NO yes yes yes
Roll Server

CF structure name

n/a none none name
Authorized Services Manager/SIP n/a n/a SIP slot number/size XCF group name/CF structure name

The Natural CICS Interface requires a SIP slot size of 256 bytes.

Note:
For the scenarios 2, 3 and 4, the very first Natural session initializing the NCI environment must have the SUBSID parameter set to the value of the corresponding Roll Server and/or Authorized Services Manager.

Natural Storage Threads under CICS

A thread is a contiguous storage area from where Natural requests all its required storage. It can either be storage shared by several Natural users or, in 31-bit mode environments, CICS user storage above the 16 MB line dedicated to a specific task.

Each storage thread can be seen as the "address space" for a Natural user. Each memory allocation request issued by the Natural nucleus is transferred to the system control program to be satisfied from the storage thread.

Storage threads are allocated when the Natural CICS Interface is initialized. They are allocated in a CICS region or partition, in which case they are permanent (shared) threads or they are allocated during the start of a Natural CICS task, in which case they are exclusive threads (task-dependent user storage).

The technique of storage threads was implemented with Natural for the following reasons:

  • To overcome the 64 KB limitation of CICS for user storage in non-31-bit mode systems.

  • To be able to optimize rolling (formerly, each piece of user storage had to be written to the roll medium; now, as there is a contiguous storage area, this area is compressed by making the relevant portions contiguous to each other before rolling out).

  • The Natural CICS Interface tries to satisfy all GETMAIN requests of a Natural session from its thread. This is faster than GETMAIN requests by means of CICS service calls. This is particularly true for CICS command level calls, as the CICS EXEC Interface Program (EIP) is involved, too.

A thread is released by the owning task with every screen I/O. This is true for both conversational and pseudo-conversational tasks. When a session is resumed, its storage is rolled into a thread again, unless its storage is still there; that is, no other task used the thread in between.

The Natural thread selection algorithm balances thread usage to minimize roll I/O operations. This means that the more threads there are, the better is the chance of finding the old data thus preventing a roll-in. However, the more threads there are, the more paging the operating system must perform to keep all threads efficiently in real storage.

Threads are grouped together depending on their size and their type; that is, whether they have been pre-allocated as permanently shared storage or via a GETMAIN request. The decision on which kind of thread group to use, is controlled by the CICS transaction code at session initialization time. All storage threads belonging to the same group have the same size.

The thread should be defined as small as possible; see also the Buffer Usage Statistics function of the Natural utility SYSTP in the Natural Utilities documentation. However, the thread must still be large enough to hold the session with the largest sizes.

If you have separate Natural development and production environments, the rule is to have more smaller threads in the production environment (to serve production requests as soon as possible) and fewer larger threads in the development environment (as Natural programmers normally need larger Natural sizes and have longer "think times").

The very first Natural session allocates all permanent (shared) threads.

Natural Roll Facilities under CICS

As permanent storage threads are shared by several users and as larger threads allocated via GETMAIN should not be kept for too much time, a Natural task releases its thread with each terminal I/O. Previously, however, the user data have to be saved to be able to restart the Natural session after the terminal I/O has been performed.

Session data can be saved by using

  • the Natural Roll Server with its local roll buffer and roll files;

  • the CICS Roll Facilities;

  • the Natural swap pool.

See also the various component scenarios. For more information, see Roll Server in the Natural Operations documentation.

CICS Roll Facilities

CICS Roll Facilities are local CICS storage facilities. They can be either CICS main or auxiliary temporary storage or VSAM relative record data sets (RRDS) which the user has previously defined to CICS. These files allow Natural to store a user's compressed dynamic storage when a roll-out occurs.

When a swap pool is used, the CICS roll facilities only serve as backup for the swap pool. The choice of the roll medium is of greater importance when no swap pool is used, since it affects Natural performance and throughput.

Every CICS service request causes CICS system overhead. So, the larger the CISIZE/record size for the roll facility is, the less CPU overhead occurs due to fewer CICS service calls to roll a Natural session. On the other hand, larger CISIZE/record size also means more VSAM buffer space allocated for the roll facility.

See Performance Considerations for further information on roll facilities.

Warning:
When using the Roll Server, the swap pool and the CICS Roll Facilities are not available.

Natural Local Buffer Pool under CICS

The Natural local buffer pool contains all Natural modules during execution and copies of Natural modules once they have been loaded from the Adabas or VSAM system file.

The local buffer pool must be large enough to minimize the number of Natural program loads. However, if the local buffer pool is too large, this means wasted storage and may introduce paging overhead.

The local buffer pool is allocated as GETMAIN storage, that is, EXEC CICS GETMAIN SHARED with all CICS Transaction Server versions or a GETVIS request with CICS/VSE in z/VSE. Sufficient storage must be available in the partition or in the relevant CICS DSA.

A local buffer pool is optional, as Natural can also run with a global buffer pool, which can be shared with other Natural environments such as Natural in Batch Mode (z/OS and z/VSE) or Natural under TSO or Natural under IMS (under z/OS only).

Natural Swap Pool under CICS

The Natural swap pool offers the possibility to "swap" a compressed Natural session from the thread into a main storage area instead of doing expensive roll I/O operations.

The swap pool is allocated as GETMAIN storage, that is, EXEC CICS GETMAIN SHARED with all CICS Transaction Server versions or a GETVIS request with CICS/VSE in z/VSE. Sufficient storage must be available in the partition or in the relevant CICS DSA.

The options for the swap management are set in the Natural CICS source module NCISCPCB and by using the Natural profile parameter BPI.

The size, name and cache size of the swap pool are specified using profile parameter BPI or the corresponding macro NTBPI in the Natural parameter module, that is, the NTBPI or BPI settings in effect for the Natural session initializing the NCI environment are taken.

For further details on the swap pool, see Natural Swap Pool in the Natural Operations documentation and Using the Natural Swap Pool under CICS.

Note concerning z/OS Systems

The swap pool can only be used when running Natural under CICS locally in a single CICS region. However, even in such a scenario, you should consider using the Roll Server instead, because it runs asynchronously to the CICS region and because it can provide more roll buffers in its data space than the swap pool. When using the Roll Server, the swap pool and the Roll Facilities are not available under CICS.

Natural CICS Interface System Control Records in CICS Temporary Storage

The Natural CICS Interface remembers its permanent GETMAINed storages, that is, storages acquired via EXEC CICS GETMAIN SHARED or operating system GETMAIN requests for OSCOR/GETVIS storage, in NCI system control records in CICS main temporary storage.

These system control records are kept for two reasons:

  1. System recovery:

    As all NCI related storages are chained of the NCI system directory, the system control records can be used to re-construct storage chains in case of storage corruptions.

  2. Clean up old NCI system after CICS NEWCOPY of NCI system directory module:

    At NCI system environment initialization, NCI checks for existing system control records, and, if found, NCI frees the associated permanent storages prior to the installation of the new environment.

The CICS temporary storage queue names of these control records are prefixXCR, where prefix is the common prefix for Natural CICS components (see NCIPARM generation parameter PREFIX) and X is a hexadecimal value, namely

x'01' for the main system control record holding information about NCI system directory extension, shared threads (TYPE=SHR), and secondary SIR blocks (see NCMDIR generation parameter USERS).
x'02' for the parms system control record holding information about the NCI shared profile parameters retrieved via file input (see NCIPARM generation parameter PRMDEST).
x'03' for the pools system control record holding information about all local pools belonging toe the NCI environment including a potential swap pool.

Important:
As the NCI system control records describe a local NCI environment, these CICS MAIN temporary storage queues must be kept also in the CICS AOR. This is particularly true when running Natural in CICSPlex.

NCIDIREX - System Directory Module Name Exit Interface

The name of the Natural CICS Interface system directory module is prefix CB by default (see PREFIX parameter of NCMPRM macro) unless specified explicitly via the DIRNAME parameter of the NCIPRM macro.

The NCIDIREX exit interface is to set/modify the name of the Natural CICS Interface system directory module at run-time. This makes it possible to use the same NCI driver/ NCIPARM, but use different NCI environments (thread groups/thread sizes, etc) by accessing different system directory modules, depending for example on CICS system ID, transaction ID.

The first 5 characters of the directory module name are also used as part of CICS temporary storage queue names related to the relevant NCI environment. So when running more than one Natural CICS environment in a CICS region, the relevant system directory module names must be different in the first 5 characters.

The NCIDIREX interface exit is called using standard linkage conventions (Registers 13, 14, 15 and 1) but in addition with Registers 4 and 5 holding CICS EIB and EISTG addresses to enable the exit to call CICS services.

Source module XNCIDIRX contains a sample system directory module name exit.

NCIDTPEX - DTP Terminal I/O Exit Interface

Natural sessions may also be executed using distributed transaction processing (DTP), that is, using APPC or MRO conversations. Formally, such Natural sessions have a terminal associated (CICS TCTTE), however, this is a terminal out of a pool (see CICS SESSIONs / CONNECTIONs) and the "terminal" may change from Natural dialog step to dialog step, that is, such "terminals" cannot be used as key to save a session's context over a "screen I/O". Because of this nature, such Natural sessions are treated by default as asynchronous sessions (TTYPE=ASYN/ASYL), and Natural does not deal/communicate with these terminals, as they are no 3270 devices.

However, there is an exit interface NCIDTPEX available, which allows you to run the Natural session in a "conversational way":

  • when the exit is available, Natural sets up a terminal bound session (TTYPE=3270);

  • Natural terminal input and output operations (RECEIVE/SEND/CONVERSE) are not handled by Natural, but passed to the exit for further processing.

The source modules XNCIDTPX and XNCITIOX contain samples of DTP terminal exits.

Control Use of NCIDTPEX

You can set the FDTPX generation parameter of the NCMPRM macro to YES to cause a potential DTP exit to be invoked for all terminal types. This can be helpful, for example, if you want to analyze terminal output before a EXEC CICS SEND operation is executed, or if you want to suppress screen I/O operations.

NCITIDEX - Terminal ID Exit Interface

The 4-character CICS terminal ID which is unique per CICS region is used by the Natural CICS Interface as part of the session key (SIP server, roll server, CICS temporary storage queues). For compatibility with Natural, the Natural CICS Interface uses an 8-character field. This NCI terminal ID can be made unique over several CICS regions by appending the CICS system ID to the CICS terminal ID (see UNITID parameter of NCMPRM macro).

Alternatively, the NCITIDEX terminal ID exit interface can be used to set that NCI terminal ID. It should be noted that for CICS purposes (for example, temporary storage queue names, etc) just the first four characters of the NCI terminal ID are taken. Therefore these 4-character strings must be unique.

The NCITIDEX exit interface is particularly interesting for session managers under CICS in order to distinguish multiple Natural sessions running at the same physical terminal.

The terminal ID set by a NCITIDEX exit is used "externally" by the Natural CICS Interface and is the default for the Natural system variable *INIT-ID for "internal" Natural use. (The *INIT-ID system variable can subsequently be modified by the NCIUIDEX / NATUEX1 user ID exit interface.)

The NCITIDEX interface exit is called by using standard linkage conventions (Registers 13, 14, 15 and 1), but in addition by using the Registers 4 and 5 holding CICS EIB and EISTG addresses to enable the exit to call CICS services.

Source module XNCITIDX contains a sample terminal ID exit.

Restrictions

Certain Natural CICS Interface functions cannot work if the first four characters of the logical terminal ID do not match the physical terminal.

As a consequence,

  • you cannot send a message to a logical terminal by way of message switching,

  • you cannot use the SYSTP utility or NEP to flush a session at a logical terminal.

NCIUIDEX - User ID Exit Interface

Natural provides the NATUEX1 user exit interface to determine whether or not a user is authorized to use Natural and to set various Natural system variables.

Whenever a Natural user session is started, the NATUEX1 interface exit is called using standard linkage conventions (Registers 13, 14, 15 and 1).

If you want to issue EXEC CICS calls or obtain information from CICS control blocks in a CICS environment from within NATUEX1, the information supplied to NATUEX1 as of the standard linkage conventions is not sufficient.

Therefore, Natural CICS Interface delivers the load module NCIUEX1 that can be called in a CICS environment instead of the NATUEX1 interface exit. Module NCIUEX1 calls the interface exit NCIUIDEX with the information according to the standard linkage conventions (registers 13, 14, 15 and 1), and additionally passes CICS related addresses in registers 4 (EIB), 5 (EISTG), and 6 (TCTTE).

If your user ID interface exit requires addressability of the CICS environment, use module NCIUEX1 and the NCIUIDEX user ID interface exit rather than the standard NATUEX1 interface exit.

Source module XNCIUIDX contains a sample user ID exit.

Important:
With each installation of a new CICS release, the NCIUIDEX interface exit must be reassembled and linked.

NCIXIDEX - Transaction ID Exit Interface

By default, Natural always uses the transaction ID the pseudo-conversational session was started with. This transaction ID can be changed within Natural by using CALLNAT CMTRNSET (library SYSEXTP). The NCIXIDEX transaction ID exit interface can also be used to change the Natural pseudo-conversational transaction ID.

The NCIXIDEX interface exit is called by using standard linkage conventions (Registers 13, 14, 15 and 1), but in addition by using the Registers 4 and 5 holding CICS EIB and EISTG addresses to enable the exit to call CICS services. Source module XNCIXIDX contains a sample transation ID exit.

Note:
The transaction ID exit is only invoked prior to pseudo-conversational screen I/O under control of the Natural CICS Interface; that is, the exit is not invoked for conversational screen I/O (for example, SET CONTROL 'N') or when Natural is invoked from a front-end program via EXEC CICS LINK.

Natural CICS Interface Debugging Facilities

The following topics are covered:

Using the TPF Parameter

The dynamic parameter TPF=(TPF1,TPF2,TPF3,TPF4,TPF5,TPF6,TPF7,TPF8) can be set for driver-specific options by specifying "1" for the corresponding option.

Supported options are:

TPF1 Invoke Adabas linkage module via EXEC CICS LINK with Adabas parameter in TWA and CICS COMMAREA rather than via DCI.

Enables debugging of Adabas-related problems via CEDF.

TPF2

Dump the whole Natural swap pool.

With this parameter setting, the entire Natural swap pool is included in a CICS transaction dump.

TPF3

Dump the whole Natural buffer pool.

With this parameter setting, the entire Natural buffer pool is included in a CICS transaction dump.

Note:
Usually the Natural buffer pool is not required in a dump, as all objects from the buffer pool relevant to a session are dumped anyway; so this option may only be required in the case of a buffer pool problem.

TPF4 Dump the whole EDITOR buffer pool.

With this parameter setting, the EDITOR buffer pool is included in a CICS transaction dump.

TPF6 Handle terminal I/O errors by NCI.

With this parameter setting, NCI will not pass control back to Natural for terminal I/O errors, but will handle it by itself, which results in one of the error messages NT06 - NT13.

TPF7 Force abend in case of NCI system errors.

With this parameter setting, a program check is forced in case of NSxx, NIxx, NRxx or NUSnnnn error messages. This is particularly helpful when a debugging tool intercepting abends is active. Then the error can be analyzed directly online.

When specifying 0 (which can also be omitted), the corresponding option is not set, for example:

TPF=(0,0,0,1) which is equivalent to TPF=(,,,1)

Using the UPSI Parameter

The Natural CICS interface reacts on certain settings of the Natural profile parameter UPSI:

Natural Trace Extension

With profile parameter ETRACE=ON or ETRACE=(ON,NOGTF):

  • UPSI=XXXX10XX causes all CMTRACE trace records to be written to the Natural CICS Interface message destination (see NCIPARM MSGDEST parameter) in addition to the CICS trace (message number NCI0110).

  • UPSI=XXXX11XX causes all CMTRACE trace records to be written to the console (WTO) in addition to the CICS trace.

Using Asynchronous Natural Sessions

If the first 5 characters in the dynamic parameter string for starting Natural are ASYN,, the Natural CICS Interface will always setup an asynchronous Natural session, regardless of whether the session is terminal-bound or not.

This may be helpful for testing purposes, particularly with EDF or with other debugging tools installed.

Natural CICS Interface CICS TWA Usage

The Natural transactions are all defined with a TWA size of 128 bytes, although the Natural CICS Interface just uses the first 88 bytes of the CICS transaction work area (TWA) for Natural processing of the following functions:

  • on calling Adabas for the Adabas parameter list (up to 32 bytes), the Natural CICS Interface saves the TWA contents before calling Adabas and restores it after the Adabas call.

  • on calling external programs for the parameter list address pointers (up to 20 bytes, see the Natural CALL statement), the Natural CICS Interface saves the TWA contents before calling the external program and restores the TWA call portion after the external program call.

  • on invoking a back-end program for the termination message and potential termination data (80 bytes, see Back-End Program Calling Conventions in the Natural Operations documentation).

  • on returning control to a "LINK" front-end caller for the termination message and potential termination data at session end and the termination message area fully reset to low-value at Natural dialog step end respectively, that is, 80 bytes at session and dialog step end.

  • for passing LE information at CICS task start (up to 88 bytes, just at start of task).

User programs (front-end, back-end, called external programs) can also take advantage of the CICS TWA to communicate besides Natural, but they should not use the TWA portion used by Natural; for such cases, it is higly recommended to increase the TWA size of the Natural transactions and use TWA portions outside the first 128 bytes.