Natural under Com-plete/SMARTS

#### Search Results

Search

# Natural under Com-plete/SMARTS

This document describes the functionality of the Natural Com-plete/SMARTS Interface (product code NCF) and the operation and individual components of Natural in a Com-plete environment.

Note
SMARTS is an acronym for "Software AG Multi-Architecture Runtime System". It constitutes a runtime layer that allows POSIX-like applications to run on mainframe operating systems. Software AG products communicate with the operating system through the SMARTS layer.

The following topics are covered:

- Driver Parameters for the Natural Com-plete/SMARTS Interface

- Use of the Abend Exits

- Storage Usage

- Support for Back-end Programs

- Com-plete Support in Natural Batch Runs

- Asynchronous Natural Processing under Com-plete/SMARTS

- Invoking Natural from User Programs

- Storage Thread Key Handling

- Support for User Exit Handling during Session Initialization

- Use of the SMARTS Server Environment

- Support for Com-plete's Recoverable Session Handling

- Support for Natural for zIIP under Com-plete

#### Related Documents:

- Com-plete documentation set for details of the Com-plete product

- Online Processing in the Natural System Architecture documentation

- Installing Natural Com-plete/SMARTS Interface on z/OS in the Installation for z/OS documentation.

- SYSTP Utility in the Natural Utilities documentation

- Natural under Com-plete/SMARTS User Abend Codes in the Natural Codes and Messages documentation

## Driver Parameters for the Natural Com-plete/SMARTS Interface

For information on the driver parameters that are available for the Natural Com-plete/SMARTS Interface, refer to the description of profile parameter `COMP` or parameter macro `NTCOMP` in the Parameter Reference documentation. `COMP` (or `NTCOMP`) comprises several keyword subparameters whose use is explained in the following sections.

## Use of the Abend Exits

The `ABEXIT` exits can generally be deactivated by setting the keyword subparameter `SPIEA` to `OFF`.

The `ABEXIT` exit is called during Com-plete's EOJ handling for an abnormal program termination processing.

By default, an `0CX` abend is interpreted by the `ABEXIT` exit routine.

- When running with `DU``=ON`, the Natural session is dumped and terminated properly, with error message `NAT9974`.

- When running with `DU``=SNAP`, the Natural session is dumped as with `DU=ON`, but the session is not terminated.

  Note
  After the dump is taken, the Natural session continues as if running with `DU=OFF`.

- When running with `DU``=ABEND`, the Natural session is dumped without terminating the session.

- When running with `DU=FORCE`, the `ABEXIT` exit routine is disabled, an immediate dump during Com-plete is produced.

- If `LE370=ON` is specified in the `NTCOMP` macro, or is specified dynamically, and the abend occurs while an LE program has control, user-written or language-specific condition handlers are ignored. The abend is handled by the `ABEXIT` exit routine, the Natural error message `NAT0950` or `NAT9967` occurs.

If `DU=OFF`, Natural responds with error message `NAT0950`, `NAT0954`, `NAT0955` or `NAT0956`, and the entire abend PSW and the Registers 0 to 15 are contained in the IOCB at offset `x'290'`.

## Storage Usage

At session initialization, the amount of space defined with the keyword subparameter `NTHSIZE` is allocated as thread `GETMAIN` above or below the 16 MB line, depending on the keyword subparameter `THABOVE`, for usage by Natural.

The Natural profile parameter `WPSIZE` determines the sizes of below and above work pools. By default, the size of the below subpool is set to 32 KB.

Therefore, you must catalog the Natural Com-plete front part with the Com-plete utility `ULIB`, RG size = 36 KB or larger.

The remaining areas within the Com-plete thread parts below and/or above (Com-plete ULIB `RG=specification` and/or `THABOVESIZE=specification`) are used by Com-plete for the following:

- user subroutines,

- increasing of variable buffers inside the Natural thread,

- subproducts doing "physical" `GETMAIN` requests, this enforces the Natural work pool allocation.

For more details concerning the `ULIB RG` and `THABOVESIZE` parameters, refer to the Com-plete Utilities documentation.

## Support for Back-end Programs

Natural passes the following string to a back-end program:

- the Natural return code (fullword),

- the Natural termination message (A72),

- the length of the termination area (fullword),

- the termination data.

This string is mapped by the `NAMBCKP` macro.

The `XNCFBACK` source module is an example of a Natural back-end program in a Com-plete environment. It is written as reentrant code and can be loaded as `RESIDENTPAGE` program or once per user.

## Com-plete Support in Natural Batch Runs

If you use the Com-plete services in a Natural batch run, the batch user ID remains logged on at the end of the batch run.

To avoid this situation, include the module `COMPBTCH` from the Com-plete distribution library in the batch Natural nucleus. This resolves the entry point for module EOJ, which is called at the end of the Natural batch job for termination clean-up.

The module `NCFAM` is used to access Com-plete print/work files. It has to be included in the linking of the Natural nucleus, together with the module `COMPBTCH` from the Com-plete distribution library.

## Asynchronous Natural Processing under Com-plete/SMARTS

Asynchronous Natural processing is discussed in the section Asynchronous Processing in the Natural Operations documentation; however, some additional considerations apply when Natural is run under Com-plete.

Make sure that appropriate `SENDER` and `OUTDEST` destinations are specified for an asynchronous Natural session; otherwise, any output will lead to an abnormal termination.

In addition to Com-plete terminal IDs for `SENDER` and `OUTDEST`, the following keywords are supported by the Natural Com-plete/SMARTS interface:

Profile Parameter | Possible Values | Explanation
--- | --- | ---
`SENDER` | `DUMMY` | Output is ignored.
`TID` | Output destination.
`LUNAME`
`OUTDEST` | `DUMMY` | Output is ignored.
`CONSOLE` | Output destination.
`LUNAME`

By default, the 3270 data stream protocol is used for output of an asynchronous Natural session running under Com-plete.

An example to start an asynchronous Natural transaction under Com-plete can be found in the library `SYSEXTP`, program `ASYNCOMP`.

## Invoking Natural from User Programs

The Com-plete `FETCH` function is used to invoke Natural from a user front-end program under Com-plete; see the Com-plete Application Programmer's Manual for details.

## Storage Thread Key Handling

If you want to use protection mode between Com-plete and your application program, you must set the Natural profile parameter `SKEY` to `OFF` in the Natural parameter module. The application program runs in the corresponding thread key.

You can improve performance of the application program under Com-plete by activating the Storage-Protection Override facility on your machine.

Set the thread key to `9` in the Com-plete startup parameter `THREAD-GROUP` for your Natural sub-group.

The front-end driver sets the Natural application automatically to the privileged mode if the thread key is `9`, and uses the `SPKA` instruction for the key switch handling instead of the Com-plete function `MODIFY` with the function codes `THRD/TCS`.

Storage key switching is not performed for any Natural or editor buffer pool call.

## Support for User Exit Handling during Session Initialization

During session initialization, it is possible to pass user-specific session information about the activation of a user exit to Natural. The exit is called before Natural has been initialized, after the driver/IOCB initialization is complete.

The driver passes as a parameter the address of the IOCB in Register 1, whereas the exit is activated/deactivated by the Com-plete functions `COLOAD/CODEL`; see the Com-plete Application Programmer's Manual for details.

The `NCFUEXIT` source module is an example of a user exit. The user exit module can be defined with the keyword subparameter `EXIT`.

## Use of the SMARTS Server Environment

With the SMARTS Server Environment, it is possible to use the SMARTS portable file system as a container for input and output files as well as data sets on the native file system. It depends on the setting of the SMARTS parameters `CDI_DRIVER and MOUNT_FS` whether the environment variable refers to a the portable file system or to a native file system. For more information, see the SMARTS Installation and Operations Manual.

If environment variables are not defined, the normal data sets are accessed as described in the section Data Sets Used by Natural under z/OS Batch in the Natural Operations documentation.

The following topics are covered below:

- Input/Output

- Print File/Work File

### Input/Output

Input/output in the SMARTS Server Environment is performed by DLL `NCF92IO`.

`NCF92IO` must be loaded into the resident area. If `NCF92IO` is loaded into the application program thread, the Natural session is terminated with a `NAT9980` error message.

Supported environment variables:

- `CMPRINT` - Primary Report Output

- `CMSYNIN` - Primary Command Input

- `CMOBJIN` - Input for Natural `INPUT` Statements

These environment variables are described below.

#### CMPRINT - Primary Report Output

Syntax:

`CMPRINT`=/pathname/filename[/],[mode]

Where

`pathname` | Specifies the location of the output file. If `pathname` refers to a portable file system, the path will be created; if it refers to a native data set, it must be available.
`filename` | Specifies the name of the output file. An asterisk (*) as the file name means that the file name is generated from the actual user ID. If pathname refers to the native file system and filename is terminated with the slash character (/), the sequential data set pathname/filename will be accessed; if it is not terminated with "/", the member filename in data set pathname will be accessed.
`mode` | Specifies the file mode as documented in the C Library for the `fopen()` function. The default is `w` (write).

Example: Assume `/fs/` is mapped to the native file system and `/pfs/` is mapped to a portable file system.

`CMPRINT=/fs/natural/test/print` | Member print in data set `natural.test` is accessed.
`CMPRINT=/fs/natural/test/print/` | Sequential data set `natural.test.print` is accessed.
`CMPRINT=/pfs/natural/test/print` | Member print in `/natural/test` of the portable file system is accessed.

#### CMSYNIN - Primary Command Input

Syntax:

`CMSYNIN`=/pathname/filename[/]

Specifies the `pathname` and `filename` of the appropriate command input file.

If pathname refers to the native file system and filename is terminated with the "/" character, the sequential data set `pathname/filename` will be accessed; if it is not terminated with a slash (/), the member `filename` in data set `pathname` will be accessed.

#### CMOBJIN - Input for Natural INPUT Statements

Syntax:

`CMOBJIN`=/pathname/filename[/]

Specifies the `pathname` and `filename` of the appropriate data input file.

If `pathname` refers to the native file system and `filename` is terminated with the slash character (/), the sequential data set `pathname/filename` will be accessed; if it is not terminated with a slash (/), the member `filename` in data set `pathname` will be accessed.

### Print File/Work File

Print file and work file access in the SMARTS Server Environment is performed by DLL `NCF92APS`.

`NCF92APS` must be loaded into the resident area. If `NCF92APS` is loaded into the application program thread, the Natural session is terminated with a `NAT9980` error message.

Supported environment variables:

- `NAT_PRINT_ROOT` - Path to the printer files on a PFS or native file system.

- `NAT_WORK_ROOT` - Path to the work files on a PFS or native file system.

Syntax Example:

`NAT_WORK_ROOT`=/qualifier/path1/path2

Where

`qualifier` | Determines whether a SMARTS portable file system or a native, OS-managed file system will be accessed.
`path1/path2` | Is the path to the location of the file in the appropriate file sytem.

## Support for Com-plete's Recoverable Session Handling

To benefit from Com-plete’s recoverable session handling available under z/OS, you have to link the module `NCFROLLS` to your front-end module. `NCFROLLS` serves as an interface to the Natural Roll Server, which has to be started to support recoverable sessions.

Furthermore, the module `ATRRCSS` needs not to be linked to your front-end module, because the RRS interface module is part of the Com-plete routine `TLOPUSER`. When a conversational terminal I/O is to be performed, the Natural thread is written to the Natural roll file in compressed form to allow resuming the Natural session after a Com-plete restart. For non-conversational terminal I/Os and thread locked applications, the Natural thread is not written to the Natural roll file; as a consequence, such sessions cannot be recovered.

## Support for Natural for zIIP under Com-plete

Natural Com-plete/SMARTS Interface supports Natural for zIIP under Com-plete if the prerequisites described in the Natural for zIIP documentation are met.

### Support of zIIP-enabled Natural Roll Server

Natural Com-plete/SMARTS Interface supports the Natural Roll Server. To benefit from this feature, Natural for zIIP under Com-plete and the Natural Roll Server NATRSMvr must be used. In this case the Compression and Decompression of the Natural thread is executed on IBM’s System z Integrated Information Processors (zIIPs), thus reducing the CPU load of the GCPs.

To enable the use of the Natural Roll Server, just start the Natural Roll Server NATRSMvr.

Note
The notation vr represents the relevant product version (see also Version in the Glossary).

### On this page

- Driver Parameters for the Natural Com-plete/SMARTS Interface
- Use of the Abend Exits
- Storage Usage
- Support for Back-end Programs
- Com-plete Support in Natural Batch Runs
- Asynchronous Natural Processing under Com-plete/SMARTS
- Invoking Natural from User Programs
- Storage Thread Key Handling
- Support for User Exit Handling during Session Initialization
- Use of the SMARTS Server Environment
- Support for Com-plete's Recoverable Session Handling
- Support for Natural for zIIP under Com-plete