
Natural for Mainframes	Version 8.2.6 for Mainframes	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Parameter Reference —

WORK - Work-File Assignments

This Natural profile parameter specifies the maximum number of work files to be used during the session. It corresponds to the NTWORK macro in the Natural parameter module.

Possible settings	See WORK Parameter Syntax.
Default setting	See default values of the keyword subparameters described below. Depending on the access method and the environment, there may be different default settings.
Dynamic specification	yes	The parameter `WORK` can only be specified dynamically. In the Natural parameter module, the macro `NTWORK` must be used.
Specification within session	no

Notes:

Within a session, up to 32 logical work files (numbered 1 to 32) can be used.
To provide different work file definitions, WORK or NTWORK can be specified multiple times.
The software components for accessing work files in different environments are called access methods. For the duration of a Natural session, each logical work file can be assigned to one access method only. The access method for a work file is determined by the keyword subparameter AM.
In z/OS under TSO and in batch mode, work files need not be predefined in the JCL. Provided they are defined by subparameter AM=STD, they can be allocated dynamically during the session by a Natural program using the DEFINE WORK FILE statement or the application programming interface USR2021 (in library SYSEXT).
See also Print and Work File Handling with External Data Sets in a Server Environment in the Operations documentation.

This document covers the following topics:

WORK Parameter Syntax
NTWORK Macro Syntax
Keyword Subparameters for All Environments
Keyword Subparameters for AM=STD in All Environments
Keyword Subparameters for AM=STD in z/OS Environments
Keyword Subparameters for AM=STD in z/VSE Environments
Keyword Subparameters for AM=STD in BS2000/OSD Environments
Keyword Subparameters for AM=CICS
Keyword Subparameters for AM=COMP
Keyword Subparameters for AM=SMARTS

WORK Parameter Syntax

With the WORK parameter, you first specify one or more logical work file numbers and then several keyword subparameters, which define the characteristics for these work files:

WORK=((work-file-numbers),keyword-subparameters,...)

Where:

Syntax Element	Description
`work-file-numbers`	The file numbers must be specified first and enclosed in parentheses: The numbers can be from 1 to 32. They can be specified in any sequence. Multiple numbers must be separated from one another by commas or blanks. To specify a range of numbers, you can use a hyphen (-).
`keyword-subparameters`	The keyword subparameters (for the different environments) are described below. If any previous definition (or default) for the same work file exists, only the values for the specified keyword subparameters are overwritten, all other values remain unchanged.

Note:
To provide different work file definitions, WORK can be specified multiple times.

Examples:

WORK=((2,12,18),AM=STD,DEST='WORK**') 
WORK=((1,3,6-11,15),AM=COMP,OPEN=INITOBJ,CLOSE=CMD)

NTWORK Macro Syntax

With an NTWORK macro, you first specify one or more logical work file numbers, and then several keyword subparameters, which define the characteristics for these work files:

         NTWORK (work-file-numbers),keyword-subparameters,...

Where:

Syntax Element	Description
`work-file-numbers`	The file numbers must be specified first and enclosed in parentheses: The numbers can be from 1 to 32. They can be specified in any sequence. Multiple numbers must be separated from one another by commas or blanks. To specify a range of numbers, you can use a hyphen (-).
`keyword-subparameters`	The keyword subparameters (for the different environments) are described below. If any previous definition (or default) for the same work file exists, only the values for the specified keyword subparameters are overwritten, all other values remain unchanged.

Note:
To provide different work file definitions, NTWORK can be specified multiple times.

Examples:

         NTWORK (2,12,18),AM=STD,DEST='WORK**' 
         NTWORK (1,3,6-11,15),AM=COMP,OPEN=INITOBJ,CLOSE=CMD

Keyword Subparameters for All Environments

The following keyword subparameters are available for all environments:

AM - Type of Access Method

AM=value specifies the type of access method to be used.

Value	Access Method
`STD`	Standard sequential files (batch, TSO, TIAM).
`COMP`	Com-plete work files.
`SMARTS`	SMARTS work files. Work file on a SMARTS Portable File System (PFS).
`CICS`	CICS transient data or temporary storage.
`PC`	Entire Connection.
`USER`	Third-party vendor work-file interface.
`OFF`	Unassigned. No automatic assignments if `FAMSTD=OFF` is set. Note: `WORK=OFF` is equivalent to: `WORK=((1-32)),AM=OFF)`. It does not affect any of the other keyword subparameter specifications.
`0`	Unassigned. Automatic assignments if `FAMSTD=OFF` is set. This is the default value.

Notes:

For an online session, all work files to be used have to be assigned to a specific access method.
For a batch session, any work files not assigned to a specific access method will be automatically detected and assigned by the standard batch access method (AM=STD), provided that they have been predefined in the JCL. See also FAMSTD - Overwriting of Print and Work File Access Method Assignments.

DEST - External Data Set Name

DEST=value specifies the external data set name.

Value	Explanation
1 - 8 characters or 1 - 7 characters, depending on access method and environment.	Name of the external data set. Note: The `DEST` subparameter corresponds to `operand1` of the `DEFINE WORK FILE` statement, and the subparameter value can be overwritten by a `DEFINE WORK FILE` specification.

The meaning of the subparameter DEST depends on the access method specified with the AM subparameter:

Access Method Meaning of Keyword Subparameter DEST

Access Method	Meaning of Keyword Subparameter DEST
`AM=STD`	`DEST` is the logical data set name (`DDNAME`, `LINK` name, DTF name). Notes: If the destination is to be for multiple files, two asterisks () have to be specified for the file number. These will be replaced by the corresponding logical file number for each work file. A `DEST` value including two asterisks must be enclosed in apostrophes ('), when it is used as a dynamic parameter. The default value is `DEST='CMWKF'` for z/OS, z/VSE, and `DEST='W**'` for BS2000/OSD environments. Under z/VSE, only 7-character names are supported.
`AM=CICS`	There is no default value for work files under CICS. Here, the `DEST` subparameter is mandatory; that is, CICS work files defined without a valid `DEST` specification are ignored. Note: The Natural CICS interface also supports a variable (see `TERMVAR` parameter in the `NCIPARM` generation macro; `&TID` is the default) as part of the `DEST` value which, when being specified, is replaced by the actual CICS terminal ID; see also Natural Print and Work Files under CICS in the TP Monitor Interfaces documentation).
`AM=COMP`	`DEST` defines the name of the Com-plete SD-file. The length is restricted to a maximum of 8 characters. Notes: If the file is defined with `TYPE=TID`, the `DEST` value is appended by the Com-plete stack level. The length is restricted accordingly to a maximum of 7 characters. SD-file names starting with `'&&'` are treated as temporary files which are deleted automatically after Natural termination.

AM=STD

DEST is the logical data set name (DDNAME, LINK name, DTF name).

Notes:

If the destination is to be for multiple files, two asterisks (**) have to be specified for the file number. These will be replaced by the corresponding logical file number for each work file. A DEST value including two asterisks must be enclosed in apostrophes ('), when it is used as a dynamic parameter.
The default value is DEST='CMWKF**' for z/OS, z/VSE, and DEST='W**' for BS2000/OSD environments.
Under z/VSE, only 7-character names are supported.

AM=CICS

There is no default value for work files under CICS. Here, the DEST subparameter is mandatory; that is, CICS work files defined without a valid DEST specification are ignored.

Note:
The Natural CICS interface also supports a variable (see TERMVAR parameter in the NCIPARM generation macro; &TID is the default) as part of the DEST value which, when being specified, is replaced by the actual CICS terminal ID; see also Natural Print and Work Files under CICS in the TP Monitor Interfaces documentation).

AM=COMP

DEST defines the name of the Com-plete SD-file. The length is restricted to a maximum of 8 characters.

Notes:

If the file is defined with TYPE=TID, the DEST value is appended by the Com-plete stack level. The length is restricted accordingly to a maximum of 7 characters.
SD-file names starting with '&&' are treated as temporary files which are deleted automatically after Natural termination.

OPEN - Time of File Opening

OPEN=value specifies when the file is to be opened:

Value	Explanation: The file is opened ...
`INIT`	for output at session initialization.
`OBF`	according to the default `OPEN` value for the different environments (batch, CICS, Com-plete, TSO).
`OBJ`	when the execution of the first object which accesses the file starts. This is the default value.
`INITOBF`	for output at session initialization. Any subsequent re-opening of the file sets the default `OPEN` value for the different environments (batch, CICS, Com-plete, TSO).
`OBJ1`	when the execution of the first object on level 1 which accesses the file starts. Otherwise, it is opened when it is first accessed.
`ACC`	when it is first accessed by a statement.
`INITOBJ`	for output at session initialization. Any subsequent re-opening of the file will be performed when the execution of the first object which accesses the file starts.
`INITOBJ1`	when the execution of the first object on level 1 which accesses the file starts. Otherwise, it is opened when it is first accessed.
`INITACC`	for output at session initialization. Any subsequent re-opening of the file will be performed when it is first accessed by a statement.

CLOSE - Time of File Closure

CLOSE=value specifies when the file is to be closed:

Value	Explanation: The file is closed ...
`OBJ`	when processing of the object in which it was first accessed is finished, or when command mode, `NEXT` mode or `MAINMENU` is reached.
`CMD`	when command mode, `NEXT` mode or `MAINMENU` is reached. This is the default value.
`FIN`	at session end. Note: With `CLOSE=FIN`, a `DEFINE WORK FILE` statement causes an error if the work file was opened already. A `CLOSE WORK FILE` statement for the work file is ignored. When the end-of-file condition occurs during the `READ WORK FILE` statement, Natural closes the work file immediately.
`USER`	This value specifies that a work file is closed only if the file is open and one of the following conditions is true: a `CLOSE WORK FILE` statement is issued, a `DEFINE WORK FILE` statement is issued, session termination.

LRECL - Default and Maximum Record Length of Data Set

LRECL=value specifies the record length of the data set.

Value	Explanation
`0` or `5 - 32767`	Record length of the data set (in bytes).
`0`	This is the default value.

Note:
This subparameter is used particularly to check for truncation and padding. For more information on AM=STD, see the keyword subparameter LRECL in the section Keyword Subparameters for AM=STD in All Environments.

TRUNC - Truncation of Output Records

TRUNC=value specifies whether the output records are truncated or not.

Possible values:

Value	Explanation
`ON`	Output records that are longer than the record length (`LRECL`) of the data set will be truncated.
`OFF`	Error NAT1512 will be issued if an output record is longer than the data set record length. This is the default value.

PAD - Padding of Output Records

PAD=value specifies whether the output records are padded or not (applies only to data sets of fixed record length).

Value	Explanation
`ON`	Output records that are shorter than the record length (`LRECL`) of the data set will be padded with padding characters defined by keyword subparameter `PADCHRO`. This is the default value.
`OFF`	Error NAT1510 will be issued if an output record is shorter than the data set record length.

PADCHRO - Padding Character of Output Records

PADCHRO=value specifies the character which is used for padding of output records if PAD=ON is defined for the work file.

Value	Explanation
`'x'` or `x'xx'`	One character `x` within single quotes or one hex character `xx`.
`x'00'`	This is the default value.

PADCHRI - Padding Character of Input Records

PADCHRI=value specifies the character which is used for padding of input records.

Value	Explanation
`'x'` or `x'xx'`	One character `x` within single quotes or one hex character `xx`.
`x'40'`	Blank. This is the default value.

Keyword Subparameters for AM=STD in All Environments

The following keyword subparameters are available for AM=STD in all environments:

RECFM | BLKSIZE | LRECL

RECFM - Default Record Format of Data Set

RECFM=value specifies the default record format of the data set.

Supported formats:

Value	Format
`F`	Fixed
`V`	Variable
`U`	Undefined
`B`	Blocked
`S`	Spanned
`A`	ASA
`M`	Machine control characters

Possible values or combinations of values:

Value	Explanation
`F, FA, FM, FB, FBA, FBM, V, VA, VM, VB, VBA, VBM, VBS, VBSA, VBSM, U, UA, UM`	These values or combinations of values that can be specified.
`VB`	Variable blocked. This is the default value.

Note:
The RECFM specification only applies if no record format is predefined in the JCL or (under z/OS only) in the data set DCB.

BLKSIZE - Default Block Size of Data Set

BLKSIZE=value specifies the default block size of the data set.

Value	Explanation
`0` or `8 - 32767`	Default block size of the data set (in bytes).
`4628`	This is the default value.

Note:
The BLKSIZE specification only applies if no block size is predefined in the JCL or (under z/OS only) in the data set DCB.

LRECL - Default and Maximum Record Length of Data Set

LRECL=value specifies the record length of the data set.

Value	Explanation
`0` or `5 - 32767`	Record length of the data set (in bytes).
`0`	This is the default value.

Notes:

This subparameter is used particularly to check for truncation and padding.
For RECFM=V(B) the LRECL value includes a 4-byte record descriptor word.
If LRECL=0 is defined, the following applies: With RECFM=V(B), LRECL defaults to BLKSIZE-4. With RECFM=U, LRECL defaults to BLKSIZE. With RECFM=F(B), the maximum record length in the Natural program being executed is taken when the file is opened. If no record length from a program is available when the file is opened, for example with OPEN=INIT, this leads to an error.
The LRECL specification only applies if no record length is predefined in the JCL or (z/OS only) in the data set DCB.

Keyword Subparameters for AM=STD in z/OS Environments

The following keyword subparameters are available for AM=STD in z/OS environments:

REREAD | FREE | BUFNO | DISP | VMAX

REREAD - Closing of Tape File Data Sets

REREAD=value specifies the REREAD option for the closing of the tape file.

Value	Explanation
`ON`	The `REREAD` option is set for the `CLOSE SVC`. This causes the volume to be repositioned to reprocess the data set. This is the default value.
`OFF`	The `REREAD` option is not set for the `CLOSE SVC`.

FREE - Data Set De-allocation at File Closure

FREE=value specifies whether the data set is de-allocated when the file is closed.

Value	Explanation
`ON`	The `FREE` option is set for the CLOSE SVC, which means that the data set is de-allocated when it is closed (and not at step termination).
`OFF`	The `FREE` option is not set for the CLOSE SVC. This is the default value.

BUFNO - Default Number of z/OS I/O Buffers of Data Set

BUFNO=value specifies the default number of z/OS I/O buffers of the data set.

Value	Explanation
`0` or `1 - 255`	Default number of z/OS I/O buffers of the data set.
`0`	With `BUFNO=0`, z/OS allocates five I/O buffers per default. This is the default value.

Notes:

The number of I/O buffers can improve the performance of work file access dramatically. Note that the storage for I/O buffers is allocated below the 16 MB line.
The BUFNO specification applies only if the BUFNO parameter is not specified in the JCL for the data set.

DISP - Open Work File for Modification

DISP=value specifies that the work file is opened for modification.

Value	Explanation
`MOD`	New records are added at the end of the file. Note: This corresponds to the JCL DD statement subparameter `DISP=MOD`.
`NOMOD`	The work file is rewritten from the start. This is the default value.

VMAX - Control LRECL for Variable Record Format

VMAX=value controls the LRECL setting for an output file with variable record format (RECFM=V).

Value	Explanation
`ON`	Providing a non-zero `BLKSIZE` value exists for the file, `VMAX=ON` sets `LRECL=BLKSIZE-4` for variable record format, regardless of the `LRECL` setting in the DCB or the `LRECL` subparameter.
`NAT`	`LRECL` is set to the length `+4` of the largest record in the application program if this value is less than `LRECL` in the DCB for the data set.
`OFF`	`LRECL` from the DCB for the data set is used. This is the default value.

Keyword Subparameters for AM=STD in z/VSE Environments

The following keyword subparameters are available for AM=STD in z/VSE environments:

SYSNR | LABEL | REWIND | BLOCKS | DISP

SYSNR - Logical VSE SYS Number

SYSNR=value specifies the logical VSE SYS number.

Value	Explanation
`1 - 99`	Logical VSE SYS number. By default, the SYS number is identical to the work file number.

LABEL - Tape Label Processing

LABEL=value specifies the tape label processing.

Value	Explanation
`ON`	The tape is in standard label format. This is the default value.
`OFF`	The tape is unlabeled with front tape mark.
`NOTM`	The tape is unlabeled without front tape mark.

REWIND - Action at File Closure

REWIND=value specifies the action to be taken when a tape file is closed.

Value	Explanation
`ON`	The tape is rewound when the file is closed. This is the default value.
`OFF`	The tape is not rewound when the file is closed.
`UNLOAD`	The tape is unloaded when the file is closed.

BLOCKS - Number of Storage Blocks

BLOCKS=value specifies the number of file blocks or file tracks to be allocated for a dynamic NATVSE work file.

Value	Explanation
`1 - 9999`	Number of file blocks or file tracks to be allocated.
`20`	This is the default value.

Note:
See NATVSE Dynamic Work File Allocation (DYNALLOC) Support in the Operations documentation.

DISP - Work File Disposition for VSAM/SAM

DISP=(value1,value2) specifies the disposition of a dynamic NATVSE work file controlled by VSAM/SAM.

Value Pair	Explanation
`(NEW,KEEP)`	File is to be reset at open and to be kept at close. This is the default value.
`(NEW,DELETE)`	File is to be reset at open and to be made inaccessible at close.
`(OLD,DELETE)`	File is not to be reset at open and to be made inaccessible at close.
`(OLD,KEEP)`	File is not to be reset at open and to be kept at close.

Note:
See NATVSE Dynamic Work File Allocation (DYNALLOC) Support in the Operations documentation.

Keyword Subparameters for AM=STD in BS2000/OSD Environments

The following keyword subparameter is available for AM=STD in BS2000/OSD environments:

DISP

DISP - File Open Mode

DISP=value specifies the open mode of the file.

Value	Explanation
`EXT`	The open mode is set to `EXTEND`.
`NOEXT`	The open mode is set to the default value `OUTPUT`. This is the default value.

Keyword Subparameters for AM=CICS

The following keyword subparameters are available for AM=CICS:

TYPE | DISP

TYPE - Type of CICS Storage Medium

TYPE=value specifies the type of CICS storage medium to be used.

Value	Explanation
`MAIN`	Temporary main storage.
`AUX`	Temporary auxiliary storage.
`TD`	Transient data.

Note:
The default value used depends on the setting of the subparameter DEST. If the DEST subparameter value matches a valid CICS transient data queue, the TYPE subparameter defaults to TD, otherwise MAIN will be taken as default value.

DISP - CICS Temporary Storage Queue Disposition

DISP=(value1,value2) specifies the CICS temporary storage queue disposition.

Value Pairs	Explanation
`(NEW,KEEP)`	The storage queue is deleted when the file is opened. This is the default value.
`(NEW,DELETE)`	The storage queue is deleted when the file is opened and when it is closed.
`(OLD,DELETE)`	The storage queue is deleted when the file is closed.
`(OLD,KEEP)`	The storage queue is not deleted.

Note:
The DISP specification does not apply to CICS extra-partition transient data queues.

Keyword Subparameters for AM=COMP

The following keyword subparameters are available for AM=COMP:

TYPE | BLOCKS | BLKSIZE

TYPE - Type of Storage Access

TYPE=value specifies the type of storage access to be used.

Value	Explanation
`SHR`	Shared access; that is, the work file is accessible by all users.
`TID`	The work file is only available to the current Com-plete terminal ID.
`DYN`	The work file is only available to the current terminal stack level.

BLOCKS - Number of Storage Blocks

BLOCKS=value specifies the number of storage blocks to be allocated.

Value	Explanation
`1 - 9999`	Number of storage blocks to be allocated.
`20`	This is the default value.

BLKSIZE - Size of Storage Blocks

BLKSIZE=value specifies the default block size of the data set.

Value	Explanation
`0` or `8 - 32767`	Default block size of the data set (in bytes).
`4628`	This is the default value.

Keyword Subparameters for AM=SMARTS

The following keyword subparameters are available for AM=SMARTS:

DEST | TYPE | DISP

DEST - Work File Name

DEST=value specifies the work file name.

Value	Explanation
1 - 8 characters.	Work file name.

Notes:

Since the DEST clause is restricted to an 8 character maximum, it is useless to define a file with absolute PFS path specification.
The name specified in the DEST clause is relative to the work file root directory. The work file root directory is specified with the environment variable NAT_WORK_ROOT.
To specify a file with absolute path definition, use the DEFINE WORK FILE statement.

TYPE - Type of Storage Access

TYPE=value specifies the type of storage access to be used.

Value	Explanation
`BIN`	Each line is written to the work file without terminating end-of-line character. This is the default value.
`TXT`	Each line is written to the work file with a terminating end-of-line character (`x'15'`).

DISP - File Open Mode

DISP=(value1,value2,value3) specifies the mode of the work file.

Value	Explanation
`value1`	`value1` specifies whether an existing file should be deleted or new data should be appended to the file.
	`NEW`	An existing file will be deleted if the file is opened for writing. This is the default value.
	`OLD` or `MOD`	New data written are appended at the end of the file.
`value2`	`value2` specifies whether a file should be kept or removed after access.
	`KEEP`	Permanent file that will be kept after close. This is the default value.
	`DELETE`	Temporary file that will be removed after close.
`value3`	`value3` specifies whether a user has exclusive access to the file or not.
	`SHR`	Shared access; that is, the work file is accessible by all users. This is the default value.
	`OWN`	Exclusive access, the work file is accessible to the current Comp-lete user ID. Files with exclusive access are located in an additional directory which has the name of the current user ID.

Example 1:

DISP=(NEW,KEEP,SHR)

Example 2:

If you specify only the first value (with or without parentheses), the other values will assume their default settings:

DISP=(MOD)

DISP=MOD

Both specifications correspond to:

DISP=(MOD,KEEP,SHR)

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT