This document contains special considerations that refer to Natural in batch mode under the operating system z/VSE.
The following topics are covered:
For considerations that refer to Natural in batch mode generally, see also:
The Natural z/VSE batch mode interface NATVSE
consists of a
number of service routines interfacing with the z/VSE operating system.
NATVSE
is supplied as a source module and can be customized
to meet your requirements; see also Installing Natural under
z/VSE, where you can set the generation parameters. You
can either assemble and link it to the Natural nucleus or you can run it
separately, connecting with a shared nucleus.
NATVSE
must run below the 16 MB line. Multiple sessions can
be started in parallel within one batch region; see
Subtasking
Session Support for Batch Mode Environments.
The NTVSE
macro contains several generation parameters (to
be set in the NATVSE
copy book) to change the NATVSE
internal defaults.
These parameters are:
NAME
|
BUFSIZE
|
CANCEL
|
DSECTS
|
FILEID
|
FILMNGR
|
FILSCAN
|
FLUSH
|
IDUMP
|
LE370
|
LIBRID
|
MAXABND
|
RCSIZE
|
RJEUSER
|
SEGMENT
|
THDSIZE
|
USERID
|
WAITIME
NAME
specifies the name of the relocatable
module to be created by the given assembly. Possible values:
NAME=xxxxxx
|
xxxxxx = name of the
relocatable module to be created.
Maximum length: 8 characters. |
NAME=NATVSE |
This is the default value. |
BUFSIZE
specifies the size of the Natural I/O
buffer which is used for all input and output operations.
BUFSIZE=nnnn |
nnnn specifies the
size of the Natural I/O buffer in KB.
Minimum value: |
BUFSIZE=8192 |
This is the default value. |
CANCEL
specifies how the Natural z/VSE interface
is to proceed at session termination. Possible values:
CANCEL=YES |
The job is cancelled by This is the default value. |
CANCEL=NO |
NATVSE always terminates with RETURN
or EOJ macros with a set return code (the same effect is achieved
when you set the Session Abend Flag UPSI
XXXXX1XX ).
|
Note:CANCEL=YES
is the default for compatibility reasons.
However, it is recommended to specify CANCEL=NO
, particularly to
take advantage of VSE conditional job control facilities.
DSECTS
specifies whether operating system DSECTS
are to be listed. Possible values:
DSECTS=YES |
Listing of operating system DSECTS takes place. |
DSECTS=NO |
Operating system DSECTS are not to be listed. This is the default value. |
FILEID
specifies a string of up to 8 characters
which is checked against the start of a DLBL
or TLBL
file ID. If it matches, this label information is ignored. Possible values:
FILEID=xxxxxxxx
|
xxxxxxxx = any character string which must be enclosed in apostrophes if it contains special characters. |
FILEID='IGNORE' |
This is the default value. |
This is particularly helpful when DLBL
or
TLBL
statements for CMWKFnn*
and/or CMPRTnn*
are supplied in the (partition) standard labels, but should not be used.
If, for example, a // DLBL CMPRT01,'...'
statement is
found, it is not possible to direct a WRITE(1)
output to a printer
SPOOL
. To do so, use the JCS statement // DLBL
CMPRT01,'IGNORE'
and a suitable printer assignment of the relevant
SYSnnn
.
FILMNGR
specifies how a print or a work file is
to be managed in Natural. Possible values:
FILMNGR=YES |
The fact that there is label information for a print or a work
file and the fact that This is the default value. |
FILMNGR=NO |
The logical unit number of the Natural print or work file must be assigned to the appropriate device type. |
FILSCAN
specifies whether print or work files
are to be scanned. Possible values:
FILSCAN=YES |
The Natural z/VSE interface scans the z/VSE label area for all Natural print and work files for which no specific file access method has been defined via Natural session parameters, as this may cause overhead. This is the default value. |
FILSCAN=NO |
Access to all Natural print and work files must be specified explicitly via session parameters in order to be "available". This concentrates all file access efforts on the defined files. |
FLUSH
specifies how the Natural z/VSE interface
is to proceed at session termination with the CMSYNIN/CMOBJIN
card
input files. Possible values:
FLUSH=YES
|
At session termination, the Natural z/VSE interface will read the
This is the default. |
FLUSH=NO |
No extra SYSIN/SYSRDR/SYSIPT card input (null)
file is required, if the batch mode Natural session is completely driven with
STACK data; the SYSIN/SYSRDR/SYSIPT card input file
is then left as is, thus potentially resulting in INVALID
STATEMENT operator prompts or job cancellation due to INVALID
STATEMENT , when the Natural CMSYNIN /CMOBJIN had not been
retrieved completely.
|
IDUMP
specifies the kind of dump the Natural
z/VSE interface is to produce.
Possible values:
IDUMP=YES |
The Natural z/VSE interface will create dumps using the
This is the default value. |
IDUMP=NO |
The Natural z/VSE interface will create dumps using the
SDUMP macro.
|
LE370
specifies whether Natural is to run in the IBM
Language Environment. Possible values:
LE370=YES |
The IBM Language Environment runtime environment is initialized on the initialization of the Natural session. You must specify "YES" if IBM Language Environment subroutine programs (dynamic or static) are to be called via Natural. |
LE370=NO |
The IBM Language Environment runtime environment is not initialized on the initialization of the Natural session. This is the default value. |
LIBRID
specifies a string of up to 8 characters
which is checked against the start of a DLBL file ID. If it matches, the
remaining portion of that file ID is scanned for information specifying a
library member in a z/VSE library or library chain. Possible values:
LIBRID=xxxxxxxx
|
xxxxxxxx = any
character string of 8 characters length; must be enclosed in quotes if it
contains any special characters.
|
LIBRID='LIBR:' |
This is the default value. |
MAXABND
specifies the maximum number of abends
which NATVSE
tolerates (that is, NATVSE
intercepts
the abend and invokes the Natural abend handler) until it assumes an
unrecoverable abend situation or abend loop and terminates the Natural session
abnormally by itself. Possible values:
MAXABND=nnnn |
nnnn = maximum number
of abends.
|
MAXABND=16
|
This is the default value. |
RCSIZE
specifies the default roll cache size
for a server environment for the case that the roll cache size is not
passed with the Initialize Environment request. Possible values:
RCSIZE=nnnnnnnnn |
nnnnnnnnn = default
roll cache size in KB.
|
RCSIZE=0 |
This is the default value. |
RJEUSER
defines which user ID is to be set for submission
via XPCC
macro requests. Possible values:
|
RJEUSER=YES is the default value. The system
variable *INIT-USER is used as the mandatory
submission user ID.
|
RJEUSER=(YES,NAT) |
The system variable *USER is used
as the mandatory submission user ID.
|
RJEUSER=NO |
The user ID R000 is used.
|
SEGMENT
specifies how the Natural z/VSE
interface is to behave at CLOSE
of an output SPOOL
file (print or punch). Possible values:
SEGMENT=YES |
A file close is accompanied by a POWER segment
close unless CLOSE=FIN is in effect for that file.
|
SEGMENT=NO |
The SPOOL file is closed without closing the
POWER segment.
This is the default value. |
THDSIZE
specifies the default thread size for a
server Natural environment for the case, that the thread size is not
passed with the Initialize Environment request. Possible values:
THDSIZE=nnnnnnnnn |
nnnnnnnnn = default
thread size in KB.
|
THDSIZE=0 |
This is the default value. |
This parameter specifies the contents of the system variable
*INIT-USER
. Possible values:
USERID=YES |
The following logic applies: if a z/VSE user ID is specified in
JCL (// ID USER=xxx ), this user ID is
taken; otherwise, if a POWER from-user is specified in JECL
(* $$ JOB FROM=xxx ), this user id is
taken; otherwise, the VSE job name is taken for the Natural user ID.
|
USERID=NO
|
The VSE job name is taken for the Natural user ID.
This is the default value. |
WAITIME
specifies a time limit in milliseconds. It
applies to the CMROLL
call in a Natural server environment: if the
time interval passed in the CMROLL
call is not less than the
WAITIME
interval, the session is rolled-out and the its
thread is released, while the session is waiting. Possible values:
WAITIME=nnnnn |
nnnnn = time limit in
milliseconds.
|
WAITIME=1000 |
This is the default value. |
The following datasets are required if certain functions are used during a Natural z/VSE batch mode session:
Dataset | Explanation |
---|---|
CMEDIT
|
Software AG Editor Work File |
CMHCOPY
|
Hardcopy Print Output |
CMOBJIN
|
Input for Natural INPUT Statements
|
CMPLOG
|
Dynamic Profile Parameter Report Output |
CMPRINT
|
Primary Report Output |
CMPRMIN
|
Dynamic Profile Parameter Input |
CMPRTnn
|
Additional Reports 01-31 |
CMSYNIN
|
Primary Command Input |
CMTRACE
|
External Trace Output |
CMWKFnn
|
Work Files 01-32 |
These datasets are described below.
The Software AG Editor work file VSAM dataset is required if a local or global Software AG editor buffer pool is to be used.
If not defined in the JCL, the name of the Editor work file specified
by subparameter DSNAME
of
profile parameter EDBP
or parameter
macro NTEDBP
is used by Natural to do the dynamic allocation for the Editor work file.
Alternatively, profile parameter EDPSIZE
can be
used to run with an auxiliary editor buffer pool, which does not require an
editor work file. For more information about the installation of the Software
AG editor, see Installing the
Software AG Editor.
The default name of the hardcopy print output dataset is
CMHCOPY
. It can be changed by one of the following:
the subparameter DEST
of
profile parameter PRINT
for Print File
0,
the profile parameter HCDEST
, which is an
equivalent of PRINT=((0),DEST=...),
the setting of the system variable
*HARDCOPY
during the session,
the terminal command %H
during the
session.
The subparameters of the profile parameter
PRINT
for
Print File 0 can be used to change the default values for the hardcopy dataset.
The default dataset name CMHCOPY
implies
CLOSE
=FIN
for the hardcopy print dataset, that is, after the dataset has been opened for
output, any subsequent change of the hardcopy print output dataset name will
not be honored. If a different name is defined at open time, the hardcopy
dataset will be closed according to subparameter
CLOSE
of
profile parameter PRINT
for Print File
0.
By default, the CMHCOPY
file is assigned to
SYSLST
and is processed via the macro DTFPR
.
If appropriate label information is supplied for the file name
CMHCOPY
, the print output may also be routed to disk or tape by
using the z/VSE macro DTFSD
or DTFMT
with:
RECFORM=UNDEF,BLKSIZE=133
When routed to a z/VSE library, the record format is fix, the record
length is 80 and the default member type is PRINT
.
CMOBJIN
is used for data intended to be read by Natural
INPUT
statements. This
type of data can alternatively be placed in the
CMSYNIN
input
stream immediately following the relevant source program or the relevant
RUN
or EXEC
command.
When the setting for the profile parameter
OBJIN
is
N
, Natural reads input from CMSYNIN
. When
OBJIN
is set to Y
, Natural reads input from
CMOBJIN
. When OBJIN
is set to R
, Natural
determines which option has been selected for a particular session depending
upon the presence or absence of a CMOBJIN
label information.
By default, the CMOBJIN
input file is assigned to
SYSIPT
. By using the profile parameter
READER
, it
can be assigned to SYSRDR
.
Alternatively, a sequential disk or labeled tape file may be used
rather than a real/logical (POWER
) reader file. In that case, you
must supply appropriate label information for file name
CMOBJIN
.
Supported file formats are:
DTFSD/DTFMT: RECFORM=FIXUNB,RECSIZE=81 DTFSD/DTFMT: RECFORM=FIXUNB/FIXBLK,RECSIZE=80 LIBR: RECFORM=FIX,RECSIZE=80 , default member type CARD
You must supply appropriate label information; for assignment, you have
to use file names CMSYNIN
and /or
CMOBJIN
.
If profile parameter PLOG
=ON
is set and
dataset CMPLOG
is available, the evaluated dynamic profile
parameters are written to this dataset during session initialization. If
dataset CMPLOG
is not available, the evaluated dynamic profile
parameters are written to CMPRINT
.
By default, the CMPLOG
file is assigned to
SYSLST
and is processed with the macro DTFPR
.
If appropriate label information is supplied for the file name
CMPLOG
, the print output may also be routed to disk or tape by
using the z/VSE macros DTFSD
or DTFMT
with:
RECFORM=UNDEF,BLKSIZE=133
When routed to a z/VSE library, the record format is fix, the record
length is 80 and the default member type is PRINT
.
CMPRINT
is used for the primary output report resulting
from DISPLAY
,
PRINT
and
WRITE
statements in a
Natural program.
By default, the CMPRINT
file is assigned to
SYSLST
and is processed via the macro DTFPR
.
If appropriate label information is supplied for the file name
CMPRINT
, the print output may also be routed to disk or tape by
using the z/VSE macro DTFSD
or DTFMT
with:
RECFORM=UNDEF,BLKSIZE=133
When routed to a z/VSE library, the record format is fix, the record
length is 80 and the default file type is PRINT
.
CMPRMIN
can be used as a dynamic parameter dataset to
overcome the length restriction for the character string in the job control
PARM
keyword of the EXEC
statement.
If available, this file is read during session initialization to get the dynamic profile parameters.
All input records from CMPRMIN
are concatenated into one
parameter string. Only the first 72 positions of each CMPRMIN
record are significant. Trailing blanks at the end of each record are
truncated; if the last non-blank character is a comma, all trailing blanks are
truncated, else just one blank is left for delimiter; no commas are
inserted.
Additional dynamic parameters can be supplied using the job control
PARM
keyword: if the PARM
keyword contains a dynamic
parameter string, these profile parameters are concatenated at the end of the
parameter string which was built trom the input of CMPRMIN
, i.e.
these can be used to overwrite the parameters from CMPRMIN
. If the
PARM
keyword is specified as SYSRDR
or
SYSIPT
, Natural retrieves additional profile parameters from
SYSRDR
or SYSIPT
respectively as a logical extension
of the CMPRMIN
dataset, i.e. the same rules apply.
CMPRMIN
is a sequential disk or a labelled tape dataset.
Supported file formats are:
DTFSD/DTFMT: RECFORM=FIXUNB,RECSIZE=81 DTFSD/DTFMT: RECFORM=FIXUNB/FIXBLK,RECSIZE=80 LIBR: RECFORM=FIX,RECSIZE=80 , default member type CARD
CMPRTnn
is used for each
additional report referenced by any Natural program compiled or executed during
the session. "nn" must be a two-digit decimal number
in the range 01-31 corresponding to the report number used in a
DISPLAY
,
PRINT
or
WRITE
statement.
Instead of CMPRTnn
, another
file name may be used by setting the DEST
subparameter
of profile parameter PRINT
to an
appropriate value, for example:
PRINT=((nn),...,DEST=PRNTFIL)
When supplying label information with file name
CMPRTnn
, the print output can be
written to a disk or tape. Natural treats this print file like an unblocked
fixed-length work file. When "printing" to disk or tape, the same
logic as for work files applies (see below).
When mapped to a z/VSE library member, the record format is fix, the
record length is 80 and the default file type for these files is
PRINT
.
CMSYNIN
is used for the primary input file that contains
Natural commands, Natural source programs, and (optionally) data to be read by
INPUT
statements during
the execution of Natural programs.
By default, the CMSYININ
input file is assigned to
SYSRDR
. By using the profile parameter
READER
, it
may be assigned to SYSIPT
.
Alternatively, a sequential disk or labeled tape file may be used
rather than a real/logical (POWER
) reader file. In that case, you
must supply appropriate label information for file name
CMSYNIN
.
Supported file formats are:
DTFSD/DTFMT: RECFORM=FIXUNB,RECSIZE=81 DTFSD/DTFMT: RECFORM=FIXUNB/FIXBLK,RECSIZE=80 LIBR: RECFORM=FIX,RECSIZE=80 , default member type CARD
If profile parameter ETRACE
is set to
"ON" or the equivalent terminal command
%TRE+
was issued, any Natural trace output during the session is written to the
CMTRACE
dataset. To define the Natural components that are to be
traced, the profile parameter TRACE
is
required.
By default, the CMTRACE
file is assigned to
SYSLST
and is processed via the macro DTFPR
.
If appropriate label information is supplied for the file name
CMTRACE
, the print output may also be routed to disk or tape by
using the z/VSE macro DTFSD
or DTFMT
with:
RECFORM=UNDEF,BLKSIZE=133
When routed to a z/VSE library, the record format is fix, the record
length is 80 and the default member type is PRINT
.
CMWKFnn
is used for each
Natural work file referenced by any Natural program compiled or executed during
the session. nn
must be a two-digit
decimal number in the range 01 - 32 corresponding to the number used in a
READ WORK FILE
or
WRITE WORK FILE
statement.
Instead of CMWKFnn
, another
file name may be used by setting the
DEST
subparameter of profile parameter WORK
to an
appropriate value.
If the Natural z/VSE generation parameter
FILMNGR
=YES
is
specified and there is label information for a work file or if OFF
or NOTM
is specified for the
LABEL
subparameter of profile parameter WORK
for an
unlabeled work file, Natural knows the file is available. Otherwise, the
Natural work-file logical-unit number must be assigned to the correct device
type.
When mapped to a z/VSE library member, the record format is fix, the
record length is 80 and the default member type for these files is
WORK
.
If a Natural printer or work file is assigned IGN
, all I/O
requests for these files are treated as dummy and no Natural error is
generated. However, if there is no assignment or the printer/work file is
assigned UA
, any attempt to use this file is treated as an
error.
NATVSE
supports access to z/VSE library members for input
and/or output for all Natural datasets. When a z/VSE library member is
accessed, only "card image format" is supported, that is, a record
length of 80 bytes.
The access to a z/VSE library member is triggered via the file ID of an
associated DLBL
statement. A special string (see
LIBRID
in
NTVSE Generation Parameters) at the start of the file ID
field in the DLBL statement signals that the Natural dataset actually is a
z/VSE library member which is specified in the remainder of the file ID
field.
The following specifications are possible:
C=chain |
Specifies a library concatenation chain defined in JCL. |
S=library.sublib |
Specifies a specific sublibrary in a specific library. |
M=mbrname.mbrtype |
Specifies a library member name and its type. |
The following rules apply:
All these possible specifications are optional.
Each parameter may be specified only once.
The parameters are separated by one ore more commas or blanks.
Chain (C=
) and sublibrary (S=
)
specifications are optional, but mutually exclusive when specified.
If neither a chain (C=
) nor a sublibrary
(S=
) is specified, a default of C=SOURCE
is
taken.
If a library member (M=
) is not specified, a default of
M=filename.type
is taken, where
filename
is the file
name of the DLBL
statement and
type
indicates the
Natural file class, namely WORK
for Natural work files,
PRINT
for Natural print files and CARD
for the
Natural input files CMPRMIN
,
CMSYNIN
and
CMOBJIN
(the
relevant default member type for every Natural dataset is mentioned
below).
An asterisk specified for any sub-parameter of the library member
specification signals the default to be taken; hence a specification of
M=*.*
has the same effect as omitting this parameter.
Omitting the member type subparameter also means the default to be taken.
Example:
// LIBDEF PROC,SEARCH=(...) // LIBDEF SOURCE,SEARCH=(...) // DLBL CMWKF01,'LIBR:M=FILE1.TEST S=SAGLIB.USRLIB' // DLBL CMWKF02,'LIBR: S=SAGLIB.USRLIB' -> M=CMWKF02.WORK // DLBL CMWKF03,'LIBR: M=TEST C=PROC' -> M=TEST.WORK // DLBL CMPRT04,'LIBR:M=*.LISTING,S=SAGLIB.USRLIB' -> M=CMPRT04.LISTING // DLBL CMPRT05,'LIBR:' -> M=CMPRT05.PRINT,C=SOURCE // DLBL CMPRT06,'LIBR:M=WORK' -> M=WORK.PRINT,C=SOURCE // DLBL CMWKF07,'LIBR: M=*.DATA' -> M=CMWKF07.DATA,C=SOURCE // DLBL CMPRMIN,'LIBR:M=*.*' -> M=CMPRMIN.CARD,C=SOURCE
Notes:
DLBL
statement is just 44
characters in length, which is not enough to specify all (sub)parameters in
their full length. Therefore it is recommended to take advantage of the
defaults. Regarding the member name, there is also the option to specify the
file name via the DEST
subparameter of the Natural profile parameter
PRINT
or
WORK
.
Natural under z/VSE offers functionality to define work files
dynamically, that is, these files need not be predefined in JCL. This means
that Natural under z/VSE adds labels into the partition's temporary labels area
for work files defined using a DEFINE
WORK FILE
statement.
In this respect Natural under z/VSE does not modify existing label information. All file labels dynamically added by a Natural session are deleted at session termination.
The following topics are covered below:
A disk file manager is required, as it is not feasable to have fix file extent information within Natural application programs, particularly when these programs are executed in parallel in the same partition or in several partitions. This is not a restriction, as at least VSAM/SAM is available under z/VSE.
For dynamic allocation support by Natural under z/VSE, the following
keyword subparameters of Natural profile parameter
WORK
have
been made sensitive:
The following keyword parameters are available for dynamic work files under VSE:
Keyword Parameter | Purpose |
---|---|
CAT=catalog |
Triggers the usage for VSAM/SAM for the dynamic work file,
where catalog is the 1 to 7 characters VSAM catalog file name. As this
parameter is mandatory, if you want to use VSAM/SAM, you have to specify a VSAM
job catalog explicitely (CAT=IJSYSUC ).
|
VOL=volser
|
If specified a // EXTENT information is generated
with that 1 to 5 characters volume serial number; its content depends on the
preceeding DLBL information, see below.
|
DSN=fileid |
Is the DSN to set the file ID (optional). |
Potential CAT
or VOL
parameters have to come first in the DEFINE WORK FILE
string, as
the end of the parameter value can easily be found; the DSN
=
parameter must be specified as the last keyword parameter.
In other words, if CAT
or
VOL
parameters are specified, and the
DSN
keyword parameter is not specified, all data in the
DEFINE WORK FILE
parameter string behind the last keyword
parameter is considered as file ID to be set.
For VSAM/SAM, NATVSE dynamically adds the following label information:
// DLBL xxyyyyz,'file-id',0,VSAM,CAT=catalog, + RECORDS=n1,RECSIZE=n2,DISP=(dsp1,dsp2) // EXTENT ,volser optional
where:
xx | is the partition's SYSLOG ID, for example
BG , F4 , etc.
|
yyyy |
yyyy is the edited z/VSE two-byte hexadecimal task
number (to allow Natural subtasks in the same partition).
|
z | is the Natural work file number: "1" through "9" for files 1 to 9, "A" through "W" for files 10 to 32. |
n1 |
is the value specified by the keyword subparameter
BLOCKS of
profile parameter WORK .
|
n2
|
is the value specified by the keyword subparameter
BLKSIZE
of profile parameter WORK .
|
dsp1, dsp2
|
is the value specified by the keyword subparameter
DISP
of profile parameter WORK .
|
catalog
|
is the VSAM catalog which has to be set using a
DEFINE WORK FILE
statement.
|
volser | is the volume serial number on which the file is allocated. |
Note that the EXTENT
card is only generated when
volser
has been set in a DEFINE
WORK FILE
statement in the Natural application.
For other disk file management systems, for example
CA-DYNAM/D
, NATVSE
adds dynamically the following
label information:
// DLBL xxyyyyz,'file-id',0 // EXTENTsysnnn,volser,,,1,n1 optional
where:
xx | is the partition's SYSLOG ID, for example
BG , F4 , etc.
|
yyyy | is the edited z/VSE two-byte hexadecimal task number (to allow Natural subtasks in the same partition). |
z | is the Natural work file number: 1 through
9 for files 1 to 9, A through W for
files 10 to 32.
|
n1
|
is the value specified by the keyword subparameter
BLOCKS of
profile parameter WORK .
|
sysnnn
|
is the value specified by the keyword subparameter
SYSNR of
profile parameter WORK .
|
volser
|
is the volume serial number on which the file is allocated. |
Note that the EXTENT
card is only generated when
volser
has been set in a
DEFINE WORK FILE
statement in the Natural application. If
n1
is zero, extent information (start
track/block and number of tracks/blocks) is omitted.
For Natural as a server the file name setup has the format:
xyyyyyz
where:
xyyyyy
|
is the server session number in hexadecimal format (edited) with the very first character forced alphabetic by translation of 0 through F into A to P. |
z
|
is the Natural work file number, as for normal Natural under z/VSE batch operation. |
Files to be dynamically allocated must have a Natural file name of
'*' set in keyword subparameter
DEST
='*'
of profile parameter WORK
or a statement
definition of DEFINE WORK
FILE
'*'
to enable Natural under z/VSE to create
new file names as described above.
The file identification to be used also has to be set using a
DEFINE WORK FILE
statement.
The regular z/VSE restrictions for file IDs apply.
In a Natural multitasking or server environment, it is recommended to provide some unique information in the file ID to prevent "equal file" conditions.
Natural parameters:
WORK=((1-6),AM=1,DEST='*',BLOCKS=100),WORK=((2), DISP=(OLD,DELETE)),WORK=((6),BLOCKS=0)
Natural work file definition within application:
DEFINE WORK 1 'CAT=IJSYSUC,VSAM.SAM.FILE' DEFINE WORK 2 'CAT=IJSYSCT,DSN=ANOTHER FILE' DEFINE WORK 3 'CAT=IJSYSUC,VOL=DOSRES,ONE MORE FILE' DEFINE WORK 4 '==.CATALOGED.FILE' DEFINE WORK 5 'VOL=POOL01,DSN=FILE WITH EXTENT INFO' DEFINE WORK 6 'VOL=DOSRES,ANY FILE'
z/VSE labels generated:
// DLBL xxyyyy1,'VSAM.SAM.FILE',0,VSAM,CAT=IJSYSUC, + RECORDS=100,RECSIZE=4628,DISP=(NEW,KEEP) // DLBL xxyyyy2,'ANOTHER FILE',0,VSAM,CAT=IJSYSCT, + RECORDS=100,RECSIZE=4628,DISP=(OLD,DELETE) // DLBL xxyyyy3,'ONE NORE FILE',0,VSAM,CAT=IJSYSUC, + RECORDS=100,RECSIZE=4628,DISP=(NEW,KEEP) // EXTENT ,DOSRES // DLBL xxyyyy4,'==.CATALOGED.FILE',0 // DLBL xxyyyy5,'FILE WITH EXTENT INFO',0 // EXTENT SYS005,POOL01,,,1,100 // DLBL xxyyyy6,'ANY FILE',0 // EXTENT SYS006,DOSRES
The Natural z/VSE batch mode interface contains some debugging facilities which can help you to track down problems.
These facilities are controlled by the UPSI
settings in the
JCL.
Additionally, the UPSI
settings may also be specified as a
Natural session parameter
(UPSI=1XXXXXXX
, for example). This is
useful if UPSI
settings in JCL have produced side effects in the
sense that they have a different meaning for other programs such as for
front-end Natural or for programs called by Natural.
There may be the following UPSI
settings:
UPSI Setting | Meaning |
---|---|
UPSI
1XXXXXXX |
Dump Flag |
UPSI
X1XXXXXX
|
Trace Flag |
UPSI
XXX1XXXX
|
Storage Freeze Flag |
UPSI
XXXXX1XX
|
Session Abend Flag |
UPSI
XXXXXX1X
|
Abend Exit Flag |
UPSI
XXXXXXX1 |
Formatted Dump-Only Flag |
These settings are described below. In addition, a sample job is given to show you how to obtain documentation for debugging.
When Natural encounters a problem, the corresponding job usually
cancels without a dump, unless an abend actually occurred. When this
UPSI
flag is set, a dump is always created at the end of the job
when an error occurs, that is, when the Natural session termination message is
other than NAT9995.
When this flag is set, snapshots are taken of the register save area at some strategic points in Natural.
Note:
Depending on the product sample output, setting this flag can lead
to large output.
On entry of all NATVSE
service routines, the name of this
routine and the general registers 0 to 15 (GRG) are displayed.
Note:
You can identify the caller from Register 14.
On exit of all NATVSE
service routines, the name of this
routine, the current general registers (GRG) and Registers 0 to 15 of the
currently assigned save area (CSA) are displayed.
Notes:
Whenever the GRG registers are set, the debugging trace program tries to determine the name of the calling routine and the offset of the call from the beginning of the routine.
The SYSnnn
number for the
debugging trace print output is SYS040
, as long as this
SYSnnn
number is assigned to a printer
device; otherwise SYSLST
is used. This is of particular interest
if debugging trace output and other Natural print output are to be separated;
to do so, assign SYS040
appropriately and supply a POWER *
$$ LST
statement for this logical print unit.
On normal or abnormal session termination, Natural, by default,
releases all its resources including storage. Despite the setting of UPSI
1
, a dump may be useless, because all relevant storage has already been
released during Natural termination. When this flag is set, no
GETVIS
storage acquired earlier is ever released within this job;
this applies to all external subroutine programs called by Natural including
the Natural nucleus (if not linked to NATVSE
) and
RCA=ON
subproducts.
Warning: This flag should be handled carefully, because more partition GETVIS storage is used, but jobs may still cancel due to failed
GETVIS requests if the operating system storage requests cannot be
satisfied. |
By default, a Natural session is cancelled if crucial errors have occurred (NAT9nnn termination messages except NAT9995 and NAT9987). When this flag is set, Natural does not cancel, but terminates "normally" just passing the Natural return code to the job control.
This flag may be helpful in the case of recurrent abends.
In batch mode, Natural usually has a check abend exit for active
programs (STXIT PC
) to recover from program checks
(NAT095n error messages). When
DU
=ON
is
specified, this exit creates a snap dump and passes control to Natural for a
clean session termination.
When this flag is set, the Natural session runs without any abend exit for active programs, which means that all program checks are handled directly by the operating system.
If this flag is set, the dump flag, the storage freeze flag, the session abend flag and the formatted dump-only flag are ignored.
With DU
=ON
, the
NATVSE
abend exit routine creates a snap dump of the Natural
session when a program check abend occurs (and the UPSI
XXXXXX1X flag is not
set).
The failed instruction, the program check code
(S0Cn
), the general registers, the
currently active routine, the offset of the failed instruction within this
routine and the absolute (PSW) address are displayed together with Registers 0
to 15 of the currently assigned save area (CSA).
In addition, the non-reentrant Natural z/VSE driver, all areas
GETMAIN
ed by Natural and all Natural programs in the buffer pool
are dumped.
Then control is passed to Natural for a clean session termination.
Finally the job terminates via a z/VSE JDUMP
macro
resulting in a dump containing the whole partition.
Since in many cases the dynamic Natural session areas are relevant for
debugging only, the dump of the static session areas can be suppressed by
setting this UPSI
flag.
If a problem has to be analyzed, any information which might be relevant is important, in particular, the executed JCS and the corresponding console log.
The following sample job is intended to show you how to obtain comprehensive documentation:
// JOB sampljob // OPTION LOG,PARTDUMP to see JCL on printer /* Library Definitions: labels and LIBDEFs ... /* ADARUN Parameter Input Definition // ASSGN SYS000,SYSRDR /* Natural Work File Definitions // DLBL CMWKFnn,'...',... disk work file // EXTENT SYSnnn,volser,,,nn,mm // ASSGN SYSnnn,DISK,VOL=volser,SHR // TLBL CMWKFnn,'...',... labelled tape work file // ASSGN SYSnnn,cuu assignment to tape unit /* Natural Print File Definitions // ASSGN SYSnnn,cuu assignment to print UR unit // DLBL CMPRTnn,'...',... print file on disk // EXTENT SYSnnn,volser,,,nn,mm // ASSGN SYSnnn,DISK,VOL=volser,SHR // TLBL CMPRTnn,'...',... print file on labelled tape // ASSGN SYSnnn,cuu assignment to tape unit /* Debugging Options // ASSGN SYS040,SYSLST debugging trace unit // UPSI 1xxx00xx flags as discussed above // EXEC Natural,SIZE=... ... dynamic parameters /* end of dynamic parameters ... ADARUN parameters /* end of ADARUN parameters ... Natural input /* end of Natural input // EXEC LISTLOG print console messages /& end of job
The Natural z/VSE batch mode interface (NATVSE
) supports
attention interrupts via the console command MSG
xx
, where xx is
the z/VSE partition ID a console operator can force on a NAT1016 attention
interrupt event.
This special functionality is controlled by the Natural profile
parameter ATTN
.