Natural CICS Interface Functionality

#### Search Results

Search

# Natural CICS Interface Functionality

This document describes the functionality of Natural CICS Interface.

It covers the following topics:

- Natural CICS Interface

- Natural Environment-Dependent Nucleus for CICS

- System Control under CICS

- Natural Components in CICS Dynamic Storage

- Natural Storage Threads under CICS

- Natural Roll Facilities under CICS

- CICS Roll Facilities

- Natural Local Buffer Pool under CICS

- Natural CICS Interface System Control Records in CICS Temporary Storage

- NCIDIREX - System Directory Module Name Exit Interface

- NCIDTPEX - DTP Terminal I/O Exit Interface

- NCITIDEX - Terminal ID Exit Interface

- NCIUIDEX - User ID Exit Interface

- NCIXIDEX - Transaction ID Exit Interface

- Natural CICS Interface Debugging Facilities

- Natural CICS Interface CICS TWA Usage

## Natural CICS Interface

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 performed by Natural CICS Interface.

## Natural Environment-Dependent Nucleus for CICS

The Natural environment-dependent nucleus (described in the Natural Installation documentation) for CICS consists of the following components:

- The object module `NCINUC`.

  This module holds Natural CICS Interface system control logic and the logic required for calling operating-system and CICS services.

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

- The `NTCICSP` macro of the Natural parameter module (see CICSP - Environment Parameters for Natural CICS Interface the Parameter Reference documentation).

  This macro holds Natural CICS Interface parameters required for 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 object 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 independent of the CICS version.

### CICS Shutdown under Natural

The Natural environment-dependent nucleus is eligible to be placed into the CICS PLTSD for CICS quiesce stage 1 or 2 execution.

- When executed in quiesce stage 1, Natural CICS Interface force-terminates all active Natural sessions prior to performing the SYSTP snapshot function (described in SYSTP Utility in the Natural Utilities documentation).

- When executed in quiesce stage 2, Natural CICS Interface performs the SYSTP snapshot function.

Natural CICS Interface holds logic to be called (via a CICS LINK) by a node error program with the relevant CICS terminal entry address either in the CICS COMMAREA.

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

## Natural Components in CICS Dynamic 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:

- Natural Storage Threads under CICS

- Natural Local Buffer Pool under CICS

- Natural Roll Facilities

Scenario 1 applies when running Natural locally in a single CICS application region.

Note for z/OS:

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 (described in the Operations documentation).

#### 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=NAT,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

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

- 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 SYSTP utility described 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.

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.

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 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. 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, Natural under TSO or Natural under IMS.

## Natural CICS Interface System Control Records in CICS Temporary Storage

Natural CICS Interface remembers its permanent `GETMAIN`ed storages, that is, storages acquired via `EXEC CICS GETMAIN SHARED` 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 `NTCICSP` macro 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 the `PRMDEST` parameter of the `NTCICSP` macro).
`x'03'` | for the pools system control record holding information about all local pools belonging to the NCI environment.

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 Natural CICS Interface system directory module is prefix `CB` by default (see `PREFIX` parameter of the `NTCICSP` macro) unless specified explicitly via the `DIRNAME` parameter of the `NTCICSP` 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/ Natural parameter module, 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 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 `NTCICSP` macro to `ON` 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.

## NCITIDEX - Terminal ID Exit Interface

The 4-character CICS terminal ID which is unique per CICS region is used by Natural CICS Interface as part of the session key (SIP server, roll server, CICS temporary storage queues). For compatibility with Natural, 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 the `NTCICSP` 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 Natural CICS Interface and is the default for the Natural system variable `*INIT-ID` for 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).

In a CICS environment, the standard linkage conventions are not sufficient in order to issue CICS service calls and to obtain addressability of CICS control blocks.

Therefore, Natural CICS Interface delivers the load module `NCIUEX1` as a `NATUEX1` interface exit in a CICS environment. This module just sets up addressability in CICS and calls the `NCIUIDEX` interface exit by using standard linkage conventions (Registers 13, 14, 15 and 1), but in addition by passing CICS related addresses in other registers: R4 (`EIB`), R5 (`EISTG`), R6 (`TCTTE`).

Thus, if you want to issue requests requiring addressability of the CICS environment, the `NCIUIDEX` user ID exit interface should be used rather than the standard `NATUEX1` interface.

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

- Using Asynchronous Natural Sessions

### 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` | With this parameter setting, all `CMTRACE` trace records are written to the Natural CICS Interface message destination (see the `MSGDEST` parameter of the `NTCICSP` macro) in addition to the CICS trace (message number NCI0110). Note Parameter `ETRACE=ON` or `ETRACE=(ON,NOGTF)` is required to write trace records.
`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 Asynchronous Natural Sessions

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

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

### On this page

- Natural CICS Interface
- Natural Environment-Dependent Nucleus for CICS
- System Control under CICS
- Natural Components in CICS Dynamic Storage
- Natural Storage Threads under CICS
- Natural Roll Facilities under CICS
- CICS Roll Facilities
- Natural Local Buffer Pool under CICS
- Natural CICS Interface System Control Records in CICS Temporary Storage
- NCIDIREX - System Directory Module Name Exit Interface
- NCIDTPEX - DTP Terminal I/O Exit Interface
- NCITIDEX - Terminal ID Exit Interface
- NCIUIDEX - User ID Exit Interface
- NCIXIDEX - Transaction ID Exit Interface
- Natural CICS Interface Debugging Facilities
- Natural CICS Interface CICS TWA Usage