DEFINE WORK FILE
n
|
[ATTRIBUTES
{operand3}...]
|
Note:
The elements shown in square brackets [...] are optional, however, at
least one of them must be specified with this statement.
This document covers the following topics:
For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.
Related Statements: CLOSE WORK
FILE
| READ WORK
FILE
| WRITE WORK
FILE
Belongs to Function Group: Control of Work Files / PC Files
The statement DEFINE WORK FILE
is used to assign a file
name to a Natural work file number within a Natural application. This allows
you to make or change work file assignments dynamically within a Natural
session or overwrite work file assignments made at another level.
When this statement is executed and the specified work file is already open, the statement will implicitly close the work file.
All work files to be used during a session must be preassigned
to an access method by means of keyword subparameter
AM
of profile parameter WORK
or automatically
by definition in the JCL.
Note:
For Unicode and code page support on mainframe platforms, see
Work Files and Print Files
in the Unicode and Code Page Support documentation.
Operand Definition Table:
Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operand1 | C | S | A | U | yes | no | |||||||||||||
operand2 | C | S | A | U | yes | no | |||||||||||||
operand3 | C | S | A | U | yes | no |
Syntax Element Description:
Syntax Element | Description | |
---|---|---|
DEFINE WORK FILE
n
|
Work File
Number: n is the work
file number (1 to 32). This is the number to be used in a
WRITE WORK FILE ,
READ WORK FILE or
CLOSE WORK FILE
statement.
|
|
operand1
|
Work File
Name: operand1 is the
name of the work file.
As If Note: Information on operating-system- or TP-monitor-dependent work file naming conventions is included in the following sections: |
|
TYPE
operand2
|
TYPE Clause:
The value of |
|
UNFORMATTED
|
A completely unformatted file. No formatting information is written (neither for fields nor for records).
Format: |
|
FORMATTED
|
|
|
ATTRIBUTES
{operand3}... |
ATTRIBUTES Clause:
This clause makes sense only in Natural for Open Systems; in Natural for Mainframes it is ignored. |
Examples:
DEFINE WORK FILE 17 #FILE TYPE 'UNFORMATTED' #TYPE := 'FORMATTED' DEFINE WORK FILE 18 #FILE TYPE #TYPE
The following topics are covered:
Under z/OS, for a work-file number that is defined with the access
method AM=STD
,
operand1
can be:
a logical data set name (DD name, 1 to 8 characters);
a physical data set name of a cataloged data set (1 to 44 characters) or a physical data set member name;
a path name and member name of an HFS file (1 to 253 characters) in an MVS UNIX Services environment;
NULLFILE
.
Logical Data Set Names |
Example: DEFINE WORK FILE 21 'SYSOUT1' The specified data set The allocation can be done via JCL, CLIST (TCO) or dynamic
allocation (SVC 99). For dynamic allocation you can use the application
programming interface The data set name specified in the Optionally, the data set name may be prefixed by DEFINE WORK FILE 22 'DDN=MYWORK' |
Physical Data Set Names |
Example: DEFINE WORK FILE 23 'TEST.WORK.FILE' The specified data set must exist in cataloged form. When the
If the data set name is 8 characters or shorter and does not
contain a period (.), it might be misinterpreted as a DD name. To avoid this,
prefix the name with DEFINE WORK FILE 22 'DSN=WORKXYZ' If the data set is a PDS member, you specify the PDS member name (1 to 8 characters) in parentheses after the data set name (1 to 44 characters). For example: DEFINE WORK FILE 4 'TEST.WORK.PDS(TEST1)' If the specified member does not exist, a new member of that name will be created. |
HFS Files |
Example: DEFINE WORK FILE 14 '/u/nat/rec/test.txt' The specified path name must exist. When the For the dynamic allocation of the data set, the following z/OS path options are used: PATHOPTS=(OCREAT,OTRUNC,ORDWR) PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP) FILEDATA=TEXT When an HFS file is closed, it is automatically de-allocated by
z/OS (regardless of the setting of keyword subparameter
To read an HFS file, you have to use the application programming
interface |
JES Spool File Class |
To create a JES spool data set, you specify
Examples: DEFINE WORK FILE 10 'SYSOUT=A' DEFINE WORK FILE 12 'SYSOUT=*' To specify additional parameters for the dynamic allocation, use
the application programming interface |
NULLFILE |
To indicate a dummy data set. |
When the DEFINE WORK FILE
statement is executed and a
physical data set name, HFS file, spool file class or dummy data set has been
specified, the corresponding data set is allocated automatically. If the
logical file is already open, it will be closed automatically, except when the
keyword subparameter CLOSE=FIN
of profile
parameter WORK
has been
specified, in which case an error will be issued. Moreover, an existing data
set allocated with the same current DD name is automatically de-allocated
before the new data set is allocated. To avoid unnecessary overhead by
unsuccessful premature opening of work files not yet allocated at the start of
the program, work files should be defined with keyword subparameter
OPEN=ACC
(open at first access) of profile parameter WORK
.
In the case of an HFS file, or a work file defined with keyword
subparameter FREE=ON
of profile
parameter WORK
, the work file
is automatically de-allocated as soon as it has been closed.
As an alternative for the dynamic allocation and de-allocation of data
sets, the application programming interface USR2021N
(dynamic data
set allocation) in the library SYSEXT
is provided. This API also
allows you to specify additional parameters for dynamic allocation.
In server environments, errors may occur if multiple Natural sessions
attempt to allocate or open a data set with the same DD name. To avoid this,
you either specify the work file with keyword subparameter
DEST=*
of
profile parameter WORK
, or you specify
DEFINE WORK FILE '*'
in your program before the actual
DEFINE WORK FILE
statement. Natural then generates a unique DD
name at the physical data set allocation when the first DEFINE WORK
FILE
statement for that work file is executed.
All work files whose DD names begin with CM
are shared by
all sessions in a server environment. A shared work file opened for output by
the first session is physically closed when the server is terminated. A shared
work file opened for input is physically closed when the last session closes
it, that is, when it receives an end-of-file condition. When a work file is
read concurrently, one file record is supplied to one
READ WORK FILE
statement
only.
Under z/VSE, for a work-file number that is defined with the access
method
AM=STD
,
operand1
can be:
a logical data set name (DD name, 1 to 7 characters);
NULLFILE
(to
indicate a dummy data set).
Logical Data Set Names |
Example: DEFINE WORK FILE 21 'SYSOUT1' The specified data set The data set name specified in the Optionally, the data set name may be prefixed by DEFINE WORK FILE 22 'DDN=MYWORK' |
NULLFILE
|
To allocate a dummy data set, you specify DEFINE WORK FILE n 'NULLFILE' |
Under BS2000, for a work-file number that is defined with the access
method
AM=STD
,
you can use operand1
to specify a file
name or a link name that is allocated to this work file.
In this case, operand1
can have
a length of 1 to 253 characters and one of the following meanings:
a BS2000 link name (1 to 8 characters)
a BS2000 file name (9 to 54 characters)
a generic BS2000 file name (wildcard)
a BS2000 file name and link name
a generic BS2000 file name and link name (wildcard)
The following rules apply.
File name and link name can be specified as positional parameters or
keyword parameters. The corresponding keywords are FILE=
and
LINK=
. Mixing positional and keyword parameters is allowed but not
recommended.
A string with a length of 1 to 8 characters without commas is interpreted as a link name. This notation is compatible with earlier versions of Natural. Example:
DEFINE WORK FILE 1 'W01'
The corresponding definition with a keyword parameter is:
DEFINE WORK FILE 1 'LINK=W01'
A string of 9 to 54 characters without commas is interpreted as a file name.
Example:
DEFINE WORK FILE 2 'NATURALvr.TEST.WORKFILE02'
where vr represents the relevant product version.
The corresponding definition with a keyword parameter is:
DEFINE WORK FILE 2 'FILE=NATURALvr.TEST.WORKFILE02'
The following input is interpreted without considering the length and therefore forms exceptions to Rules 2 and 3:
keyword input: LINK=
, FILE=
*DUMMY
NULLFILE
(equivalent to *DUMMY
)
*
*,*
Example: DEFINE WORK FILE 7 'FILE=Y'
is a valid file
allocation and not a link name, although the string of characters contains
fewer than 9 characters.
Generic file names are formed as follows:
Wnn.userid.tsn.date.time.number
where
nn |
is a work-file number |
userid |
is a Natural user-ID, 8 characters |
tsn |
is the BS2000 TSN of the current task, 4 digits |
date |
is DDMMYYYY |
time |
is HHIISS |
number |
is a number, 5 digits |
Generic link names are formed as follows:
NWFnnnnn
nnnnn
is a 5-digit number
that is increased by one after every generation of a dynamic link name.
Changing the file allocation for a work-file number causes an
implicit CLOSE
of the work file allocated so far.
You are strongly recommended, in all cases except when you only specify
a link name (for example: W01
), to work with keyword parameters.
This avoids conflicts of interpretation with additional reports and is
essential for file names with fewer than 9 characters.
Example:
DEFINE WORK FILE 3 'LINK=#W03' DEFINE WORK FILE 3 'FILE=#W03'
Link Name |
Example: DEFINE WORK FILE 1 'LINKW01' means the same as DEFINE WORK FILE 1 'LINK=LINKW01' A file with the link |
File Name |
Example: DEFINE WORK FILE 2 'NATURALvr.TEST.WORK02' means the same as DEFINE WORK FILE 2 'FILE=NATURALvr.TEST.WORK02' where vr represents the relevant product version. The file specified in
|
Generic File Name |
Example: DEFINE WORK FILE 21 '*' means the same as DEFINE WORK FILE 21 'FILE=*' A file with a name created according to Rule 4 is set up using a
DEFINE WORK FILE 22 'FILE=*,LINK=WFLK22' A file with a name created according to Rule 4 is set up with the
specified link name, using a |
File Name and Link Name |
Example: DEFINE WORK FILE 11 'NATURALvr.TEST.WORKF11,LNKW11' means the same as DEFINE WORK FILE 11 'FILE=NATURALvr.TEST.WORKF11,LINK=LNKW11' which means the same as DEFINE WORK FILE 11 'FILE=NATURALvr.TEST.WORKF11,LNKW11' where vr represents the relevant product version. The file given in |
Generic File Name and Link Name |
Example: DEFINE WORK FILE 27 '*,*' means the same as DEFINE WORK FILE 27 'FILE=*,LINK=*' A file with a file name and link name created according to Rule 4
and Rule 5 is set up using a |
*DUMMY
|
To indicate a dummy data set. |
For a work-file number defined with access method
AM=CICS
,
operand1
can be a transient data or
temporary storage queue name (1 to 8 characters), depending on keyword
subparameter TYPE
of profile parameter WORK
for the work
file. For TYPE=TD
, only
the first 4 characters of operand1
are
honored and the transient data destination must be predefined to CICS.
For further information on work files, see Natural Print and Work Files under CICS in the TP Monitor Interfaces documentation.
Under Com-plete with access method
AM=SMARTS
,
PFS files are available. Any work file name can be assigned, even if it has not
been defined to Natural. For example:
DEFINE WORK (14) '/nat/path/workfile' DEFINE WORK (14) 'workfile'
It depends on the MOUNT_FS
parameter of SMARTS
whether the file is located on a SMARTS portable file system or on the native
file system. The first element of the path (/nat/)
determines the target file system.
If the string does not start with a slash (/), the path of the file is
taken from the environment variable
$NAT_WORK_ROOT
.
The specified path name must exist. When the DEFINE WORK
FILE
statement is executed, the file is allocated dynamically. If the
specified member does not exist, a new member of that name will be created.