This document describes how to configure a Natural Development Server for z/OS (Com-plete).
The following topics are covered:
The following topics are covered below:
The Natural Development Server requires the following SMARTS SYSPARM
parameters:
You can set the SMARTS SYSPARM parameters in the file referred
by DD-name SYSPARM within your Com-plete startup JCL.
In the following example, the notation vrs or
vr stands for the relevant version, release,
system maintenance level numbers. The currently applicable product version must be
installed; refer to https://empower.softwareag.com/.
* ------------------ NDV Server to launch at startup ----------*
* STARTUPPGM='NATRDEVS NDVvr'
*
*
TASK-GROUP=(DEFAULT,6)
THREAD-GROUP=(DEFAULT,(DEFAULT,252,06,15,28,N))
*
THSIZEABOVE=1024
*
SERVER=(NCFNATvr,NCFNATvr)
*
CDI_DRIVER=('TCPIP,PAAOSOCK,ADDRSPCE=...')
*
RESIDENTPAGE=NATRDEVS
RESIDENTPAGE=NDVNCFvr
RESIDENTPAGE=NATNUCvr
RESIDENTPAGE=NATHTMON
RESIDENTPAGE=NATMONI
RESIDENTPAGE=NATDSSEC
ADDRSPCE should contain the name of the TCP/IP address
space.
NDVNCFvr is the name of the Natural
Complete Frontend.
NATNUCvr is the name of the Natural
Nucleus.
A configuration file is allocated to the name
<serverid>C (for example, ) or
STGCONFG alternatively.
The configuration file is a text file located on a dataset under z/OS.
The configuration file contains the server configuration parameters in the form of a
keyword=value syntax. In addition, it may
contain comments whose beginning is marked with a hash symbol (#).
See also the NDV Configuration File Example shown below.
The following NDV configuration parameters are available:
This optional configuration parameter specifies a time limit of central processing unit (CPU) time of a transaction. Transactions with a higher CPU time usage than the specified time limit are traced in the trace file. Trace level 30 is required to enable the trace. There are two types of traces: one that shows the CPU time of a single transaction and one that shows the CPU time of an entire session.
Note
A session consists of several transactions.
Example of traces of session DEBE5E3816036616:
04 14:21:34 00000052 Execute cpu time of session DEBE5E3816036616: 0.001295 s 04 14:25:51 00000052 Total cpu time of session DEBE5E3816036616: 0.063536 s
The value of CPU_TIME_TRACE applies also to the
CPU_TIME_HISTORY parameter if specified.
The parameter can be changed dynamically in the configuration menu of the HTML Monitor.
| Value | Explanation |
|---|---|
time-limit |
CPU time limit in seconds written as a decimal. Valid values are from
0,0 to 65535,0.
|
120,0 |
120,0 seconds. This is the default value.
|
Example:
CPU_TIME_TRACE=1,0
The setting in the example traces transactions and sessions with higher CPU time usage than 1,0 seconds.
This optional configuration parameter specifies a buffer that stores the specified number of transactions with the highest central processing unit (CPU) time values.
The entries are sorted by CPU time in descending order. Each stored entry contains the CPU time, the session ID, the day and time, the user ID and type of transaction executed.
The list can be displayed with the HTML Monitor Client in a browser window or with
Monitor Client NATMOPI. The number of stored entries can be filtered by setting a CPU
time limit with CPU_TIME_TRACE. The parameter can be changed
dynamically in the configuration menu of the HTML Monitor.
| Value | Explanation |
|---|---|
time_history_integer |
Stores the number of highest CPU time values provided. The values are
sorted by CPU time in descending order. Valid values are from 1 to 100, and
NO.
|
NO |
CPU time history is off. This is the default value. |
Example:
CPU_TIME_HISTORY=32
The setting in the example stores the 32 highest CPU time values sorted by cpu time.
This optional configuration parameter specifies the translation table to be used by the
remote debugger. By default, the remote debugger uses the code page
IBM-1047, whereas the Natural Development Server uses
TABA1/2.
| Value | Explanation |
|---|---|
USER |
Use the Natural translation tables TABA1/2.
|
No default value is provided.
Example:
DBG_CODEPAGE=USER
This optional configuration parameter defines a default profile.
| Value | Explanation |
|---|---|
string |
The following syntax applies:
profile-name,dbid,fnr,password,cipher-code Note: |
No default value is provided.
Example:
DEFAULT_PROFILE=RDEVS,10,930
The setting in the example defines that, if no parameters are defined in the Map Environment dialog box of Natural Studio, the session is
started with the Natural profile parameter
PROFILE=(RDEVS,10,930).
Related parameter: SESSION_PARAMETER.
This configuration parameter applies to z/OS.
This parameter allows you to enforce the use of communication method IPV4.
| Value | Explanation |
|---|---|
YES |
Enforce the use of communication method IPV4. |
NO |
First try communication method IPV6. If this fails give an error message and use communication method IPV4. This is the default value. |
This configuration parameter specifies the name of the Natural front-end to be used to start a Natural session. The front-end resides on a PDS member.
| Value | Explanation |
|---|---|
frontend-name |
Natural front-end to be used. Maximum length: 8 characters. |
No default value is provided.
Example:
FRONTEND_NAME=NATvrsSV
- where vrs stands for the version, release, system maintenance number.
If an abend occurs in the server processing outside the Natural processing the abend is not trapped by the Natural abend handling. For this reason the NDV server has its own abend recovery.
It is recommended that you leave this parameter on its default value in order to limit
the impact of an abend to a single user. If you set the value of this parameter to
NO, any abend in the server processing terminates the complete server
processing. That is, it affects all users running on that server.
| Value | Explanation |
|---|---|
YES |
Trap abends in the server processing, write a snap dump and abort the affected user. This is the default value. |
NO |
Suspend the server abend handling. |
Example:
HANDLE_ABEND=NO
This optional configuration parameter is necessary only if the server host supports multiple TCP/IP stacks.
| Value | Explanation |
|---|---|
host-name |
If HOST_NAME is specified, the server listens on the
particular stack specified by HOST_NAME, otherwise the
server listens on all stacks.
|
No default value is provided.
Example:
HOST_NAME=node1
or
HOST_NAME=157.189.160.55
This configuration parameter defines the password required for some monitor activities
(for example, Terminate Server) performed by the HTML Monitor Client.
| Value | Explanation |
|---|---|
| any character string | The password to be entered at the HTML Monitor Client for some monitor activities. |
No default value is provided.
Example:
HTPMON_ADMIN_PSW=GHAU129B
An NDV server can be configured to host an HTTP monitor task which serves the HTML Monitor Client running in a web browser. It is not required to run this monitor task on each server. A single task allows you to monitor all servers running at one node.
This configuration parameter defines the TCP/IP port number under which the server monitor task can be connected from a web browser.
| Value | Explanation |
|---|---|
1 - 65535 |
TCP/IP port number. |
No default value is provided.
Example:
HTPMON_PORT=3141
This configuration parameter defines the host name of the NDV server.
At server initialization, the Natural Development Server creates a temporary Natural session to obtain the properties of the installed Natural environment.
This configuration parameter specifies the user ID to be used for this Natural session.
| Value | Explanation |
|---|---|
userid
|
The specified value must not exceed 8 characters, otherwise it is truncated. |
STARGATE
|
This is the default value. |
Example:
INITIAL_USERID=NDVINITU
See also NDV Clients must be defined to Natural Security (in the Natural Development Server Installation documentation).
This parameter defines a minimum version of Natural Studio which is required to operate with the NDV server. This parameter assists in performing a preliminary validation if all clients use a minimum Natural Studio version. This can be useful to smoothly upgrade to a NDV version that does not support clients whose version is below the minimum Natural Studio version.
| Value | Explanation | |
|---|---|---|
vvmmpp |
The Studio Version (5-6 digits), where: | |
| vv | Version number (1 or 2 digits). | |
| mm | System maintenance level (2 digits). | |
| pp | Patch level (2 digits). | |
61100
|
This is the default value. | |
Example:
MINIMUM_STUDIO_VERSION=62100
This parameter allows you to perform a parameter check of Natural session parameters
after the server is up. The check is done by mapping to Natural. If a problem occurs, a
message is written to the NDV server trace, and the server is terminated immediately. In
such cases, session parameters (SESSION_PARAMETER) can be corrected. To
avoid termination of the server in case of invalid Natural parameters, the parameter
check can be switched off.
This parameter does not apply with SECURITY_MODE=IMPERSONATE,
IMPERSONATE_LOCAL, or IMPERSONATE_REMOTE.
| Value | Explanation |
|---|---|
YES |
Perform parameter check after the server is up. This is the default value. |
NO |
Avoid parameter check after the server is up. |
Example:
PARMCHECK=NO
This parameter allows you to define whether passwords specified in the Map Environment dialog are translated into upper case or not.
This parameter does only apply with SECURITY_MODE=IMPERSONATE,
IMPERSONATE_LOCAL or IMPERSONATE_REMOTE.
| Value | Explanation |
|---|---|
YES |
Passwords remain in mixed case. |
NO |
Passwords are translated into upper case. This is the default value. |
Example:
PASSWORD_MIXEDCASE=YES
This configuration parameter defines the TCP/IP port number under which the server can be connected.
| Value | Explanation |
|---|---|
1 - 65535 |
TCP/IP port number. |
No default value is provided.
Example:
PORT_NUMBER=3140
The Natural Development Server offers a security concept that also covers the operating system resources. The client credentials are validated at the operating-system-depending security system and the client request is executed under the client's account data.
Using the SECURITY_MODE parameter, you can specify at which rank
(Batch) you want to impersonate the activities of an
NDV client.
| Value | Explanation |
|---|---|
IMPERSONATE_LOCAL |
Impersonation is done within the Natural Development Server environment. If the session is dispatched in a remote TP environment, it is still executed anonymous. The client must be defined in the security system of the NDV server. It is not required to define the client in a remote TP environment. |
IMPERSONATE_REMOTE |
No impersonation is done within the Natural Development Server environment. If the session is dispatched in a remote TP environment, the client is impersonated. The client must be defined in the security system of the remote TP environment. |
IMPERSONATE |
Impersonation is done within the Natural Development Server environment and in a remote TP environment. The client must be defined in the security system of the NDV server and in the remote TP environment. |
Note
For a batch server SECURITY_MODE=IMPERSONATE and
SECURITY_MODE=IMPERSONATE_LOCAL are the same.
SECURITY_MODE requires Natural Security (NSC).
No default value is provided.
Example:
SECURITY_MODE=IMPERSONATE
This optional configuration parameter defines session parameters that precede the
parameter string either specified in the Map
Environment dialog of Natural Studio or defined by default by the
configuration parameter DEFAULT_PROFILE.
| Value | Explanation |
|---|---|
parameter-string |
This string may extend across several lines. A plus sign (+) at the end of a string line denotes that another line follows. |
No default value is provided.
Example 1:
SESSION_PARAMETER='NUCNAME=NATNUCvr' + 'PROFILE=(NDVPARM,18006,48),ADAMODE=0,' + 'BPI=(TYPE=NAT,SIZE=6044),BPI=(TYPE=EDIT,SIZE=2048)', + 'BPI=(TYPE=SORT,SIZE=1024)'
- where vr stands for the version and release
number.
Example 2:
SESSION_PARAMETER=FNAT=(10,930)
The setting in the second example defines that every session on this Natural
Development Server is started with the session parameter
FNAT=(10,930) appended to the user-specified parameters or the
definitions in the configuration parameter DEFAULT_PROFILE.
This optional configuration parameter can be used to allow session parameters and URL specifications in mixed case.
| Value | Explanation |
|---|---|
YES |
Session parameters remain in mixed case. |
NO |
Session parameters are translated into upper case. This is the default value. |
Cancel inactive sessions when the SESSION_TIMEOUT parameter is
met. Check for sessions inactive longer then n
minutes once a day at HH:MM (24 hours) or every
n minutes.
The server will not start if an invalid SESSION_TIMEOUT
parameter is given.
| Value | Explanation |
|---|---|
|
|
If format is or If format is a numeric value, check every
|
Examples:
SESSION_TIMEOUT=19:30,480
Every day at 19:30 cancel sessions more than 480 minutes inactive.
SESSION_TIMEOUT=360,480
Every 360 minutes cancel sessions more than 480 minutes inactive.
This configuration parameter defines the terminal emulation to be used for processing the Natural I/O. This definition applies to all clients using that server.
| Value | Explanation |
|---|---|
WEBIO |
Use the Web I/O Interface as terminal emulation. |
3270 |
Use the 3270 terminal emulation. This is the default value. |
Example:
TERMINAL_EMULATION=WEBIO
This optional configuration parameter enables you to restrict the trace by a logical filter in order to reduce the volume of the server trace output, for example:
TRACE_FILTER="Client=(KSP P*)"
Each request of the user ID KSP and each request of the user IDs starting
with a P are traced.
See Trace Filter in the section Operating the Natural Development Server.
| Value | Explanation |
|---|---|
trace-level |
See Trace Level in the section Operating the Natural Development Server. |
0 |
This is the default value. |
Example:
TRACE_LEVEL=0x00000011
or alternatively
TRACE_LEVEL=31+27
The setting in the example switches on Bits 31 and 27.
This configuration parameter is used to define whether the NDV server accepts source files in Unicode or not.
Sources transmitted in Unicode are not converted using the Natural ASCII-to-EBCDIC
translation tables TABA1/TABA2. All characters in the source file are
supported without maintaining the Natural translation tables.
A transmission in Unicode, however, increases the CPU consumption of the server significantly.
| Value | Explanation |
|---|---|
YES |
Transfer sources in Unicode. |
NO |
Transfer sources in ASCII. No code page support for Natural sources. This is the default value. |
Example:
UNICODE_SOURCE=YES
This configuration parameter is used to enable or disable the translation of all NDV error messages and trace outputs to uppercase. This feature is for customers who are using character sets with no lowercase characters defined.
| Value | Explanation |
|---|---|
YES |
Enable uppercase translation. |
NO |
Disable uppercase translation. This is the default value. |
# This is a comment SESSION_PARAMETER=profile=(stgqa,10,930) fuser=(10,32) DEFAULT_PROFILE=DEFPROF FRONTEND_NAME=NATNCF # and another comment PORT_NUMBER=4711
The Natural Development Server requires the following datasets:
STGCONFG |
Defines the server configuration file. |
STGTRACE |
The server trace output. |
STGSTDO |
The stdo dataset. |
STGSTDE |
The stde error output. |
Alternatively, you can qualify each dataset name by the server ID. This is necessary if you want to start different Natural Development Servers under a single SMARTS address space.
NDVS1C |
Defines the server configuration file for the server
NDVS1.
|
NDVS1T |
The server trace output for the server NDVS1.
|
NDVS1O |
The stdo dataset for the server NDVS1.
|
NDVS1E
|
The stde error output for the server NDVS1.
|
Natural Single Point of Development provides the following user exits.
The NDV-UX01 user exit is invoked before a Natural source object or a DDM
is edited. It can be used to reject editing certain sources.
The name of the source code of this exit in the SYSLIB Natural system
library is NDV-SX01.
To use this user exit, you must first enable it. For instructions, see Enabling NDV User Exits.
You can specify the following parameters for NDV-UX01:
| Parameter | Format | In/Out | Description |
|---|---|---|---|
| FUSER-DBID | N5 | In | Database ID of the system file that contains the object. |
| FUSER-FNR | N5 | In | File number of the system file that contains the object. |
| LIBRARY | A8 | In | Name of the library that contains the object. |
| OBJECT-NAME | A32 | In | Name of the Natural object or DDM that is edited. |
| USERID | A8 | In | ID of the current user. |
| OBJECT-TYPE | A1 | In | Natural type of the object. |
| ALLOW-DISALLOW-TRANSFER | L | Out |
Possible values:
|
| DISALLOW-DESCRIPTION | A65 | Out | Error message issued by NDV if the edit request is rejected. |
The NDV-UX02 user exit is invoked before a Natural object or DDM, or when
a user error message is deleted, copied, or moved (including the context menu functions
Cut, Copy, and Paste). NDV-UX02 enables the rejection of further processing
of this object, similarly to the MAINEX01 user exit of SYSMAIN
in Natural for z/OS.
The name of the source code of this exit in the SYSLIB Natural system
library is NDV-SX02.
To use this user exit, you must first enable it. For instructions, see Enabling NDV User Exits.
You can specify the following parameters for NDV-UX02:
| Parameter | Format | In/Out | Description |
|---|---|---|---|
| P-OBJECT-TYPE | A1 | In | Type of object:
|
| P-FUNCTION | A1 | In | Function currently performed:
M - MOVE within server C - COPY within server D - DELETE G - Get-Copy from server H - Get-Move from server P - Put to server S - SAVE source W - STOW source T - CAT source K - CHECK source |
| P-SOURCE-LIBRARY | A8 | In | Source library name for P-FUNCTION = 'M', 'C', 'D', 'G',
'H'. |
| P-SOURCE-OBJECT-NAME | A32 | In | Source object name for P-FUNCTION = 'M', 'C', 'D', 'G',
'H'. |
| P-SOURCE-DBID | N5 | In | Source DBID for P-FUNCTION = 'M', 'C', 'D', 'G', 'H'. |
| P-SOURCE-FNR | N5 | In | Source file number for P-FUNCTION = 'M', 'C', 'D', 'G',
'H'. |
| P-TARGET-LIBRARY | A8 | In | Target library name for P-FUNCTION = 'M', 'C', 'P', 'S', 'W',
'T'. |
| P-TARGET-OBJECT-NAME | A32 | In | Target object name for P-FUNCTION = 'M', 'C', 'P', 'S', 'W',
'T'. |
| P-TARGET-DBID | N5 | In | Target DBID for P-FUNCTION = 'M', 'C', 'P', 'S', 'W',
'T'. |
| P-TARGET-FNR | N5 | In | Target file number for P-FUNCTION = 'M', 'C', 'P', 'S', 'W',
'T'. |
| P-NATURAL-OBJECT-TYPE | A1 | In | Natural object type for P-OBJECT-TYPE = 'P'. |
| P-NATURAL-OBJECT-KIND | A1 | In | Natural object kind for P-OBJECT-TYPE = 'P'.
Possible values:
|
| P-ERROR-MESSAGE-LANGUAGE | N2 | In | Language code for error message for P-OBJECT-TYPE =
'E'. |
| P-REPLACE-OPTION | A1 | In | Replaces option for P-FUNCTION = 'M', 'C', 'P'.
Possible values:
|
| P-RESPONSE-CODE | I4 | Out | Response code for the caller. If set to any non-zero value, the requested function is rejected. |
| P-MESSAGE-TEXT | A200 | Out | Message text returned to the caller when P-RESPONSE-CODE
≠ 0.
|
| P-SUPPRESS-MSG-TO-CLIENT | A1 | Out | Suppresses the sending of the message text P-MESSAGE-TEXT to
the client. If the message is suppressed, the user is not informed that the
function was rejected by this user exit.
Possible values:
Other values - Sends the message |
| FP-VERSION | A2 | In | Interface version for P-FUTURE-PARAMETERS.
|
| FP-V1-SOURCE-FDIC-DBID | I4 | In | For FP-VERSION ≥ 01, DBID of the FDIC to be
used for the source environment.
|
| FP-V1-SOURCE-FDIC-FNR | I4 | In | For FP-VERSION ≥ 01, FNR of the FDIC to be
used for the source environment.
|
| FP-V1-SOURCE-FSEC-DBID | I4 | In | For FP-VERSION ≥ 01, DBID of the FSEC to be
used for the source environment.
|
| FP-V1-SOURCE-FSEC-FNR | I4 | In | For FP-VERSION ≥ 01, FNR of the FSEC to be
used for the source environment.
|
| FP-V1-TARGET-FDIC-DBID | I4 | In | For FP-VERSION ≥ 01, DBID of the FDIC to be
used for the target environment.
|
| FP-V1-TARGET-FDIC-FNR | I4 | In | For FP-VERSION ≥ 01, FNR of the FDIC to be
used for the target environment.
|
| FP-V1-TARGET-FSEC-DBID | I4 | In | For FP-VERSION ≥ 01, DBID of the FSEC to be
used for the target environment.
|
| FP-V1-TARGET-FSEC-FNR | I4 | In | For FP-VERSION ≥ 01, FNR of the FSEC to be
used for the target environment.
|
| FP-V2-SRC-RESOURCE-NAME | A250 | In | For FP-VERSION ≥ 02, the name of the
resource in the source environment for P-NATURAL-OBJECT-TYPE = 9
(resource).
|
| FP-V2-TGT-RESOURCE-NAME | A250 | In | For FP-VERSION ≥ 02, the name of the
resource in the target environment for P-NATURAL-OBJECT-TYPE = 9
(resource).
|
The NDV-UX03 user exit provides flags for special settings within the
Natural Development Server. It specifies whether resources are displayed and in which
format data areas are written on the server.
The resources are not displayed by default for performance reasons, neither in the
NaturalONE server view nor in the Natural Studio. If resources should be listed, set the
DISPLAY-RESOURCES parameter to Y.
For higher performance, consider implementing the hyperdescriptor H1 as described in NaturalONE > NaturalONE in a Nutshell > Performance Aspects > Improve Mainframe Access.
For historical reasons, Natural supports three data area formats. Originally, the old
internal format was used. Later, the new internal format was introduced. With Natural
9.1.2 (all platforms), the DEFINE DATA format was introduced. When saving a
data area with NDV on the server, the DEFINE DATA format for NaturalONE or
the new internal format for Natural Studio is used by default. When saving a data area
directly on the server, the new internal format is used. You can override the default
values for NaturalONE and Natural Studio with the NDV-UX03 user exit.
The name of the source code of this exit in the SYSLIB Natural system
library is NDV-SX03.
To use this user exit, you must first enable it. For instructions, see Enabling NDV User Exits.
You can specify the following parameters for NDV-UX03:
| Parameter | Format | In/Out | Description |
|---|---|---|---|
| DISPLAY-RESOURCES | A1 | Out |
Indicates whether Natural objects of type Resource ( Possible values:
Other values - does not display resources (default). |
| SAVE-ORIGINAL-SOURCE | A1 | Out |
Applies only for a NaturalONE client and
Retains the original DEFINE DATA format of the client. Possible values:
Other values - stores the data area source in the new internal format only. The original DEFINE DATA format will be lost when the data area is reloaded to NaturalONE. |
| DATA-AREA-NO-INDENTION | A1 | Out |
Applies only for a NaturalONE client and
When a data area source coming from NaturalONE is stored in the new internal format, the indention (leading blanks) of each line is written by default to the end of the internal source line. During download, the indention will be restored. Suppresses the writing of the indention. Possible values:
Other values - writes the indention (default). |
| DATA-AREA-CONVERT-TO-NEW-FORMAT | A1 | Out |
Applies only for a NaturalONE client,
Saves the data area source in the new internal format when the data area source cannot be converted into the old internal format. Possible values:
Other values - doesn't save the data area and NaturalONE shows an error message. |
| DATA-AREA-DEFINE-DATA-FORMAT | A1 | Out | Applies only for a NaturalONE client.
Specifies whether data areas are saved in the DEFINE DATA format or in the new internal format on the server. Possible values:
Other values - saves data areas in the DEFINE DATA format on the server (default). |
The NDV user exits are delivered in the SYSLIB Natural system library.
The sources of these user exit routines are named
NDV-SXnn, where
nn denotes the number of the user exit
routine.
To make an NDV user exit routine available:
Copy the source code of the user exit
NDV-SXnn from the SYSLIB
Natural system library into a user library and save it under the name
NDV-UXnn.
Renaming the user exit guarantees that the object is not affected if the user exit source is overwritten by an installation update.
Adapt the values of the parameters as required and stow the user exit.
Copy the cataloged object of NDV-UXnn to
the SYSLIB Natural system library.
Apart from the NDV user exits that are coded in Natural, the following user exit exists.
This user exit is applicable only when the parameter SECURITY_MODE is set to IMPERSONATE_LOCAL or
IMPERSONATE.
This user exit allows you to adapt the user ID used for the RACF login. It is useful if
the RACF user IDs and the user IDs used in Natural differ according to a standardized
rule. For example, each RACF user ID is the corresponding Natural user ID preceded by
two dollar signs ($$).
If the exit (the loadmodule NSECUX01) is found in the NDV load library
concatenation, it is called using standard linkage conventions (direct branch using BASR
instructions) before the user is validated against RACF.
You can specify the following parameters for this exit:
| Parameter | Format | In/Out | Description |
|---|---|---|---|
| sUid | CL64 | In/Out | User ID to be modified for RACF login. |
The exit is called using standard linkage conventions.
Sample user exit implemented in C:
#include <string.h>
#include <stdio.h>
# pragma linkage (NSECUX01, FETCHABLE)
void NSECUX01(char sUid[64])
{
char sUidTemp[64];
printf("Uex got usid:%s\n", sUid);
strcpy(sUidTemp, sUid);
sprintf(sUid, "$$%s", sUidTemp);
printf("Uex ret usid:%s\n", sUid);
return;
}
The exit above extends each user ID by two preceding dollar signs ($$)
when it is used for RACF login.
Communication between NaturalONE and NDV servers can be encrypted by using an SSL or (preferably) a TLS protocol.
On the server side, encryption is enabled by using the AT-TLS component of the z/OS Communications Server. AT-TLS allows you to encrypt and secure the TCP/IP communication between client and server without any changes on the server side. If you want to use encrypted communication mode, you must define a set of rules concerning the NDV server job for the policy agent (PAGENT) configuration file of AT-TLS. Encrypted communication requires a certificate associated with encryption on the server side. This encryption certificate must either be included in a RACF keyring or stored in a key database located on the z/OS USS POSIX file system.
Use the ZOSMF utility for maintaining the PAGENT.
For detailed information on AT-TLS, refer to the z/OS Communications Server documentation from IBM.
SSL/TLS support for the Natural development server is based on the z/OS Communication Server component AT-TLS (Application Transparent-Transport Layer Security).
AT-TLS provides SSL/TLS encryption as a configurable service for sockets applications. It is realized as an additional layer on top of the TCP/IP protocol stack, which exploits the SSL/TLS functionality in nearly or even fully transparent mode to sockets applications. AT-TLS offers three modes of operation. See z/OS Communications Server, IP Programmer’s Guide and Reference. Chapter: Application Transparent Transport Layer Security (AT-TLS).
These modes are:
The sockets application runs without modification in transparent mode, unaware of performing encrypted communication via AT-TLS. Thus legacy applications can run in secured mode without source code modification.
The application is aware of running in secured mode and is able to query TLS status information.
The sockets application is aware of AT-TLS and controls the use of AT-TLS encryption services itself. This means, the application is able to switch between secured and non secured communication.
Natural development server uses the Basic mode for its SSL/TLS implementation. That is, a server configured as SSL/TLS server rejects requests from non-secured clients.
Certificates, which are to be used with AT-TLS, can be maintained in two ways under z/OS. They are stored either in RACF key rings or in key databases, which are located in the z/OS Linux file system. Which of these proceedings actually applies is defined in the AT-TLS Policy Agent Configuration file for the z/OS TCP/IP stack, which is used by the Natural HTTPS client.
IBM delivers a set of commonly used CA root certificates with each z/OS system delivery. If key rings are going to be used to hold server certificates, those root certificates must be manually imported into the key rings by the system administrator. If IBM delivers newer replacements for expired root certificates, all affected key rings have to be updated accordingly.
Unlike key rings, key databases contain the current set of root certificates automatically after they have been newly created. However, the need for maintaining always the latest set of root certificates applies to the key database alternative as well.
In RACF, digital certificates are stored in so-called key rings. The RACF command
RACDCERT is used to create and maintain key rings and
certificates, which are contained in those key rings.
See z/OS Security Server RACF Security Administrator’s Guide, Chapter: RACF and digital certificates - RACF and key rings, and z/OS Security Server RACF, Command Language Reference, Chapter: RACF command syntax - RACDCERT.
Alternatively to RACF, certificates can be kept in key databases, which reside in the
z/OS Linux services file system. For the creation and maintenance of key databases,
the GSKKYMAN utility has to be used.
See z/OS Cryptographic Services PKI Services Guide and Reference, Chapter: Appendix B. Using a gskkyman key database for your certificate store.
Proceed as follows:
In the TCP/IP configuration file, set the option TTLS in the
TCPCONFIG statement.
Configure and start the AT-TLS Policy Agent. This agent is called by TCP/IP on each new TCP connection to check if the connection is SSL/TLS.
Create the Policy Agent file containing the AT-TLS rules. The Policy Agent file contains the rules to stipulate which connection is SSL/TLS.
See also z/OS Communications Server: IP Configuration Guide, Chapter: Application Transparent Transport Layer Security data protection.
The Sample Policy Agent file defines the server with the job name starting with
NDVDEV and listening at port 4843 to use SSL/TLS.
The sample expects the certificate database on the HFS file /u/admin/CERT.kdb.
TTLSRule ConnRule01~1
{
LocalAddrSetRef addr1
RemoteAddrSetRef addr1
LocalPortRangeRef portR1
RemotePortRangeRef portR2
Jobname NDVDEV*
Direction Inbound
Priority 255
TTLSGroupActionRef gAct1~NDV_Server
TTLSEnvironmentActionRef eAct1~NDV_Server
TTLSConnectionActionRef cAct1~NDV_Server
}
TTLSGroupAction gAct1~NDV_Server
{
TTLSEnabled On
}
TTLSEnvironmentAction eAct1~NDV_Server
{
HandshakeRole Server
EnvironmentUserInstance 0
TTLSKeyringParmsRef keyR1
}
TTLSConnectionAction cAct1~NDV_Server
{
HandshakeRole Server
TTLSCipherParmsRef cipher1~AT-TLS__Silver
TTLSConnectionAdvancedParmsRef cAdv1~NDV_Server
}
TTLSConnectionAdvancedParms cAdv1~NDV_Server
{
CertificateLabel NDV_TEST_CERT
}
TTLSKeyringParms keyR1
{
Keyring /u/admin/CERT.kdb
KeyringStashFile /u/admin/CERT.sth
}
TTLSCipherParms cipher1~AT-TLS__Silver
{
V3CipherSuites TLS_RSA_WITH_DES_CBC_SHA
V3CipherSuites TLS_RSA_WITH_3DES_EDE_CBC_SHA
V3CipherSuites TLS_RSA_WITH_AES_128_CBC_SHA
}
IpAddrSet addr1
{
Prefix 0.0.0.0/0
}
PortRange portR1
{
Port 4843
}
PortRange portR2
{
Port 1024-65535
}
Check Policy-Agent job output JESMSGLG for:
EZZ8771I PAGENT CONFIG POLICY PROCESSING COMPLETE FOR <your TCP/IP address space>: TTLS
This message indicates a successful initialization.
Check Policy-Agent job output JESMSGLG for:
EZZ8438I PAGENT POLICY DEFINITIONS CONTAIN ERRORS FOR <your TCP/IP address space>: TTLS
This message indicates errors in the configuration file. Check the syslog.log file for further information.
Does the configuration rule cover the server?
Try to connect the server and check syslog.log for:
EZD1281I TTLS Map CONNID: 00018BED LOCAL: 10.20.91.61..4843 REMOTE: 10.20.160.47..4889 JOBNAME: NDVDEVvr USERID: NDVSRV TYPE: InBound STATUS: Enabled RULE: ConnRule01~1 ACTIONS: gAct1 eAct1~NDV_Server cAct1~NDV_Server
The above entry indicates that the connection to Port 4843 is SSL/TLS enabled.
See z/OS Communications Server, IP Diagnosis Guide, Chapter: Diagnosing Application Transparent Transport Layer Security (AT-TLS)
See z/OS Communications Server, IP Configuration Reference, Chapter: Syslog deamon, and z/OS Communications Server, IP Configuration Guide, Chapter: Base TCP/IP system – TCP/IP Customization - Configuring the syslog daemon (syslogd).
Find return code RC and corresponding GSK_ function name in P-agent
trace.
Get description of the return code from z/OS Cryptographic Services, System Security Sockets Layer Programming, Chapter: : messages and codes – SSL function return codes.
Sample trace with trace=255:
EZD1281I TTLS Map CONNID: 00002909 LOCAL: 10.20.91.61..1751 REMOTE: 10.20.91.117..443 JOBNAME: KSP USERID: KSP TYPE: OutBound STATUS: A EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000000 CONNID: 00002909 RC: 0 Connection Init EZD1282I TTLS Start GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 Initial Handshake ACTIONS: gAct1 eAct1 AllUsersAsClient HS-Client EZD1284I TTLS Flow GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 0 Call GSK_SECURE_SOCKET_OPEN - 7EE4F718 EZD1284I TTLS Flow GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 0 Set GSK_SESSION_TYPE - CLIENT EZD1284I TTLS Flow GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 0 Set GSK_V3_CIPHER_SPECS - 090A2F EZD1284I TTLS Flow GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 0 Set GSK_FD - 00002909 EZD1284I TTLS Flow GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 0 Set GSK_USER_DATA - 7EEE9B50 EZD1284I TTLS Flow GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 435 Call GSK_SECURE_SOCKET_INIT - 7EE4F718 EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 435 Initial Handshake 00000000 7EEE8118 EZD1286I TTLS Error GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 JOBNAME: KSP USERID: KSP RULE: ConnRule01 RC: 435 Initial Handshake EZD1283I TTLS Event GRPID: 00000003 ENVID: 00000002 CONNID: 00002909 RC: 0 Connection Close 00000000 7EEE8118
Under z/OS, SSL/TLS certificates can be produced with the Linux System Services
utility GSKKYMAN. The following steps have to be executed for the
production of a new certificate, which is to be used for the SSL/TLS secured
communication between Natural Web I/O Interface client and server:
Start a shell session out of TSO or connect via telnet to the z/OS Linux shell.
Start GSKKYMAN.
Create a new – or open an existing key database.
Create a self-signed certificate, for example, of type "User or server certificate with 2048-bit RSA key".
Export the certificate to a (HFS) file. Choose Base64 ASN.1 DER as export format.
This generated file can now be copied to the Natural development server client(s) using FTP with ASCII transfer format. On the client side, the received file should be stored with the file name suffix .CER. The certificate can now be used by the Natural development server client.
For more information on how to import the certificate, see the documentation of NaturalONE, Natural for Ajax > Configuration and Administration Configuring SSL.
If certificates are kept in a RACF key ring, the generated certificate has to be
imported into the appropriate key ring using the RADCERT
command.
Certificates, which are produced on a different platform, for example, on a Windows PC, can be imported into a RACF key ring or into a key database as well.
Detailed information about the use of the GSKKYMAN utility can be found
in the IBM Communications server documentation, e.g. in the following manuals:
z/OS Communications Server, IP Configuration Guide
or
z/OS Cryptographic Services, System Secure Sockets Layer Programming
For the generation of certificates under Windows, a free downloadable utility named
Ikeyman is available on several websites. Ikeyman is an IBM product as well and maps
the functionality of GSKKYMAN to the Windows platform.
The TCP/IP port sharing component of the z/OS TCP/IP
Communications subsystem allows multiple listeners to listen on the same combination of
port and IP address. To enable this in the TCP/IP stack, you must add the
SHAREPORT or SHAREPORTWLM keyword to the PORT profile
statement that reserves the TCP port for the server instances. You can find detailed
information in section PORT Statement, chapter TCP/IP profile
(PROFILE.TCPIP) and Configuration Statements of the IBM manual z/OS
Communications Server: IP Configuration Reference found on their official
website.
You can start the NDV server as explained in section Starting the Natural Development
Server. You must define the used port with the PORT_NUMBER parameter in the
configuration file of the NDV server. If port sharing is enabled, the started task can be
executed multiple times to start multiple instances of an NDV server that listens on the
same port.
Note
All servers must be started with the same configuration
file.
Since the server ID is used to identify a server in the server directory, you must set a unique server ID. The server ID is passed as a parameter to the NDV server. You must set the parameters in the PARM card of the started task. For example:
//NDVSRV EXEC PGM=NATRDEVS,REGION=0M,TIME=20,
// PARM=('POSIX(ON) STACK(64K,32K,ANY,FREE) TRAP(ON,NOSPIE) ',
// 'TERMTHDACT(UADUMP),ENVAR(TZ=CET+0DST) /SERVERID')
If multiple NDV servers are listening on a port and one server fails, the workload can still be done by the remaining servers. From a user point of view, the service offered by the NDV server remains available.
If a request for a new connection arrives, it is in the responsibility of the z/OS operating system to pass the request to one of the listening servers. The connections are distributed across the available servers using a weighted round-robin distribution based on the Servers' accept Efficiency Fractions (SEFs). Once a session is started, it is executed on this server, until it is finished.
You can identify a session in the trace file with the following piece of code:
Start of Session: 26 10:16:45 0000000E Worker task active, SID=DED9D087D842B606, client: USER End of session: 26 10:21:53 0000000E Worker task disconnect, client: USER 26 10:21:53 0000000E Free LTCB...and finish
Each server has its own STGTRACE, STGSTDO, and
STDSTGE, which are part of the job log of each server. It is possible to
redirect the output of the files to a sequential dataset, but you must ensure that each
server is assigned its own sequential dataset. Otherwise, the output of the files cannot
be assigned to a particular server.