Version 4.2.6 for Mainframes
 —  TP Monitor Interfaces  —

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:

See also:


Parameters in Macro NFMPRM

To customize your Natural Com-plete environment, you can modify the following parameters in the macro NFMPRM:

EXIT | HCDTID | INITID | LC | LE370 | MSGHDR | NTHSIZE | SERVER | SPIEA | THABOVE | TTYxx | UCTRAN | U2PRINT |

EXIT - User Exit Module Name

This parameter defines a user exit module name which can be called during a session initialization before Natural is initialized. Possible values are:

Value: Explanation:
name Name of user exit.

No default value is provided.

HCDTID - Initialization of Hardcopy Destination

This parameter controls the initialization of the hardcopy destination.

Possible values are:

Value: Explanation:
YES The hardcopy destination is initialized with the terminal ID.
NO

The hardcopy destination corresponds to the logical terminal name.

This is the default value.

INITID - Content of *INIT-ID

This parameter controls the content of the system variable *INIT-ID.

Possible values are:

Value: Explanation:
TIBNAM *INIT-ID contains the logical unit name of the user's terminal.
TID

*INIT-ID contains the string lbnnnnnn , where l is the stack level on which the session is running, b is blank and nnnnnn is the TID number, right justified without leading zeroes.

This is the default value (Natural terminal ID).

CPATCH *INIT-ID contains the same string as with INITID=TID, except that b is the Com-plete patch character instead of a blank.

LC - Enable Lower-Case Mode

This parameter sets the terminal to lower-case mode.

Possible values are:

Value: Explanation:
YES

Lower-case mode.

This is the default value.

NO Upper-case mode.

LE 370 - LE/370 Environment Usage

This parameter specifies the usage of LE/370 as preinitialized environment (CEEPIPI interface) under Complete/SMARTS.

Possible values are:

Value: Explanation:
YES

All 3GL calls are handled in the preinitialized LE/370-enclave.

NO This is the default value.

MSGHDR - Activation of Message Header

This parameter activates or deactivates a message header for Natural error and termination messages using Com-plete's message switching facility for asynchronous Natural transactions.

Possible values are:

Value: Explanation:
YES

The message header is activated.

This is the default value.

NO The message header is deactivated.

NTHSIZE - Natural Thread Size

This parameter specifies the size of the storage area used for Natural's buffers, data areas and thread.

Possible values are:

Value: Explanation:
nnnn

Size in KB.

1024 This is the default value.

This storage area is allocated within the physical Com-plete thread. The remaining area (Com-plete region size RG for the Natural transaction minus NTHSIZE) is available for dynamically loading non-Natural subroutines, increasing of variable Natural thread buffers or for Natural work pools, for example.

SERVER - Name of Natural Server

This parameter defines the name of the Natural server which is initialized during Com-plete startup. It is used to maintain common storage and tables across Natural sessions, for example, local buffer pools. The server must be defined in the Com-plete startup.

Possible values are:

Value: Explanation:
name

Name of the Natural Server.

NCFNAT42 This is the default value.

It is possible to copy the supplied server module NCFNAT42 under a different name and to link and run different Com-plete interfaces with different servers, that is, with different sets of local buffer pools in the same Com-plete.

SPIEA - Activation of ABEXIT Exits

This parameter activates or deactivates the ABEXIT exits.

Possible values are:

Value: Explanation:
YES

Activates the ABEXIT exit.

This is the default value.

NO Deactivates the ABEXIT exit. Should be used for test purposes only.

THABOVE - Location of Natural Thread

This parameter determines the location of the Natural thread (see NTHSIZE parameter).

Possible values are:

Value: Explanation:
YES

The Natural thread is allocated in the Com-plete thread extension above the 16 MB line.

This is the default value (use Com-plete thread extension).

NO The Natural thread is allocated in the physical Com-plete thread below the 16 MB line

TTY xx - TTY Device Control Characters

This parameter sets teletypewriter (TTY) device control characters. The following hexadecimal values can be set:

Value: Explanation:
TTYCR=0D TTY carriage return
TTYLF=15 TTY line feed
TTYIC=00 TTY idle character
TTYNIC=00 TTY number of idle characters
TTYBS=16 TTY backspace
TTYAL=07 TTY alarm

UCTRAN - Lower-Case to Upper-Case Translation of Com-plete/SMARTS Error Messages

This parameter controls the lower-case to upper-case translation of the Com-plete/SMARTS error messages.

Possible values are:

Value: Explanation:
YES Upper-case translation enabled.
NO

Upper-case translation disabled.

This is the default value.

U2PRINT - Dynamic Printer Allocation

This parameter controls Com-plete's dynamic printer allocation feature for hardcopy requests.

Possible values are:

Value: Explanation:
YES Natural calls for hardcopy requests Com-plete's U2PRINT routine to specify a printer destination.
NO

Disables the dynamic hardcopy printer allocation. Natural uses the default value from Natural profile parameter HCDEST.

This is the default value.

Top of page

Use of the Abend Exits

The ABEXIT exits can generally be deactivated by setting SPIEA=NO in NCFPARM.

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.

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

Top of page

Storage Usage

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

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:

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

Top of page

Support of Back-end Programs

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

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.

Top of page

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.

Top of page

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:

Keyword: Explanation:
DUMMY Output is ignored.
CONSOLE Output is routed to the operator console/Com-plete log file.

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.

Top of page

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.

Top of page

Storage Thread Key Handling

If you want to use protection mode between Com-plete and your application program, you must set the profile parameter SKEY=OFF in the Natural parameter module NATPARM. The application program runs in the corresponding thread key. For any Natural or Editor buffer pool call, the front-end driver switches into the appropriate key and back to the thread key after the call.

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

Set the thread key = 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 using the Com-plete function MODIFY with function codes THRD/TCS.

Top of page

Support of 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 can be defined in the parameter module NCFPARM.

Top of page

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 datasets 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 datasets are accessed as described in the section Datasets Used by Natural under z/OS Batch in the Natural Operations documentation.

The following topics are covered below:

Input/Output

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

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

Supported environment variables:

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 dataset, 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 dataset pathname/filename will be accessed; if it is not terminated with "/", the member filename in dataset 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 dataset natural.test is accessed.
CMPRINT=/fs/natural/test/print/ Sequential dataset 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 dataset pathname/filename will be accessed; if it is not terminated with a slash (/), the member filename in dataset 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 dataset pathname/filename will be accessed; if it is not terminated with a slash (/), the member filename in dataset pathname will be accessed.

Print File/Work File

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

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

Supported environment variables:

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.

Top of page

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

Top of page