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 FILEor
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
GETMAINed 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.