This document contains frequently asked questions concerning the Natural Development Server (NDV) under z/OS (Batch).
The following topics are covered:
Natural Development Server starts and terminates immediately
Trace output shows: Transport initialization failed, EDC8115I address already in use
How do I get information about which process occupies a port number?
NDV task abends with User Code 4093 and SYSOUT Message CEE5101C
Characters are not displayed correctly in the terminal emulation of Natural Studio
How do I find out which hexadecimal value must be specified for TABA1/TABA2?
The modifications of TABA1/TABA2 do not apply to sources listed in the remote debugger
Are there any Natural profile parameter settings required for NDV?
The NDV server consumes a lot of CPU time even if only a few clients are using it
I get a NAT0873 internal error at user authentication for Map Environment
At server initialization, the Natural Development Server
allocates central control blocks,
opens the datasets STGTRACE, STGSTDO,
STGSTDE, STGCONFG,
obtains the configuration file,
loads the Natural front-end,
initializes the first Natural session and
launches the TCP/IP listener task.
If one of these steps fails, the server will not be able to continue and will terminate immediately.
Analyze the trace output
(STGTRACE) or the error output
(STGSTE) to find out the problem.
STGTRACE, STGSTDO, STGSTDE are
synonyms for serveridE,
serveridO and
serveridT.
| STGSTE | Contains only error output. Each record consists of 2-4 lines,
depending on whether it is a Natural error, a system error or an NDV stub
error.
|
| STGTRACE | Contains NDV trace information and error information.
Each trace record contains DayOfMonth Time TaskId trace information text. The string PrintError in the trace information text prefixes errors. |
| STGSTO | Content of the configuration file allocated to STGCONFG. |
| SYSOUT | Messages from LE runtime system. |
The Natural front-end specified by the NDV configuration parameter
FRONTEND_NAME was
not found in the load library concatenation.
The TCP/IP port number specified by the NDV configuration parameter
PORT_NUMBER
is already in use by another process.
TSO command NETSTAT (PO 4712) displays
connections of Port 4712. The first column of the list refers to the task that
owns the port. Or enter the z/OS Unix System Services command
netstat -P4712.
Enter TSO command NETSTAT (PO
nnnn) to list connections for port
nnnn.
Output of the NETSTAT (PO 4712) command:
EZZ2350I MVS TCP/IP NETSTAT CS V2R8 TCPIP NAME: DAEFTCP2 06:45:19 EZZ2585I User Id Conn Local Socket Foreign Socket State EZZ2586I ------- ---- ------------ -------------- ----- EZZ2587I SAGNDV31 000031CC 157.189.160.55..4712 192.168.40.11..3152 Establsh EZZ2587I SAGNDV31 000005E9 0.0.0.0..4712 0.0.0.0..0 Listen EZZ2587I SAGNDV31 000031CD 157.189.160.55..4712 192.168.40.27..4250 Establsh EZZ2587I SAGNDV31 000031D5 157.189.160.55..4712 157.189.164.133..2906 Establsh EZZ2587I SAGNDV31 000031D8 157.189.160.55..4712 157.189.164.152..1099 Establsh
User Id |
The job that uses port 4712.
|
Conn |
Connection ID. |
Foreign Socket |
Connected clients. |
State |
Connection status. |
If State contains FinWait, you need not drop that connection, because connections of that status do not prevent a Natural Development Server from using that port.
To drop the connection, enter the MVS command VARY
TCPIP,DAEFTCP2,DROP,000005E9.
Where DAEFTCP2 must match your TCP/IP job name (TCPIP
NAME: DAEFTCP2) in the first line of the NETSTAT output)
and 000005E9 is the connection ID in the column
Conn.
When a Natural Development Server initializes, it starts a Natural
session using the session parameter(s) defined by the NDV configuration
parameter SESSION_PARAMETER.
The profile definition of the NDV configuration parameter
DEFAULT_PROFILE is
appended. If the initialization of the template session fails, the server
terminates immediately. The original error can be found below the message
Error at:Template runtime connect.
Typical error situations could be:
No Natural buffer pool defined.
Natural system file FNAT not accessible.
Natural profile parameter ITERM=ON (Session
Termination in Case of Initialization Error).
NDV initial user ID not defined.
The account of the Natural Development Server is not defined in z/OS Unix System Services. If you start the Natural Development Server as a started task, the member name of the started task must be defined under z/OS Unix System Services. If you start the Natural Development Server as a batch job, the user that submits the job must be defined under z/OS Unix System Services.
IBM Language Environment (LE) runtime options that must be specified to operate a Natural Development Server.
Note:
These recommendations apply to the region of the NDV server. They do
not apply to the CICS region if the NDV CICS adapter is used.
POSIX(ON) |
Enables the Natural Development Server to access the POSIX
functionality of z/OS.
If you start a Natural Development Server with
IBM supplies the default |
TRAP(ON,NOSPIE) |
Defines the abend handling of the IBM Language Environment.
IBM supplies the default |
TERMTHDACT(UADUMP) |
Defines the the level of information that is produced in case of
an abend. The option UADUMP generates a Language Environment
CEEDUMP and system dump of the user address space. The
CEEDUMP does not contain the storage areas relevant to Natural.
IBM supplies the default |
IBM Language Environment (LE) runtime options to monitor and tune Natural Development Servers.
Note:
These recommendations apply to the region of the NDV server. They do
not apply to the CICS region if the NDV CICS adapter is used.
RPTOPTS(ON) |
Prints LE runtime option settings to SYSOUT after
server termination.
|
HEAPPOOLS |
The HEAPPOOLS run-time option is used to control an
optional heap storage management algorithm, known as heap pools. Refer also to
Language Environment for z/OS & VM Programming
Reference.
The setting of this parameter depends on NDV functionality mostly used by NDV clients. A good value to start with is: HEAPP=(ON,40,3,80,7,224,7,528,3,1344,8,2048,8) |
ALL31(ON) |
Specify ALL31(ON) if your entire Natural
environment runs in 31-bit mode to prevent LE switching addressing
mode.
|
STACK(64K,16K,ANY,FREE) |
Specify the ANY option if your entire Natural
environment runs in 31-bit mode. This enables LE to allocate the storage for
the STACK segment above the 16 MB line. The STACK
segment above 16 MB increases the number of subtasks you can create within the
NDV region. The initial and extend size (64 KB and 16 KB in the example) should
be determined for your own environment by using the LE storage report generated
when you specify RPTSTG(ON).
|
HEAP(800K,64K,ANY,FREE,,) |
Initial heap storage (see STACK option).
|
ANYHEAP(1300K,200K,ANY,FREE) |
Library heap storage (see STACK option).
|
RPTSTG(ON) |
Generates, after server termination, a report of the storage the
server used. At the end of the report, it suggests cell sizes for the
HEAPPOOLS option. This option decreases performance of the server.
Use it only as an aid to find best settings for HEAPPOOLS
definition.
|
ENVAR(TZ=…) |
The ENVAR option enables you to set UNIX
environment variables. The only environment variable applicable for the Natural
Development Server is TZ (time zone).
Example: |
With the PARM parameter specified in the
EXEC card of the NDV startup job. The length of the options is
limited by the maximum length of the PARM parameter.
... //NDV EXEC PGM=NATRDEVS, // PARM='RPTOPTS(ON)/server-id' ...
Assemble an LE runtime option module CEEUOPT and link it
to the NDV load module.
//KSPLNDV JOB KSP,CLASS=K,MSGCLASS=X
//*
//* RELINK NDV SERVER WITH LE RUNTIME OPTIONS
//*
//******************************************************************
//* STEP1: ASSEMBLE LE RUNTIME OPTION MODULE
//*
//STEP1 EXEC PGM=ASMA90,PARM='DECK,NOOBJECT'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSPUNCH DD DSN=&&TEMPOBJ(CEEUOPT),DISP=(,PASS),UNIT=SYSDA,
// SPACE=(TRK,(1,1,1)),DCB=(BLKSIZE=3120,LRECL=80,DSORG=PO)
//SYSLIB DD DSN=CEE.SCEEMAC,DISP=SHR <<<<<<
// DD DSN=SYS1.MACLIB,DISP=SHR <<<<<<
//SYSIN DD *
CEEUOPT CSECT
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
CEEXOPT ENVAR=(TZ=CET-1DST), X
HEAPPOOLS=(ON,40,50,80,90,224,80,528,50,1344,90,2048, X
90), X
POSIX=(ON), X
RPTOPTS=(ON)
END
/*
//******************************************************************
//* STEP1: LINK RUNTIME OPTION MODULE
//*
//STEP2 EXEC PGM=IEWL,
// PARM='NCAL,RENT,LIST,XREF,LET,MAP,SIZE=(9999K,96K)'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK,(5,5))
//SYSLMOD DD DSN=&&CEEOBJ(CEEUOPT),DISP=(,PASS),UNIT=SYSDA,
// SPACE=(TRK,(1,1,1))
//SYSLIB DD DSN=&&TEMPOBJ,DISP=(OLD,PASS)
//SYSLIN DD *
INCLUDE SYSLIB(CEEUOPT)
ENTRY CEEUOPT
ORDER CEEUOPT
NAME CEEUOPT(R)
/*
//******************************************************************
//* STEP3: RELINK NDV SERVER WITH RUNTIME OPTION MODULE
//*
//STEP3 EXEC PGM=IEWL,
// PARM='RENT,XREF,LIST,LET,REUS,SIZE=(300K,64K),CASE=MIXED,
// AMODE=31,RMODE=ANY'
//SYSUT1 DD UNIT=(SYSDA),SPACE=(TRK,(10,4))
//SYSLMOD DD DISP=SHR,DSN=NATURAL.NDV.LOAD <<<<<<
//SYSPRINT DD SYSOUT=X
//NDVLOAD DD DISP=SHR,DSN=NATURAL.NDV.LOAD <<<<<<
//CEELOAD DD DISP=SHR,DSN=&&CEEOBJ
//SYSLIN DD *
REPLACE CEEUOPT
INCLUDE NDVLOAD(NATRDEVS)
INCLUDE CEELOAD(CEEUOPT)
NAME NATRDEVS(R)
/*
The lines marked with <<<<<< must be
adapted to your environment.
Each client must be defined in Natural Security (NSC) if the
Transition Period Logon flag in NSC is set to NO. Otherwise, your
attempt fails with a NAT0873
error.
You must define an NDV initial user ID (default ID is
STARGATE) unless you run with Natural profile parameter
AUTO=OFF (no automatic logon).
Each user must have either a default library or a private library. Otherwise, your attempt will fail with a NAT1699 error.
You must not specify a startup program that executes an I/O statement
or stacks a LOGON, LOGOFF
or RETURN command, because the program is executed
whenever you change the focus to that library within the tree view.
If you add a new user, you must specify a password for this user. Otherwise, his/her attempt will fail with a NAT0838 error.
The IBM Language Environment (LE) runtime option
TRAP must be set to TRAP(ON,NOSPIE).
Specify session parameter ETID=' '. If you are
using Natural Security, clear the ETID (Adabas User Identification) definition
for that user.
Stub return codes are raised by the NDV front-end stub, if it detects a logical processing error when dispatching the NDV request. The NDV trace output contains detailed information about the reason for the error.
The following stub return codes are possible:
| Code | Meaning, Reason, Action |
|---|---|
1 |
|
2 |
When Natural Studio executes a command, the Natural Development Server allocates an
entry in its session directory and creates a new subtask. If one of these
actions fails, the Stub Reason:
Action:
Increase region size or
The number of active tasks can be displayed using the
z/OS system command The value of |
3 |
This error occurs if a storage allocation for internal NDV control buffers fails due to a lack of virtual memory above 16 MB. Reason:
Virtual memory above 16 MB too small. Action:
Increase the virtual memory above 16 MB, decrease the number of physical storage threads, configure NDV to use the Natural roll server, or distribute the clients to several Natural Development Servers. |
4 |
Internal error. Natural Studio uses an invalid session identifier to process a request. Reason:
Action:
Locate the defective session ID in the server trace file and cancel it using the monitor task, or restart your Natural Studio session. |
5 |
In some situations, a Natural I/O is prohibited at the Natural Development Server. Reason:
Action:
Locate the I/O buffer in the server trace file to find out which I/O should be processed. Check for any startup program specified for the library you want to logon to. |
6 |
Not applicable. |
7 |
The Natural Development Server cannot finish a terminal I/O. Reason:
Action:
Increase the virtual memory above 16 MB. If the I/O reply buffer is invalid, contact Software AG support. |
8 |
Internal error, contact Software AG support. |
9 |
Natural Development Server cannot execute the Natural module
Reason:
Action:
Use the Natural utility INPL to load the NDV modules. |
10 |
If you execute a program on the Natural Development Server that
executes a In an online environment, the Natural Security logon screen is
displayed in this situation. Under NDV, the Natural session rejects all
requests except a |
The ASCII-to-EBCDIC translation for NDV uses the Natural translation
tables TABA1/TABA2. These tables are automatically or manually
adapted at the customer's site.
Automatic adaptation of the Natural translation tables
TABA1/TABA2 takes place if the following Natural profile
parameters are set:
CFICU=ON and
CP=value
where value can be any value
except OFF or AUTO.
For further information on possible settings, see the corresponding profile parameter descriptions in the Natural Parameter Reference documentation.
At session initialization (when you map to the NDV server) Natural
automatically adapts its conversion tables TABA1/TABA2 according
to the CP parameter definition and the code page used at
the client. To verify if the conversion tables have been adapted, set NDV
TRACE_LEVEL=31, connect to the NDV host via Natural Studio, and
review the NDV trace file.
Each Map Environment starts with:
11 07:58:02 00000003 Got new connection
some lines down you find:
11 07:58:02 00000005 Client codepage: windows-1252 11 07:58:02 00000005 Client operation = 18
and again some lines down you find:
11 07:58:03 00000005 TABA1/TABA2 adapted according CP definitions
which indicates that the table has been adapted.
The translate tables can be modified as follows:
Modify source member NTTABA1/NTTABA2 on the Natural
distribution library. Reassemble NATCONFG and relink the Natural
nucleus.
Specify the Natural session parameter
TABA1/TABA2.
Manual adaptation requires setting CP=OFF. It also requires
that TERMINAL_EMULATION=WEBIO be off. As a result, you cannot use
the statements REQUEST DOCUMENT and PARSE.
Automatic and manual adaptation are mutually exclusive. If the automatic
adaptation is effective, any TABA1/TABA2 definitions are
discarded. You can use either the automatic or the manual update but not a mix
of both.
Do not use Natural Studio session parameters as an approach to permanently implementing these changes. You run the risk that different clients may use different translations, and this could corrupt source code the clients share. It is better to maintain the translation centrally. You can do this in two different ways:
Maintain the Natural parameter module, or
Use the NDV configuration parameter
SESSION_PARAMETER.
This affects the SPoD users only.
In Natural Studio, see also Tools / Options / Workspace / Terminal emulation setting in Natural Studio. The default (Latin) may not be the correct choice. For instance, in the US, you probably want to select "United States".
A simple Natural program on the mainframe can reveal the EBCDIC representation of a character which is not converting correctly:
#A(A1) = '{'
WRITE #A(EM=H)
END
If none of the available code pages applies to your needs, it is
possible to adapt one of the N3270_USER 3270 translation tables in
the etc directory. Details are in the Natural for
Windows product documentation.
The web-site http://www.tachyonsoft.com/uc0000.htm is a good resource for finding valid EBCDIC and ASCII values for a given character (glyph) in various code pages.
Run the following program on your Natural for Windows locally.
#A(A1) = '{'
WRITE #A(EM=H)
END
Output is 7B.
Run the program on a mainframe (edit the program with the Natural
mainframe editor). Output is 75, assuming that you use a German
EBCDIC table. If you use a US EBCDIC table, the output will be
C0.
Start your Natural Development Server session with
TABA1=(75,7B) and
TABA2=(7B,75).
Specify the NDV configuration parameter
DBG_CODEPAGE=USER.
This topic is discussed in the Natural Operations for Mainframes documentation. Refer to Natural as a Server under z/OS, Print and Work File Handling with External Datasets in a Server Environment.
Ensure that your Natural Development Server is started with the
configuration parameter KEEP_TCB=YES.
If you run the Natural Development Server with impersonation enabled
(see NDV configuration parameter SECURITY_MODE),
ensure that you have linked the interface module DSNRLI (instead
of DSNALI) to the Natural nucleus.
The following Natural profile parameter values are required for NDV:
ETID=OFF is required to allow multiple Natural sessions
for each client.
DBCLOSE=ON is required to remove database resources
immediately after session termination rather than to keep them until they are
removed due to a timeout.
ITERM=OFF is required to continue with the Natural
Development Server initialization, even if session initialization errors
occur.
AUTO=ON/AUTO=OFF (Automatic Logon) has a different
behavior under Natural Single Point of Development. In an online Natural
environment, this parameter controls whether you are prompted for your user ID
and password or whether your user ID is treated to be a trusted user ID from
the TP environment. With Natural Single Point of Development, you must always
specify your user ID and password in the Map Environment dialog.
The Natural profile parameter MT (Maximum CPU
Time) is required to avoid endless loops within user programs. If you run a
Natural session under NDV with MT=0, there is no timeout
handler that interrupts a looping Natural program. The NDV server is still
responding to other clients but with an excessive CPU time consumption. This
applies only to NDV servers under z/OS Batch.
If you run your NDV server without a CPU time limit on session level, a
Natural program might run into an endless loop. Issue a server command
list sessions and examine whether any of the listed
sessions has the status code "IO" (under the column
header St. in the list output). The character I
means that the client owns an initialized session, and the O flags mean that
the client occupies a thread and is currently executing.
If a second list sessions command results in
an "IO" for the same client with an unaltered Last
Activity, it is probably a stuck or looping client. You can try to cancel the
session using a CANCEL SESSION server command. If
the cancelation fails, a restart of the NDV server is required.
If the list sessions function does not show a
stuck or looping client, cancel the NDV server by using the
DUMP option, and consult Software AG support.
You can define a CPU time limit for NDV servers under z/OS
Batch with the Natural profile parameter MT.
MT=3 defines a maximum CPU time limit of 3 seconds.
Please check the system messages in your NDV job output for the
error message ICH408I USER(… ) with BPX.SERVER
CL(FACILITY) and INSUFFICIENT ACCESS AUTHORITY in the NDV
Job output. This message indicates that the NDV server account
(USER(…) in the ICH408I message) has no read access to the
facility BPX.SERVER.
Please check the system messages in you NDV job output for the error
message ICH422I THE ENVIRONMENT CANNOT BECOME
UNCONTROLLED and CSV042I REQUESTED MODULE … NOT
ACCESSED. THE MODULE IS NOT PROGRAM CONTROLLED. This message
indicates that the load module … is not defined as "program
controlled". Please define the corresponding load library to the program
class "**".
The client is not granted to use z/OS Unix System Services. Please check if the client has an OE segment. And if you have defined the OMVSAPPL, each client must have read access to OMVSAPPL.
Probably the TCP/IP environment is in error. See the system error message after the error log entry and ask your system programmer(s) for assistance.