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
Support for User Exit Handling during Session Initialization
Natural Com-plete/SMARTS Interface Version 8.3 - Documentation Updates
Com-plete documentation set for details of the Com-plete product
Online Processing in the Natural System Architecture documentation
Installing the Natural Com-plete/SMARTS Interface on z/OS in the Installation for z/OS documentation.
Installing the Natural Com-plete/SMARTS Interface on z/VSE in the Installation for z/VSE documentation
SYSTP Utility in the Natural Utilities documentation
Natural under Com-plete/SMARTS User Abend Codes in the Natural Codes and Messages documentation
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.
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/SNAP/ABEND
,
the Natural session is dumped and correctly terminated with error message
NAT9974
.
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'
.
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.
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.
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 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
.
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.
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.
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
.
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 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.
Syntax:
CMPRINT =/pathname/filename[/],[mode]
|
Where
pathname
|
Specifies the location of the output file. If |
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.
|
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.
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 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:
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. |
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.
Note:
The documentation updates provided here only cover the changes
specific to Natural Com-plete/SMARTS Interface Version 8.3 and above.
For the changes in installation, see Installing Natural Com-plete/SMARTS Interface Version 8.3.5 on z/OS in the Natural Installation documentation.
Natural Com-plete/SMARTS Interface Version 8.3 supports the Natural zIIP Enabler under Com-plete if the prerequisites described in the Natural zIIP Enabler documentation are met.