Macro type: type S (E form/L form/D form/C form); see "Macro types"
The FILE macro processes permanent and temporary files (but not EAM files) and file generations. It can be used to create new files and catalog entries, to change file attributes, and to import files from private volumes.
Except for the retention period (RETPD), the FILE macro cannot be used to define or change file attributes such as the passwords or the access type. If a catalog entry is created by means of FILE, the system default values are used for these attributes. They can, if necessary, then be modified by means of a CATAL macro.
Via the task file table (TFT), the FILE macro establishes a connection between the program and the file and between the file attributes defined in the FILE macro or the catalog entry and the FCB macro.
Main functions of the FILE macro
creating catalog entries for new files and file generations
requesting devices and volumes
allocating and releasing storage space
creating TFT entries with details of the file processing (data structure, OPEN mode, etc.)
defining the data organization on tapes.
This introduction is followed by an overview of the functions of the FILE macro at the operand level. The various subjects (such as TFT, TST, etc.) are described in detail in the introduction to this manual, i.e. in the opening chapters.
Catalog entry
If the file or file generation specified in the FILE macro is not yet cataloged, a catalog entry is created. If the file (generation) is already cataloged, DMS accesses the catalog entry when the file is opened and updates it, if necessary, when the file is closed again. The values entered for the operands IOPERF, IOUSAGE, DEVICE, VOLUME, SPACE, DDEVICE, DVOLUME, DSPACE, STATE=FOREIGN (for tape files) and FSEQ (in part) are evaluated and transferred to the catalog entry; otherwise, the corresponding system defaults are set. Entries for the remaining operands in a FILE macro are only evaluated in combination with a file link name and are transferred to the TFT entry.
If the catalog entry contains a basic access control list (BASIC-ACL), DELDATE or GUARDS, it is not possible to create a tape file using FILE (a FILE macro with the corresponding DEVICE operand will be rejected).
If a file (generation) which is to be cataloged is stored on private disk, DMS takes the values for the catalog entry from the F1 label of the first volume containing the file.
The following is specified for cataloging a new file:
for BACKUP: | E for temporary file and working file; otherwise: according to BACKUP system parameter |
for MIGRATE: | FORBIDDEN for specification of a disk belonging to an SM pubset in the VOLUME operand; otherwise: INHIBITED for temporary files, ALLOWED for permanent files |
for NUM-OF-BACKUP-VERS | 0 for temporary file, for file on private disk or on tape and for each file generation; |
for CCS: | Coded character set from the user catalog of the file owner. If this character set equals |
for NETCCS: | At node file creation, the Net-Storage coded character set is entered according to its definition in the user entry. The resulting NETCCS of the file is identified based on the following table: |
CCS entry 1 | NETCCS entry 1 | Resulting NETCCS in the catalog entry of the node file |
EDF03IRV/*NONE | *ISO | ISO88591; during code conversion, EDF041 is assumed for CCS |
EDF03DRV | *ISO | ISO88591; during code conversion, EDF04DRV is assumed for CCS |
EDF04DRV | *ISO | ISO88591 |
EDF04x | *ISO | ISO8859x with x=1,2,..F |
ISO8859x | *ISO or *NO-CONV | ISOx |
UTFx | *ISO or *NO-CONV | UTFx |
<name_a 1..8> | <name_b 1..8> | <name_b 1..8> |
<name_a 1..8> | *NO-CONV | <name_a 1..8> |
1 User entry (SYSSRPM) or CATALOG or CREATE-FILE or MODIFY-FILE-ATTRIBUTES entry
If a file has a catalog entry but as yet no disk storage space and is to be assigned space on a private disk through the FILE call, the file may not be encrypted.
If a file has a catalog entry but as yet no tape type and is to be assigned a tape type through
the FILE call, the file may be encrypted only if a file generation is involved. This is then decrypted.
When a new file generation is cataloged, the encryption attributes are transferred from the group entry to the new catalog entry. This does not apply for file generations on tape.
File link name / task file table (TFT)
If a file link name is specified with the LINK operand in the FILE macro, the system creates an entry in the job-specific TFT and transfers to this entry values specified in the current FILE macro, including any NULL operands (see below). When the file is opened, the values from the TFT are placed in the file control block (FCB).
At the OPEN, the specifications for a file are thus contained in:
the TFT entry
the file control block (FCB) of the program
the catalog entry of the file
The catalog entry is subsequently updated with the values contained in the file control block (see OPEN and CLOSE processing, in the “Introductory Guide to DMS” [1]).
Pool link name / ISAM pools
With NK-ISAM, ISAM files are processed in ISAM pools. The connection between the user ISAM pool and the file is established via the pool link name, which is specified by means of the POOLLNK operand. If no pool link name is specified, the file is processed in one of the standard system ISAM pools.
Access methods
Depending on the access method, data structures such as the record length, block size, etc. can be defined by means of the FILE macro.
The operand descriptions point out special features and interactions between the various operands.
NULL operands
Some operands of the FILE macro may be specified as “NULL operands” together with a file link name (null string = an empty character string as the operand value).
When the file is subsequently opened, the appropriate information for these file attributes is obtained from the catalog entry and transferred to the file control block (FCB).
FILE ...,LINK=name,FCBTYPE=,RECFORM=,...
The following operands may be specified as NULL operands in combination with a file link name:
BLKCTRL, BLKSIZE, BUFOFF, CODE, FCBTYPE, FSEQ, IOPERF, IOUSAGE, KEYLEN, KEYPOS, LOGLEN, RECFORM, RECSIZE, VALLEN and VALPROP
The term “NULL operand” applies only to the above-mentioned operands of the FILE macro. Operand values can also be omitted for other macros; however, but this normally causes the default setting or the default value for the operands to be used.
Version of the FILE macro
The VERSION operand determines which macro format is generated. If VERSION is omitted or if VERSION=0 is specified, the operand list and SVC for the old format (BS2000 V9.0) are generated. The new operands introduced with BS2000 V9.5 and the device types valid as of BS2000 V9.5 are supported as of VERSION=1. New features introduced with BS2000 V10.0 and BS2000/OSD-BC V1.0, especially the new layout of the operand list in which the variable parts are extracted and kept in separate lists (see “Programming notes”, "FILE - Define file attributes / control file processing"), can be used as of VERSION=2.
Figure 7: Functions of the FILE macro
Function overview
Operand | Operand value | Function / meaning |
Naming and cataloging files, defining link names | ||
pathname |
| |
DATATTR | Specifies the reference file from which, during creation of a TFT entry, certain values are to be taken which are not explicitly specified with the respective operands | |
*DUMMY | Define a dummy file | |
LINK | name | Define a file link name for which a TFT entry is created |
POOLLNK | name | For NK-ISAM files: define a pool link name for the user ISAM pool |
STATE | FOREIGN | Import a file from private volumes or from a Net-Storage volume |
File attributes | ||
AVAIL | HIGH | Define the requirements regarding availability |
BLKCTRL | PAMKEY/ DATA/ DATA2K/ DATA4K/ NO | Define the data format |
BLKSIZE | (STD,n) length | Block size as a multiple of a PAM page Tape files: block size for nonstandard blocks |
CODE | EBCDIC/ ISO7/ ISO7D/ OWN | Tape files: code |
EXC32GB | ALLOWED/ FORBIDDEN | Permit file size > 32 GB for disk files |
FCBTYPE | ISAM/ PAM/ SAM/ BTAM | Access method for the file |
KEYLEN | number | ISAM files: length of the ISAM key |
KEYPOS | number | ISAM files: position of the ISAM key |
LOGLEN | number | ISAM files: length of the logical flag |
NFTYPE | BS2000/ NODE-FILE | File type for file on Net-Storage: |
RECFORM | V/F/U N/M/A | Record format: variable/fixed/undefined Specifies whether printer control characters are to be taken into account |
RECSIZE | length r | Record length for RECFORM=F/V Register which contains the length of the current record for RECFORM=U |
RETPD | days | Retention period for the file |
STOCLAS | Assign a storage class to the file during its creation on an SM pubset | |
VALLEN | number | ISAM files: length of the value flag |
WORKFIL | Specify whether the file is to be created on a volume set for work files or on a volume set with permanent data storage | |
Requesting devices and volumes | ||
DDEVICE | device | ISAM files: device type for data section (if separate from index section) |
DEVICE | device/ WORK | Define device type/request work tape |
DVOLUME | (vsn,...) | ISAM files: private disk for data section (if separate from index section) |
FSEQ | UNK/NEW/number | Tape files: position within a file set |
MOUNT | (number,...) | Mount request for private volumes |
TSET | (name,vsn) | Tape files: define a tape set for extending files or file sets |
TVSN | (vsn,...) | Tape files: temporary volume list for current processing |
VOLSET | Specify the volume set of an SM pubset on which the file is to be created | |
VOLUME | (PRIVATE,n) (vsn,...) | Request private volumes Define volume list |
VSEQ | (L=(number,...)) | Tape files: specify desired file section |
Space management for disk | ||
DSPACE | primary | ISAM files: space management for the data section if the index and data sections are separate (see SPACE, "FILE - Define file attributes / control file processing") |
SPACE | primary (page,number,ABS) | Disk files: allocate or release storage space Absolute allocation |
OPEN mode and processing attributes | ||
BLIM | number | Tape files: maximum number of logical blocks per tape |
BUFOFF | L/length | Tape files: length of buffer offset |
BYPASS | LP/(LP,n)/ | Tape files: bypass label checking |
CHAINIO | number | Tape files: chaining factor |
CHKPT | NO/ ANY/ BLIM/ FEOV | Tape files: automatic checkpointing |
CLOSE | RWD/ INVAL/ REPOS/ DISCON/ LEAVE/ | Tape/disk files: close mode for the file |
CLOSMSG | NO/ YES | SAM files: output of a message after completion of CLOSE processing |
DESTOC | NO/ YES | Tape files: overwrite remaining data |
DISKWR | BY-CLOSE/ IMMEDIATE | Define the point after a write operation by which the data of the file must be in a consistent state |
DUPEKY | YES/ NO | ISAM files: duplicate keys permitted |
IOPERF | HIGH/ STD/ USER-MAX/ VERY-HIGH | Define the performance attribute of the file |
IOUSAGE | RDWRT/ READ/ WRITE | Specify the I/O operations to which the performance attribute (IOPERF) of the file refers |
LABEL | (STD,number) NO NSTD | Tape files: file with standard labels (as per DIN 66029) Tape files without file labels Tape files with nonstandard labels |
LOCKENV | HOST/ XCS | Specify whether the file can be opened for writing from different systems simultaneously |
OPEN | INPUT/ OUTPUT/ EXTEND/ INOUT/ OUTIN/ UPDATE/ SINOUT/ REVERSE | Specify the OPEN mode for the file |
OVERLAP | YES/NO | ISAM files: overlapped processing |
PAD | number | ISAM files: padding in data blocks during sequential creation of the file |
POOLSIZ | number | ISAM files: size of the file-specific ISAM pool |
SECLEV | HIGH/ LOW | Tape files: security level |
SHARUPD | YES/ NO/ WEAK | ISAM files: shared-update processing
PAM files: shared-update processing
|
STREAM | NO/ YES | BTAM tape files: enable I/Os in streaming mode |
TAPEWR | DEVICE-BUFFER/ IMMEDIATE | Files on tape cartridges: |
TPMARK | YES/ NO | Tape files: write tape marks |
TRANS | YES/ NO | Convert non-EBCDIC tape files |
VALPROP | MIN/ MAX | K-ISAM files: control interpretation of value flags |
WRCHK | NO/ YES | Disk files: read-after-write check |
WROUT | NO/ YES | ISAM files: write updated blocks immediately |
Control of macro generation | ||
MF | D / C / L / E | Operand lists |
PREFIX | Prefix for names in operand lists | |
VERSION | 0 / 1 / 2 / 3 | Version setting for the macro |
Format
Operation | Operands |
|
|
Operand default values
The following applies to FILE operands for which no default setting is explicitly described and for which a corresponding FCB operand exists. If the operand is not specified in the FILE macro, this is noted in the TFT entry. The applicable operand value when processing the file is then taken from the specifications in the FCB macro.
If the operand is omitted in the FCB macro as well, the default setting for the FCB macro applies, assuming it is not overwritten by the corresponding value from the catalog entry by OPEN.
Operand descriptions
The forms of the MF operand are described in detail in the appendix, "Macro types". In all macros differentiated by the MF operand (MF=L/E/D/C) the version operand must have the same value.
pathname
Designates the path name of the file(s) or file generation(s)
with: <c-string 1..54: filename 1..54>
“pathname” may not be a file generation group.
If “pathname” is not yet cataloged, a catalog entry is created and space is allocated to the file in accordance with the primary allocation (see the SPACE operand, "FILE - Define file attributes / control file processing").
If a temporary file is specified, it must have been created by the calling task.
The following elements CANNOT be created on a Net-Storage volume:
Files with a PAM key
File generations
Work files
Temporary files
“pathname” means [:catid:][$userid.]filename
catid
Catalog ID;
Default value: the catalog ID assigned to the user ID.
If the catalog ID belongs to a remote system to which an RFA connection exists, the FILE call is sent to the remote system with the parameter list via RFA.
userid
User ID;
Default value: the user ID specified in the SET-LOGON-PARAMETERS or LOGON command.
If the file has not yet been cataloged as shareable or if storage space has been released, a foreign user ID may only be specified if the calling task possesses the TSOS privilege or is a co-owner of the file.
filename
Fully qualified name of a file or file generation. Tape file names may be suffixed with a version number in parentheses.
*DUMMY
The FILE command describes a dummy file. If LINK is also specified, a TFT entry with a volume list is created. If TSET is specified with *DUMMY, a TST entry is also created. All other operands are simply checked for syntax errors, but otherwise ignored; neither devices nor storage space are allocated, and no catalog entry is created.
Dummy file as an input file: when the program attempts to read from the file, EOF processing is initiated.
Dummy file as an output file: data are transferred to the I/O areas of program, but output to a physical volume is suppressed.
AVAIL = HIGH
Only as of VERSION=3 and only relevant for files on pubsets and on Net-Storage volumes:
The file is to have an increased availability and is stored on a corresponding volume set (e.g. DRV).
The specification is rejected in the following cases:
the file already occupies storage space
SPACE is specified with a non-positive primary allocation
WORKFIL=YES is specified
a temporary file is specified
the file ends up on an SM pubset which does not offer increased availability
the file ends up on an SM pubset which does not contain a volume set with increased availability
the file ends up on a private disk
a tape file is specified
BLIM = number
For the creation of tape files with standard labels which are to be processed with the SAM access method:
“number” specifies how many data blocks may be written on one tape;
1 <= number <= 999999.
When this value is reached, a tape swap is initiated (EOV processing). If requested with the CHKPT operand, a checkpoint is written at the end of the tape before EOV processing is started. If the end of the tape is reached before the specified number of blocks has been written, the user receives an error message in the FCB.
The following entries are rejected if BLIM is specified: FCBTYPE=PAM/BTAM/ISAM, LABEL=NO/STD, FSEQ=n with n>1 and FSEQ=UNK/NEW.
BLKCTRL
Only as of VERSION=1:
Determines whether a file with the conventional K format (with PAM keys) or with the new NK format (without PAM keys) is to be processed. BLKCTRL is relevant for the preliminary file format.
For the processing of NK-SAM and NK-PAM files, the same functions as for the corresponding K files are available, with identical user interfaces. For NK-ISAM files, the access method NK-ISAM provides functions over and above those of K-ISAM, e.g. the processing of ISAM files in ISAM pools or the use of secondary keys (see the “Introductory Guide to DMS” [1]). NK-ISAM and K-ISAM processing differ internally, but there are only minor changes at the user interface with regard to the effects of ISAM-specific operands (see the following table).
Operand | BLKCTRL = PAMKEY | BLKCTRL = DATA/DATA2K/DATA4K |
DDEVICE | Separate index and data sections for ISAM files on private disks | Separate index and data sections are not supported, but operands can be specified |
DUPEKY | Records with duplicate keys are given an internal time stamp | |
LOGLEN | Length of the logical flag | This operand is ignored |
POOLLNK | Connects the file to a user ISAM pool | |
OVERLAP | Read operations are overlapped (with IOAREA2) | Any adjacent blocks are likewise read into the ISAM pool |
PAD | Minimum space to be left free in each data block | Maximum space to be left free in each data block |
SHARUPD | Block locks | Record or range locks |
VALLEN | Length of the value flag | This operand is ignored |
VALPROP | The value flag is evaluated | The value flag is ignored |
If the BLKCTRL operand is not specified (neither in the TFT nor in the FCB), the following BLKCTRL value is assigned to the file when it is opened (unless the value from the catalog entry is used):
BLKCTRL = PAMKEY | for files on conventional (CKD) disks |
BLKCTRL = DATA | for SAM or ISAM files on the new (FBA) disks (without PAM key simulation) |
BLKCTRL = NO | for PAM files on the new (FBA) disks (without PAM key simulation) |
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The BLKCTRL value from the reference file catalog entry is ignored.
= PAMKEY
The file has the K format: the block control information is kept in a PAM key outside the data block. Such a K file cannot be created on an NK disk (FBA disk without PAM key simulation) or on a Net-Storage volume.
= NO
This value is only meaningful for PAM files and SAM tape files: it is converted into BLKCTRL=DATA for SAM disk files, and into BLKCTRL=DATA2K or BLKCTRL=DATA4K for ISAM files.
If FCBTYPE=PAM is specified, an NK-PAM file containing no block-specific management information is created.
This file can be created on both K disks as well as NK2 disks, without regard to the selected logical block size (BLKSIZE). If the specified logical block size (BLKSIZE) is a multiple of 4K (with the blocking factor “n” even), the file can also be created on an NK4 disk.
= DATA
The file has NK format: the block control information is kept at the beginning of each logical block (for ISAM files: at the beginning of each 2-Kbyte or 4-Kbyte block).
An NK file may be located on K disks, NK2 disks, and – if the appropriate block size is selected – on NK4 disks as well. When a file is created for the first time (OPEN OUTPUT/OUTIN), an NK2 or NK4 file is created:
For files created with an access method other than ISAM, the format of the file depends on the blocking factor “n” in the BLKSIZE specification for the size of a logical block.
If the blocking factor n is an odd number, an NK2 file is created.
If the blocking factor n is an even number, an NK4 file is created.
When an NK-ISAM file (OPEN OUTPUT/OUTIN) is created, the format of the file is selected on the basis of the disk format. A file that has already been opened can be opened without regard to the block format.
= DATA2K
Only as of VERSION=2, for ISAM files:
Specialization of “DATA” for NK-ISAM files.
Explicitly creates (OPEN OUTPUT/OUTIN) an NK2-ISAM file. When existing files are opened, every file is checked to determine whether an NK2-ISAM file is involved.
The block-specific management information is stored in the first 16 bytes of each data block. This value cannot be used to create a file on an NK4 disk or to open a file located on one.
= DATA4K
Only as of VERSION=2, for ISAM files:
Specialization of “DATA” for NK-ISAM files.
Explicitly creates (OPEN OUTPUT/OUTIN) an NK4-ISAM file. When existing files are opened, every file is checked to determine whether an NK4-ISAM file is involved.
The block-specific management information is stored in the first 16 bytes of each 4-Kbyte block. If a blocking factor “n” is specified, “n” must be an even number, i.e. the logical block size must be a multiple of 4-Kbytes. The file can be created and/or opened on K disks, NK2 disks, and NK4 disks.
BLKSIZE
Defines the length of the logical block (data block), i.e. the length of the unit of data transfer from and to I/O devices. BLKSIZE is relevant for the preliminary file format.
If the BLKSIZE is not specified (neither in the TFT nor FCB), the following BLKSIZE value will be assigned to the file when it is opened (unless the value from the catalog entry is taken):
K/NK2 volumes: BLKSIZE = STD
NK4 volumes: BLKSIZE = (STD,2)
For disk files, there are interactions between this operand and the SPACE and RECSIZE operands, for tape files between this operand and the LABEL operand (see the two tables under BLKSIZE=length on "FILE - Define file attributes / control file processing").
K disk files/tape files with standard blocks: logical blocks may consist of several PAM pages. The system automatically links the PAM pages belonging to one transfer unit.
Tape files with nonstandard blocks: the block format is not the same as that used by PPAM; a logical block is defined as the number of bytes which are read or written in one read or write operation.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:The BLKSIZE value from the reference file catalog entry is ignored.
= STD
Equivalent to (STD,1); see below.
The data is transferred in units of 2048 bytes from/to the devices. The usable data length for the user varies depending on what is specified for BLKCTRL (and/or on the disk type).
= (STD,n)
“STD” is a standard block with a block size of 2048 bytes; “n” is the blocking factor (1 <= n <= 16)
Each logical block consists of “n” PAM blocks (1 PAM block or PAM page = 2048 bytes), so the maximum length of a logical block is 16 PAM pages or 32768 bytes.For NK files “n” defines the length of the logical block as a multiple of 2048 bytes: the length of each such block = n * 2048 bytes.
For NK4 files: the value of “n” must be even; the length of the logical block is a multiple of 4K. In the case of NK-ISAM files, the operand value DATA4K must be specified for the BLKCTRL operand.
For SAM files with SETL processing: up to 255 records may be held in each logical block, since the positioning information is held in only one byte. This restriction is not applicable to a 31-bit FCB= length.
= length
Only for tape files:
specifies the maximum block length in bytes and, at the same time, specifies that the file consists of nonstandard blocks; no PAM keys are written.
When specifying “length”, the user must consider, on the one hand, the settings of BUFOFF and RECFORM and, on the other hand, the settings of FCBTYPE and CHAINIO.
Operand RECFORM | Effects |
RECFORM=F | “length” specifies the block size including the length of any buffer offset (see the BUFOFF operand). |
RECFORM=V/U | “length” specifies the maximum block size including the length of any buffer offset (see the BUFOFF operand). The block size, just like the |
Operand FCBTYPE | Permissible values for “length” |
SAM / BTAM | 1 <= n <= 32768 |
PAM | ------- |
BUFOFF
For tape files with BLKCTRL=DATA or SAM tape files without standard blocking:
defines the buffer offset, i.e. the length of a field which is inserted at the beginning of each data block.
If the BUFOFF is not specified (neither in the TFT nor FCB), the following BUFOFF value will be assigned to the file when it is opened (unless the value from the catalog entry is taken):
for tape files with BLKCTRL=DATA:
for FCBTYPE=SAM: BUFOFF=16
for FCBTYPE=PAM: BUFOFF=12
for SAM tape files without standard blocking
for RECFORM=V: BUFOFF=4
for RECFORM=F/U: BUFOFF=0
As of Version=3 and only relevant if the DATATTR operand is specified:
The BUFOFF value from the reference file catalog entry is ignored.
= L
The BUFOFF value is taken from the HDR2 label of the file. If there is no HDR2 label, or if the field “buffer offset” in the label contains blanks (X'4040'), the same values apply as when the BUFOFF specification is omitted (neither TFT not FCB).
= length
Specifies the length of the buffer offset.
For SAM files with RECFORM=V: 0 <= length <= 4; if BUFOFF=4 applies, this field contains the length of the current block. For files with BLKCTRL=DATA, this field contains the block control field.
BYPASS
For input files on tape:
Given the appropriate authorization for the user in the user catalog, the user can bypass the label checking routines and specify how the tape is to be positioned. DMS checks that the correct tape is mounted and activates any user routines for label handling in the normal manner. The positioning specification is evaluated only if no OPEN exit is defined.
In addition to label checking, code checking is also bypassed. If the user specifies CODE=OWN, he/she must provide the appropriate code tables.
BYPASS permits processing of tapes created under other operating systems (such as BS1000) or of tapes whose structure and label formats are not known to the system. The BYPASS specification is valid only during file processing; it is not included in the catalog entry for the file.
If specified together with BYPASS, the FSEQ and SECLEV operands are not evaluated.
= LP
No label handling takes place. The header labels are neither checked nor read. The tape position is not changed.
= (LP,n)
No label handling takes place. When the file is opened, the tape is positioned to the nthtape mark, counting from the beginning of the tape. 0 <= n <= 32767.
(LP,0): position to the beginning of the tape.
= (LP,+n)
No label handling takes place. When the file is opened, the tape is positioned forwards by n tape marks from its current position. 0 <= n <= 127.
(LP,+0): the tape is not repositioned.
= (LP,-n)
No label handling takes place. When the file is opened, the tape is positioned backwards by n tape marks from its current position. 0 <= n <= 127.
(LP,-0): the tape is not repositioned.
CHAINIO = number
For BTAM files with chained I/O:
1 <= number <= 16;
“number” is the chaining factor which defines the length of the transport/transfer unit for input and output. “number” is a number of blocks, which means that the length of the transport unit is “number” * BLKSIZE.
Although the value from CHAINIO=number, multiplied by the block size, can be overwritten by specifications in the program (BTAM macro) when processing BTAM files, CHAINIO must still be specified in the FILE macro if chained I/O is to be used.
CHKPT
For tape files only:
controls if and when a checkpoint is to be written automatically to the end of the tape, or how file processing is to continue after a restart (RESTART command).
Default value: | CHKPT=(NO,ACTIVE) |
= (NO,...)
No automatic checkpoints are written, unless specified otherwise in the FCB of the program.
= (BLIM,...)
When the block limit specified via the BLIM operand is reached, a checkpoint is written automatically; the operand BLIM must be specified.
= (FEOV,...)
A checkpoint is written automatically each time the FEOV macro is called.
= (ANY,...)
A checkpoint is automatically written when the BLIM limit is reached or when the FEOV macro is called. The operand BLIM must be specified.
= (...,DUMMY)
“pathname” is treated like a DUMMY file during a restart by means of the RESTART-PROGRAM command.
= (...,ACTIVE)
The file “pathname” is processed further during a restart by means of the RESTART-PROGRAM command.
CLOSE
Only as of VERSION=2:
Specifies the CLOSE mode for the file. This value may be overwritten by the CLOSE macro when the file is being closed.
Default setting: | The CLOSE value is taken from the CLOSE macro. |
For more information on CLOSE processing, see also the “Introductory Guide to DMS” [1].
= RWD
For tape processing:
The tape is rewound to the start.
= REPOS
For tape processing:
The tape is positioned to the beginning of the current file section, depending on the LABEL specification.
= DISCON
For tape processing:
The tape is rewound to the start and unloaded/released.
= LEAVE
For tape processing:
Positions the tape to the logical end-of-file, depending on the LABEL specification.
= INVAL
The cached file blocks are invalidated, i.e. declared invalid, and not written back to disk (to be borne in mind for shared-update processing)
= KEEP-DATA-IN-CACHE
Only as of VERSION=3:
Blocks from the file that are in the cache are not written back to the disk, but remain flagged as valid.
CLOSMSG
Only as of VERSION=1:
For files to be processed sequentially (SAM), the user can specify that a message is to be issued (to SYSOUT) after completion of CLOSE processing. If the CLOSMSG operand is not specified (neither the TFT nor the FCB), the following CLOSMSG value is assigned to the file when it is opened:
Disk: CLOSMSG = NO
Tape: CLOSMSG = YES
= NO
The completion message is suppressed.
= YES
The completion message is issued.
CODE
For tape processing:
Specifies, for SAM or BTAM files, whether code translation tables are to be used during input and output and, if so, which tables.
If the CODE operand is not specified (neither the TFT nor the FCB), the following CODE value is assigned to the file when it is opened:
CODE = EBCDIC
For CODE=EBCDIC and CODE=ISO7 the German and international character sets are encoded in the same manner.
For CODE=ISO7/OWN and FCBTYPE=SAM, the following should be noted:
the block size must be specified by BLKSIZE=length, so that no PAM keys are written;
for outputs in locate mode with variable-length records (RECFORM=V), the contents of the record length field change.
= *BY-PROG
Only as of VERSION=3 and only relevant if the DATATTR operand is specified:
The CODE value from the reference file catalog entry is ignored.
= EBCDIC
No code conversion during processing is necessary.
= ISO7
The tape file is written in ISO 7-bit code, which means that EBCDIC code is converted to ISO 7-bit code during output and ISO 7-bit code is converted to EBCDIC code during input. The international ISO table is used.
= ISO7D
Only as of VERSION=3:
The tape file is written in ISO 7-bit code, which means that EBCDIC code is converted to ISO 7-bit code during output and ISO 7-bit code is converted to EBCDIC code during input. The German ISO table is used.
= OWN
Conversion is carried out with code tables provided by the user. The addresses of these tables must be specified in an FCB macro (see the TRTADR and TRTADW operands, "FCB - Define file control block"). At the same time, label processing must be switched off via the LABEL operand (LABEL=NO) or carried out in the user program (LABEL=NSTD).
DATATTR = (*FROM-FILE,<c-string: filename 1..54>)
Only as of VERSION=3:
The following values are transferred to the TFT entry when this is created, from the catalog entry of the reference file specified here. Explicitly specified values have precedence.
BLKCTRL, BLKSIZE, BUFOFF, CODE, FCBTYPE, KEYLEN, KEYPOS, LABEL, LOGLEN, RECFORM, RECSIZE, VALLEN, VALPROP
The reference file must be cataloged in the pubset as the file to which the FILE call refers. The caller must have the right to read the reference file catalog entry (using FSTAT or SHOW-FILE-ATTRIBUTES).
The values for BLKCTRL and BLKSIZE contained in the reference file catalog entry are taken into account when forming the preliminary file format.
If the value *BY-PROG is specified for the above operand, transfer of the corresponding value from the reference file catalog entry is suppressed and no value is transferred to the TFT entry.
Example
A reference file is specified whose catalog entry for BLKCTRL contains the valuePAMKEY. The following then applies:
BLKCTRL value specified in FILE call | BLKCTRL value in TFT entry |
none | PAMKEY |
*BY-PROG | none |
DATA | DATA |
DDEVICE = <name 1..8>
For ISAM files with index and data sections separated:
DDEVICE designates the disk type for the data section (that for the index section is specified via DEVICE); permissible entries for “device” can be found in the device table in in „System installation“ manual [16]). The new device types introduced with BS2000 V9.5 are only supported as of VERSION=1. DDEVICE must be specified if no storage space has yet been reserved for the file. DVOLUME and DSPACE must also be specified if DDEVICE is specified.
If at least one volume serial number is specified with DVOLUME, every specification of a disk device type which is known to the system is handled like the STDDISK specification.
NK-ISAM does not support index/data separation, but DDEVICE may still be specified (compatibility with K-ISAM).
DESTOC
For tape processing as of VERSION=1:
the user can specify whether any data on the remainder of the tape is to be deleted by overwriting after completion of EOF/EOV processing.
DESTOC is effective only if a TFT entry is created for “pathname” using the LINK operand.
If the DESTOC operand is not specified, the DESTROY specification is taken from the catalog entry when the file is opened.
DESTOC has the same function as the operand DESTROY in the CATAL macro, but the DESTOC specification overrides the DESTROY value in the catalog entry. The value specified for DESTOC is not placed in the catalog entry.
= NO
Any data on the remainder of the tape is not erased.
= YES
After the EOF/EOV labels have been written, any data on the remainder of the tape is erased.
DEVICE
defines the disk device type or tape type.
When VOLUME specifies a private disk which is not contained in the MAREN catalog, the DEVICE operand must be specified.
Defaults
The following applies if the file has no storage space assigned before the FILE call and is allocated storage space by the FILE call:
If DEVICE=STDDISK is specified and neither VOLUME nor NFTYPE is not, the file will be created on public disks (and also not on a Net-Storage volume in future expansions).
If DEVICE=NETSTOR (the volume type for Net-Storage volumes) is specified and VOLUME is not, the file will be created on a Net-Storage volume.
If neither DEVICE nor VOLUME is specified, the following applies:
If NFTYPE is not specified, the file is created on public disk.
When NFTYPE is specified, the file of the specified file type is created on an arbitrary Net-Storage volume provided one exists.
Future extensions can enable a different behavior here.
= <name 1..8>
Specifies the device type (for disks) or the volume type for Net-Storage volumes and tapes). The possible entries for disk devices are shown in the “System installation” manual [16] (Device type column); permissible values for tape devices are included in the volume type table (see the “Commands” manual [3]).
DEVICE=NETSTOR (the volume type for Net-Storage volumes) specifies a Net-Storage volume.
DEVICE=TAPE cannot be used to request magnetic tape cartridges.
If a tape type is specified for DEVICE when creating a file, but no specification is made for VOLUME, a free tape (SCRATCH-TAPE) with standard labels is requested during OPEN processing and assigned by the operator. A tape is considered free from the viewpoint of DMS if it has not been written as yet or if the retention period of the first file on it has expired, and write access is enabled.
If at least one volume serial number is specified with VOLUME, every specification of a disk device type which is known to the system is handled like the STDDISK specification.
= WORK
Only for tape processing:
causes a work tape with standard labels to be requested during OPEN processing.Work tapes are not assigned to any owner; the corresponding field in the VOL1 label always contains blanks (X'40'). Work tapes should be requested only when they are required during processing and are not to be archived. File protection is not possible on work tapes. Work tapes are allocated by the operator when requested; and values specified for the VOLUME operand are ignored. The operands TSET and STATE=FOREIGN must not be specified together with DEVICE=WORK.
DEVICE=WORK should not be specified for multivolume files, since any available work tape is automatically assigned.
Magnetic tape cartridges cannot be requested as work tapes.
DISKWR
Only as of VERSION=3 and only relevant for files on pubsets or Net-Storage volumes:
Specifies the time after a write operation within which the file data must be in a consistent state. The entry is taken into the catalog entry for files on pubsets or Net-Storage volumes. The entry is taken into account when selecting the volume set for files on SM pubsets.
If DISKWR is not specified and the file has no catalog entry, the value IMMEDIATE is assumed for a permanent file and BY-CLOSE for a temporary file. If DISKWR is not specified and the file has a catalog entry, the value for DISKWR in the catalog entry is used.
The entry is rejected in the following cases:
the file already occupies storage space
SPACE is specified with a non-positive primary allocation
= IMMEDIATE
The file data must be in a consistent state immediately after a write operation.
= BY-CLOSE
The file data must be in a consistent state after the file is closed. This allows the file to be processed via a volatile cache.
DSPACE
Used with DDEVICE/DVOLUME for the data section of ISAM files with index and data separation:
DSPACE defines the space allocations for the data section of an ISAM file. The rules for primary and secondary allocation and for absolute allocation are the same as for the SPACE operand, but the entries refer to the volume specified in the DVOLUME operand (see also the DDEVICE and DVOLUME operands and “Index and data separation”, in the “Introductory Guide to DMS” [1]). NK-ISAM does not support separate data and index sections, but DSPACE may still be specified (compatibility with K-ISAM).
= <integer 0..2147483647>
Primary allocation, effective immediately.
= (<integer 0..2147483647>,<integer 0..32767>)
The primary allocation is effective immediately; the secondary allocation value is transferred to the catalog entry; 0 <= secondary <= 32767.
= (<integer 0..2147483647>,<integer 0..2147483647>,ABS)
ABS: absolute allocation;
The number of the PAM page at which the absolute allocation begins is specified followed by the number of PAM pages to be reserved.
DUPEKY
For ISAM files:
Specifies whether or not there may be more than one record with the same primary key value (duplicate keys).
If no value is specified in the FILE macro or FCB, the default value of the FCB macro takes effect on opening the file.
= NO
The file must not contain more than one record with the same primary key value.
= YES
If several records have the same primary key value, they do not overwrite each other, but are written sequentially in the order in which they are created. DUPEKY=YES is of significance only if the ISAM file is created sequentially by means of the PUT macro or extended non-sequentially by means of the STORE macro.
The INSRT macro cannot be used to write records with identical primary keys.For DUPEKY=YES, see also "FCB - Define file control block".
DVOLUME
Used together with DDEVICE for K-ISAM files with separate index and data sections on a private volume:
DVOLUME specifies the volume serial number (“vsn” of the volume on which the data section of the ISAM file is to be stored. The VOLUME operand must be specified for the index section. The explanation of the DDEVICE operand applies analogously. NK-ISAM does not support separate data and index sections, but DVOLUME may still be specified (compatibility with K-ISAM). Separate data and index sections are not possible for files on a Net-Storage volume.
= <@addr>
Only as of VERSION=2:
addr is a symbolic address in the program at which a DVOLUME list has been created using the macro FILELST DVOLUME=...
The character “@” is part of the operand value and must be specified.
= PRIVATE
Issues a MOUNT message for a private disk on the console.
= (PRIVATE,<integer 1..9>)
Issues a MOUNT message for the required number of private disks on the console.
= list-poss(255): <name 1..6>
The private disks specified with their VSN are required for the data part of the ISAM file.
EXC32GB
Only for disk files; not for non-PAMKEY files:
The EXC32GB operand determines whether or not the file size may grow beyond 32 GB during data processing (see "Files larger than 32 GB"). The operand is entered in the TFT (Task File Table) and is not evaluated until the file is opened with OPEN.
EXC32GB has no influence on storage space allocations in the event of FILE calls.
= FORBIDDEN
The file size may not exceed 32 GB.
= ALLOWED
The file size may exceed 32 GB.
FCBTYPE
Specifies the access method to be used for file processing.
= *BY-PROG
Only as of VERSION=3 and only relevant if the DATATTR operand is specified:
The FCBTYPE value from the reference file catalog entry is ignored.
= ISAM
“pathname” is an ISAM file. Depending on the BLKCTRL operand, it is processed as an NK-ISAM file (BLKCTRL=DATA) or as a K-ISAM file (BLKCTRL=PAMKEY). The access method ISAM is described in the “Introductory Guide to DMS” [1].
ISAM-specific operands: DUPEKY, KEYLEN, KEYPOS, LOGLEN, POOLLNK, VALLEN, WROUT and DDEVICE, DSPACE, DVOLUME and VALPROP.
= BTAM
“pathname” is a tape file which is to be processed with the access method BTAM. The access method BTAM is described in the “Introductory Guide to DMS” [1].
BTAM-specific operands: CHAINIO, OPEN=SINOUT, STREAM
= PAM
“pathname” is a PAM file and is processed with the access method UPAM The access method UPAM is described in the “Introductory Guide to DMS” [1].
PAM files could be stored on disk or tape.
= SAM
“pathname” is a SAM file on disk or tape. SAM files are generally processed sequentially with the access methods SAM or UPAM. The access method SAM is described in the “Introductory Guide to DMS” [1].
SAM-specific operands: CLOSMSG, OPEN=UPDATE
FSEQ
For tape files which belong to a file set:
specifies the (sequence) number of a file within the file set. If, for example, several files with the same name are stored on one tape, access to a specific file is controlled via FSEQ. This also applies to MF/MV sets.
If no FSEQ value exists in the TFT entry or the FCB at the time the file is opened, FSEQ=1 is entered for files that have not yet been opened. In the case of files that have already been opened, the FSEQ value is taken from the catalog entry.
A catalog entry for the file must exist if FSEQ is specified as a null operand. If a file sequence number is entered there, this is transferred to the TFT entry. Otherwise, no file sequence number is entered in the catalog entry and the null operand is entered in the TFT entry.
= UNK
If the file already has a catalog entry containing a file sequence number, this is transferred to the TFT entry. Otherwise, no file sequence number is entered in the catalog entry and UNK is entered in the TFT entry. This means that when opening a foreign tape file with standard labels, the tape is searched for the file and positioned accordingly.
= NEW
Only permitted if no creation date is entered in the catalog entry:
The value NEW is entered in the TFT entry but not in the catalog entry. If a file sequence number is entered in the catalog entry, it is deleted. This means that a non-existent (NEW) tape file with standard labels is written after the current end of the file set and the file sequence number is incremented by one when the file is opened.
= <integer 0..9999>
If a catalog entry with creation date exists for the file, the FSEQ entry must match the file sequence number in the catalog entry. Otherwise (particularly for foreign files), the number is entered in both the catalog and TFT entries as a file sequence number. The tape is positioned according to the file sequence number when the file is opened.
Both FSEQ=0 and FSEQ=1 designate the first file of the file set.
IOPERF
Only as of VERSION=2 and only relevant for files/file generations on public volumes or Net-Storage volumes:
Specifies the performance attribute of the file. This defines the desired priority level for the I/O operations specified in the IOUSAGE operand. The highest permitted performance attribute is defined in the catalog entry (see the output of the SHOW-USER-ATTRIBUTES command).
When the file is being cataloged, the specification with the highest permissible performance attribute is compared and is transferred to the catalog entry, or STD is entered if IOPERF is not specified.
If the file is cataloged, the corresponding specifications in the catalog entry are not changed. If a file link name is specified in the LINK operand, the value is transferred to the TFT entry if IOPERF was specified.
When a new file is created on an SM pubset, the performance attribute is taken into account when selecting the volume set (e.g. selection of a volume set to which a cache is assigned).
= STD
The file is not processed via a cache.
= VERY-HIGH
If possible, a cache should be used when processing the file, and the whole file should be permanently maintained in the cache (highest performance priority).
= HIGH
The file should be processed via a cache if possible.
= USER-MAX
The file is given the highest I/O attribute that is entered for the user in the user catalog.
IOUSAGE
Only as of VERSION=2 and only relevant for files/file generations on public volumes or Net-Storage volumes:
Specifies the I/O operations to which the performance attributes (IOPERF) of the file apply. When the file is being cataloged, the specification is transferred to the catalog entry, or RDWRT is entered if IOUSAGE is not specified.
If the file is already cataloged, the corresponding specifications in the catalog entry are not changed.
If a file link name is specified in the LINK operand, the value is transferred to the TFT entry if IOUSAGE was specified.
When a new file is created on an SM pubset, the IOUSAGE attribute is taken into account when selecting the volume set (e.g. selection of a volume set to which a read cache is assigned).
= RDWRT
The performance attribute applies to read and write operations.
= WRITE
The performance attribute applies to write operations only.
= READ
The performance attribute applies to read operations only.
KEYLEN = length
For ISAM files:
specifies the length of the ISAM key.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The KEYLEN value from the reference file catalog entry is ignored.
= <integer 1..255>
Length of the ISAM key in bytes.
KEYPOS = number
For ISAM files:
specifies the position of the primary key in the record. In variable-length records, 4 bytes for the record length and control fields must be taken into account. The primary key may be anywhere in the record, but must be in the same position in each record of one file.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:The KEYPOS value from the reference file catalog entry is ignored.
= <integer 1..255>
Byte position of the primary key.
LABEL
For tape files:
Specifies the label attributes for files on magnetic tape or magnetic tape cartridge; the SECLEV operand determines how the labels are processed.
For existing tape files, the label standard version in the VOL1 label always applies. The LABEL operand is evaluated for output files (OPEN OUTIN/OUTPUT). If the tape already contains files or file sections, the standard identifier in the VOL1 label is set or updated as specified in the LABEL operand.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The LABEL value from the reference file catalog entry is ignored.
= STD
File and volume already have or are to receive standard labels in accordance with DIN 66029, exchange level 1.
= (STD,<integer 0..3>)
File and volume already have or are to receive standard labels in accordance with the specified DIN 66029 exchange level; exchange level 4 is in preparation.
For specification and effects of the operand, see also the table “Effects of the LABEL operand” in chapter "FCB - Define file control block".
= NO
Labels are neither read nor written (no file label processing). If the tape has standard labels, the system processes the volume labels and checks the access authorization.
= NSTD
The tape file already has or is to receive nonstandard labels and file label processing is performed in the user program. If the volume has standard labels, the system processes them and checks the access authorization.
LINK = <name 1..8>
A TFT entry is to be created for this file link name (“name”). The other operands are then evaluated and their values are placed in this TFT entry (apart from SPACE, DSPACE, AVAIL, WORKFIL, VOLSET, STOCLAS and DISKWR). Volumes are requested from the volume list if necessary.
If the TFT already contains an entry with the same name, it is first implicitly released and then set up again with the current values in the FILE macro. The old TFT entry must not be in the active state. If the old TFT entry had been locked by means of a LOCK-FILE-LINK command, the new entry is also locked. Furthermore, the old volume and device reservations are cleared, but tape devices remain available to the job.
The program and the file are linked together via the file link name and the TFT.
The TFT entry is created in the task of the caller if this is not an RFA case. If the catalog ID in the path name belongs to a remote system to which an RFA connection exists, the TFT entry is created in the remote task and another one is created in the task of the caller. The TFT entry created in the task of the caller must not contain all the information in the remote task TFT entry, e.g.:
user ID in the file path name
information that cannot be specified via the FILE macro operands
information on the TFT entry volume table
entries for IOPERF, IOUSAGE, DEVICE, DDEVICE, FSEQ, MOUNT
values transferred with the DATATTR operand from the reference file catalog entry
If the file link name is to be accessed via the command interface, it must correspond to the data type <structured_name 1..8> (see the “Commands” manual [3]).
Note
If the LINK operand is not specified, no TFT entry is created.
Most of the operands of the FILE macro are evaluated only together with a TFT entry. Exceptions to this are the operands whose values are transferred to the catalog entry or operands which control FILE processing such as:
IOPERF, IOUSAGE, DEVICE, VOLUME, SPACE, DDEVICE, DVOLUME, DSPACE, FSEQ (in part) MOUNT, and STATE=FOREIGN.
LOCKENV
Only as of VERSION=3:
Defines whether the file can be opened for writing by multiple systems during processing, dependent on the open mode and SHARUPD value.
= HOST
The file cannot be opened for writing by multiple systems during processing.
= XCS
The file can be opened for writing from different systems during processing by means of SHARUPD=YES if both systems belong to the same XCS network.
LOGLEN = <integer 0..255>
For ISAM files:
specifies the length (in bytes) of the logical flag in the ISAM index; the maximum length is determined by the length of the ISAM key and the length of any existing value flag (see the description of the VALLEN operand, "FILE - Define file attributes / control file processing"), since the entire ISAM index must not be longer than 255 bytes.
The following rule thus applies:
length <= 255 - KEYLEN - VALLEN
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
In the ISAM index, the ISAM key may be followed by a logical flag in which selection criteria are defined bit-by-bit and encoded in binary code. In K-ISAM files, all logical flags of a block are evaluated and the result is placed in the next-higher index entry. NK-ISAM supports logical flags only compatibly, but does not place the flags in the index entry. Any LOGLEN specification is ignored.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The LOGLEN value from the reference file catalog entry is ignored.
MF
The forms of the MF operand are described in detail in the appendix ("Macro types"). The version operand must have the same value for all macro calls that are distinguished by the MF operand (MF=L/E/D/C/S).
MF=S can only be used for VERSION=0.
Default: | MF=S for VERSION=0. |
MOUNT
Specifies which volume is requested from the volume list (see VOLUME operand) for FILE processing.
The interactions with the VSEQ operand should be borne in mind:
VSEQ: MOUNT values must be greater than or equal to the VSEQ value (exception: MOUNT=0). If VSEQ=n, the MOUNT list must begin with “n”
(MOUNT=(n[,n+1][,n+2][,...); if VSEQ=(L=(n1, n2,...)), the MOUNT list must consist of the first k elements of the VSEQ list (MOUNT=(n1, n2,...,nk)).
If the VSEQ operand is not specified, the MOUNT list must begin with “1” (MOUNT = 1, 2, ..., k)).
Exception: MOUNT=0.
The following applies when requesting public disks:
No disks are requested if LINK is specified.
No disks are requested if the file is migrated.
No disks are requested if MOUNT=0 is specified.
All MOUNT specifications apart from MOUNT=0 are rejected if LINK is specified.
All disks are removed from the volume list if LINK is specified without MOUNT and the file is not migrated.
The following applies when requesting private disks:
The specification MOUNT=0 is ignored if at least one of the operands SPACE, VOLUME, DSPACE, DVOLUME or REUSE (using the oldest generation volumes when creating a new generation) is specified.
No private disk is requested if MOUNT=0 is effective.
If MOUNT=0 is not effective and LINK is not specified, the first private disks are requested with extent and, if necessary, any additional private disks required for the storage allocation.
All disks from the volume list are requested if LINK is specified and no MOUNT specification is effective.
The first k disks from the volume list are requested if LINK is specified and k non-zero numbers are specified in MOUNT.
The following applies when requesting Net-Storage volumes:
When MOUNT=0 but neither SPACE nor VOLUME is specified and the file is already on a Net-Storage volume before the FILE call, no Net-Storage volume is requested.
In all other cases the Net-Storage volume is requested on which the file resides or is created.
The following applies when requesting tapes:
No tapes are requested if DEVICE=WORK is specified.
No tapes are requested if MOUNT=0 or neither LINK nor MOUNT is specified.
Tapes are requested according to the MOUNT list if MOUNT is specified not equal to zero.
If LINK is specified without MOUNT, just one tape is requested from the volume list: if
VSEC=n is specified, the nth tape, if VSEQ=(L=(n1, n2,...)) the n1th tape and if VSEQ is not specified, the first tape.
Every number n>0 in the MOUNT list refers to the nth tape in the volume list.
= 0
For disk files:
The volume is requested only at the time of the OPEN, provided that neither VOLUME/DVOLUME nor SPACE/DSPACE has been specified.
For tape files:
The tape is not requested until the OPEN.
= @addr
Only as of VERSION=2:
addr is a symbolic address in the program at which a MOUNT list was stored using FILELST MOUNT=...
The “@” character is part of the operand value and must be specified.
= list-poss(255): <integer 1..255>
Every number specified here refers to the nth volume in the volume list.
NFTYPE
Only as of VERSION=3 and only relevant for files on Net-Storage volumes:
Specifies the file type for the Net-Storage file to be created.
If this specification contradicts the specifications in the DEVICE and VOLUME operands (e.g. specification of a private disk), the macro is aborted with an error. If the DEVICE and VOLUME operands are not specified, the file is created with the specified file type on an arbitrary Net-Storage volume (if available).
= BS2000
The file is created on Net-Storage as a BS2000 file.
= NODE-FILE
The file is created on Net-Storage as a node file.
OPEN
Specifies the OPEN mode for the file. This setting may be overwritten by the OPEN mode specified in the OPEN macro.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
For the possible specifications for the various access methods, see also table “OPEN modes with the FCB macro” in chapter FCB - Define file control block. The various OPEN modes are also described in detail in the descriptions of the access methods.
= INPUT
“pathname” is an input file, i.e. it must exist.
= EXTEND
An existing file is extended, i.e. further data blocks are added to the end of the file or the file is overwritten from a certain position onwards; only sequential write operations are permitted. Labels are created for tape files dependent on the LABEL specification.
= INOUT
An existing file is opened for non-sequential processing; write and read operations are permitted. After OPEN is completed with tape processing, the tape is positioned to the start of tape and no further labels are written.
= OUTIN
A file is created or, if it already exists, overwritten from the beginning. Both read and write operations are permitted (non-sequential). Labels are written for tape files.
= OUTPUT
A file is created or, if it already exists, overwritten from the beginning. Labels are written for tape files.
= REVERSE
The file “pathname” must already exist and is opened as an input file for sequential reading from end-of-file -> beginning-of-file. Disk files file must not extend over several volumes. For tape files, no automatic spool swap is possible. A single section of the file can be processed (the tape concerned is to be selected using VSEQ if necessary). Tape files are positioned to the end of the file section after OPEN processing.
= SINOUT
Only for BTAM tape files:
The file must exist and the tape must not be positioned to the beginning of tape. Data blocks can be read or written. In contrast to INOUT, the tape is not positioned.
= UPDATE
Only for SAM disk files:
The records of the file can be updated by retrieving them with GET and writing them back with PUTX (this is only possible in locate mode).
OVERLAP
For ISAM files:
If this is specified and a second I/O area is defined in the program (IOAREA2 in the FCB), read operations (GET/GETR) can be executed in overlapped mode.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
For NK-ISAM, “overlapped processing” means that neighboring blocks are also read into the ISAM pool. OVERLAP=YES should be used only when reading is predominantly sequential.
= YES
Read operations are executed in overlapped mode.
= NO
Read operations are not executed in overlapped mode.
PAD = <integer 0..99>
For ISAM files created sequentially (using the ISAM macro PUT):
the “padding factor” PAD specifies how much free space is to be left in each data block for subsequent extension of the file (specified as a percentage of the block size defined by means of BLKSIZE). PAD thus has an effect on the block splitting rate when a file is extended non-sequentially.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
The PAD specification has different effects for NK-ISAM and K-ISAM. For NK-ISAM, the block is filled at least up to the PAD limit; for K-ISAM, it is not filled above the PAD limit.
POOLLNK = <name 1..8>
Only as of VERSION=1 and for ISAM files processed in user ISAM pools (NK-ISAM):
“name” is the “pool link name” (up to 8 characters long) which is entered in the TFT. This pool link name must be assigned by means of ADDPLNK to an ISAM pool created using the CREPOOL macro. This name is passed to NK-ISAM at OPEN time; an I/O buffer for the file is created in the appropriate ISAM pool.
Valid character set for “name”: letters, digits, and special characters (in accordance with the rules for file names).
If the pool link name is to be accessed via the command interface, it must correspond to the data type <structured_name 1..8> (see the “Commands” manual [3]).
POOLSIZ = <integer 128..1048576>
Size of the file-specific ISAM pool in units of 2048 bytes.
The specification does not refer to the ISAM pool referenced with POOLLNK.
PREFIX
Only evaluated in conjunction with MF=C or D; this defines the first character of field names and equates that are generated in the data area during macro expansion.
= I
The prefix with which field names and equates generated by the assembler begin.
= *
No prefix is generated.
= <name 1..1>
Prefix with which the generated field names and equates are to begin.
RECFORM
Specifies the record format of the file designated by “pathname” and also specifies which control characters are to be interpreted if the file is sent to a printer.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
The record format is evaluated for the access methods SAM and ISAM. UPAM processes files only on a block basis and any RECFORM specification is ignored. BTAM is also a block-oriented access method, but accepts a RECFORM specification. The record formats are described in detail in the section on access methods in the “Introductory Guide to DMS” [1]. For the relationship between the RECFORM and RECSIZE specifications, see the RECSIZE operand. For information on evaluation of the print control characters, refer to the PRINT-DOCUMENT command (LINE-SPACING operand) in the manuals “Commands” [3] and “SPOOL” [4].
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The RECFORM value from the reference file catalog entry is ignored.
= V
“pathname” consists of variable-length records, which means that the user must remember, when programming, that each record is preceded by a 4-byte field whose first two bytes contain the record length in binary form. Bytes 3 and 4 of this field are used by the system. For input files, the record length field is set by the system; for output files, this must be done by the user. The value specified for RECSIZE is the maximum permissible record length. For BTAM files, the specification RECFORM=V is treated like RECFORM=U.
= F
“pathname” consists of fixed-length records, i.e. the user does not need to worry about any record length and control fields. All records in the file have the same length, which is defined via the RECSIZE operand (see "FILE - Define file attributes / control file processing").
= U
“pathname” consists of records with “undefined” length. Each data block contains only one record, whose length is passed in a register. The system sets this register for input and the user must set it for output (see the BLKSIZE operand, "FILE - Define file attributes / control file processing").
RECFORM=U converts the specification LABEL=(STD,3) into (STD,2).
RECFORM=U is not permitted for ISAM files.
= (...,N)
“pathname” is not a print file and therefore contains no printer control characters. It should not be printed with control character evaluation.
= (...,M)
The first data byte in each record is interpreted as a control character in EBCDIC code. The file can be printed with the command PRINT-DOCUMENT ...,LINE-SPACING=*BY-EBCDIC-CONTROL. For ISAM files, the ISAM index is taken into account.
= (...,A)
The first data byte in each record is interpreted as an ASA control character. The file can be printed with the command PRINT-DOCUMENT ...,LINE-SPACING=*BY-ASA-CONTROL.
RECSIZE
Specifies the record length, depending on the specification in the RECFORM operand.If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The RECSIZE value from the reference file catalog entry is ignored.
= <integer 0..32768>
For RECFORM=V: the specification for RECSIZE is ignored, except in the following case: if an ISAM file is read in move mode, and if the value specified for RECSIZE is less than the length of the record which is read, only the length specified for RECSIZE is actually read and error handling (DMS0AAD) is initiated.
For RECFORM=F: the record length in bytes; all records in the file are the same length.
= <reg 2..12>
For RECFORM=U: the RECSIZE operand must specify a general-purpose register (2 <= reg <= 12) which contains the current record length for input and output. The system sets this register for input and the user must set it for output.
RETPD = <integer 0..32767>
By means of “RETPD”, the user can define a retention period during which no write access (update, delete) is possible.
If no value is specified in either the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
Once the retention period has elapsed, the file is not automatically erased; write access is simply permitted again.
The retention period can also be controlled via the CATAL macro:
any RETPD specification in CATAL is immediately placed in the catalog entry. For tape files, the CATAL macro can be used only before the file is opened for the first time.
RETPD is ignored for temporary files.
SECLEV
For tape files:
the operand SECLEV (security level) refers to the TPIGNORE entry in the JOIN file. A SECLEV specification is ignored in interactive mode. In batch mode, users with the appropriate authorization can use the SECLEV operand to specify whether error messages are to be suppressed and/or whether additional label checking is to be executed.
= HIGH
In batch mode, error messages are sent to the console. If the job is running under a user ID with TPIGNORE=YES in its JOIN entry, the operator can ignore the error messages.
= LOW
Permissible only for the tape/file owner if TPIGNORE=YES is defined in the user catalog entry: certain error messages are suppressed in batch mode.
= (...,OPR)
The entry OPR (= overwrite protection) causes the system to execute additional label checking:
if a file is written on a tape behind an existing file, the labels of the preceding file are checked;
the expiration date of the new file must not be greater than that of the preceding file.
SHARUPD
For ISAM or UPAM disk files:
specifies whether several jobs may concurrently open the file with an OPEN mode other than OPEN INPUT.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= NO
As soon as the file is opened by a job with OPEN≠INPUT, it is locked for all other jobs. Concurrent access to the file by several jobs is possible only if the file is used as an input file by all of these jobs, i.e. it is opened with OPEN INPUT. If the file has been opened with OPEN INPUT, any attempt to open it with another OPEN mode is rejected.
= YES
Only for ISAM and PAM files:
the file can be processed concurrently by several jobs, provided SHARUPD=YES is specified in all of these jobs. With UPAM, the user can protect data blocks from access by other jobs as long as he/she is processing them. For ISAM, any locks that are necessary are set automatically by the system: with NK-ISAM, as record key locks; with K-ISAM, as block locks. With NK-ISAM, files which are opened for shared-update processing must be processed in host-specific ISAM pools. SHARUPD=YES for ISAM files simultaneously activates the WROUT function (see operand WROUT, "FILE - Define file attributes / control file processing").
= WEAK
Only as of VERSION=2, for UPAM processing:
guarantees write protection but no read protection. Only one job can open the file for an update, but other jobs may use it as an input file at the same time. The user must make allowances in the program for the fact that the contents of the file may change during the period in which it is used as an input file.
SPACE
Only for disk files:
Controls, via the primary, secondary or absolute allocation, the storage space reserved for the file “pathname”. The SPACE operand is always evaluated, even if the LINK operand is not specified in the current FILE macro. Primary, secondary and absolute allocations are described in detail in the section “Requesting storage space” in the “Introductory Guide to DMS” [1].
Default value: | The following applies if SPACE is not specified:
|
A FILE macro with a SPACE operand is rejected for files which are open or reserved exclusively for another task. The protection attributes of a file or file generation group are also taken into account.
If the user requests more space on the pubset than is assigned to him in the user catalog entry, the FILE macro is rejected.
If the user is authorized to override the allocated storage space, the system informs the user with a message.
In order to minimize the management overhead for the system and storage space utilization, the following should be noted when making primary and secondary allocations:
the primary allocation should match the estimated size of the file to be created;
the secondary allocation should be sufficient to cover the anticipated expansion of the file to be created
When a file with BLKSIZE=(STD,n) is opened, where n >= 2, the following must apply for the number “p” of PAM pages reserved for the file, and for “s”, its secondary allocation:
File type | SPACE operand p | SPACE operand s |
SAM | >= 2n | >= n |
K-ISAM | > n | |
NK-ISAM | > n | |
PAM (chained I/O) | > 0 |
= <integer -2147483647..2147483647>
The primary allocation, which takes effect immediately.
In the following description, k represents the number of PAM blocks per unit (smallest management unit for the storage space management of disk files; for more information on units see the section “Requesting storage space” in the “Introductory Guide to DMS” [1]).
1...2147483647:
The storage space allocation is rounded up to a multiple of k and the corresponding number of PAM pages is allocated on the pubset or on the private disk. Users should note that each FILE macro with a positive primary allocation reserves space for the file. If the primary allocation is large, this will quickly exhaust the user's storage space contingent.
For files on public disks and private disks the disks for storage allocation are determined as follows:
Storage space on public volumes is allocated if the VOLUME operand is not specified and the file does not yet occupy storage space.
The following parameters are considered when selecting the volume set for files on SM pubsets:
preliminary file format
values of AVAIL, WORKFIL, VOLSET, IOPERF, IOUSAGE, DISKWR
permanent/temporary attributes
storage class assigned to the file.
If the VOLUME operand is specified and the file already occupies storage space, the disks already occupied by the file are used for storage space allocation as far as possible.
If the VOLUME operand is specified, storage allocation starts with the first disk received via the VOLUME operand. If this is not sufficient, allocation is continued with the second disk received via the VOLUME operand, etc.
Storage allocation to a pubset is rejected if the total number of free pages is less than was specified in the primary allocation.
For files on public disks and private disks a partial allocation is made if the VOLUME operand is specified and the disks received via VOLUME contain a total number of free PAM pages which is lower than was specified in the primary allocation (but at least one free unit). However, the FILE call is rejected if public disks are specified and there are fewer PAM pages free on the whole pubset than were specified in the primary allocation (see above).
The user ID entry in the user catalog contains its contingent of public storage space. The following applies if this is exceeded in the request for storage space by the file user ID: if, according to the user catalog entry, the user ID has the right to exceed the contingent, the calling task is informed with a warning that the contingent has been exceeded, otherwise the FILE call is rejected.
If possible, a partial allocation is made with private disks if the request exceeds the free storage space contingent.
Only the maximum possible partial allocation is made if a request would lead to the maximum file size that can be represented in the catalog entry (16777215 PAM pages) being exceeded.
-2147483647..-1:
Amount of storage space released after rounding the primary allocation up to a multiple of k. The space is released from the end of the file, working backwards, as specified in the volume list (any specification in the VOLUME operand is ignored). Only “unused” units are released. For ISAM files, the data and index sections cannot be released separately (see the DSPACE operand, "FILE - Define file attributes / control file processing").
If the file does not occupy storage space after this has been released, the following are deleted from the catalog entry: AVAIL, WORKFIL (not, however, for generations), STOCLAS indicator “File contains defective block”, indicator “S0 migration forbidden” and the interim file format.
If a BS2000 file on a Net-Storage volume has no more space after storage space has been released, it no longer exists on the Net-Storage volume. All references to the Net-Storage volume are removed from its catalog entry.
At least three PAM pages, and in the case of node files at least four PAM pages, remain allocated to the file in the case of files on private disks. For existing files with BLKSIZE=(STD,k), at least as many PAM pages remain allocated as are required for opening the file. The number of remaining PAM pages is defined in this case by storage management.
If DESTROY=YES is defined in the catalog entry, all released PAM pages are overwritten with X'00' (ignoring unit boundaries). Any required private disks are requested in this case. If DESTROY=NO is defined in the catalog entry, the released PAM pages are only overwritten if the destroy level (system parameter DESTLEV) is set high enough.
0:
No change to the storage space reservation; permissible for files on private disks only if the file already occupies storage space. Simultaneous specification of VOLUME is ignored if the file already occupies storage space, otherwise it is rejected.
= (<integer -2147483647..2147483647>,<integer 1..32767>)
Defines the primary and secondary allocations. In contrast to the primary allocation, the secondary allocation does not take effect immediately when the FILE macro is issued, but only if the reserved space runs out during creation or extension of the file. The secondary allocation value is placed in the catalog entry (field S-ALLOC in the output for the SHOW-FILE-ATTRIBUTES command).
<integer -2147483647..2147483647>:
see “primary” above.
<integer 1..32767>:
Secondary allocation, i.e. the number of PAM pages by which the storage is to be extended if required. The secondary allocation is transferred unchanged into the catalog entry. It is only rounded up to a multiple of k when it comes into effect.
SPACE=(0,secondary) defines or changes the secondary allocation and places the (new) value in the catalog entry. This may be specified for a file or file generation on private disk only if space has already been requested for this file or file generation.
(...,0):
Prevents dynamic expansion of the file.
= (<integer -2147483647..2147483647>[,<integer 1..32767>],*KEEP)
Only as of VERSION=2 with release of storage space for a file on public volumes or Net-Storage volumes:
“*KEEP” means that at least one allocation unit remains assigned to the file.
= (<integer -2147483647..2147483647>,<integer -2147483647..2147483647>,ABS)
Absolute allocation (only together with VOLUME). If there is not enough free space on the disk, the FILE macro is rejected; no partial allocation is made. Since the absolute allocation always refers to one volume, a separate FILE macro must be issued for each volume.
If the absolute allocation is the first space request for the file, the secondary allocation is set to 0. The following is specified:
Block number of the PAM page at which the space reservation is to start on the private disk. Since space is always allocated in units, “page” must be k*n + 1 (where n >= 0). The first PAM page on a disk at which storage space can be reserved depends on how the disk was formatted.
Specifies how many PAM pages are to be reserved on the volume. It must be a multiple of k. As the capacity of a given disk depends on the disk type and how it was formatted, the user should ask the system administrator what the maximum permissible value is. The upper limit for this maximum value is 2147483647 (as for the primary allocation).
ABS: The keyword “ABS” identifies an absolute allocation
Absolute allocation is not possible for a file on a Net-Storage volume.
STATE = FOREIGN
For files on private volumes or on Net-Storage volumes of the NETSTOR type for which no entry exists in the system catalog, a catalog entry is created (file import). For file generations, the group entry must also be reconstructed (by means of a CATAL macro) before the generations can be imported. Files which are imported with STATE=FOREIGN should be exported from the catalog of their “old” owner (by means of ERASE CATALOG).
The VSNs of the volumes required for file processing must be listed in the VOLUME operand in the correct order. The VOLUME specification can be omitted if MAREN is available and the file volumes are in the MAREN catalog. MAREN then supplies the VSNs.
The following must not be specified together with STATE=FOREIGN:
DEVICE=WORK, TVSN, TSET, VSEQ.
Files on private disk:
The catalog entry is created from the F1 label of the first private disk specified in the VOLUME operand or received via MAREN. The file can only be imported to the user ID contained in the F1 label. The file may also be imported to pubsets other than those on which it was first cataloged. A file cataloged in the F1 label as shareable can be imported to the user ID contained in the F1 label by any task (i.e. regardless of the task user ID).
Files on Net-Storage:
The catalog entry is created from the catalog on the Net-Storage volume of the NETSTOR type which is specified in the VOLUME operand. Specifying the VOLUME operand for a Net-Storage volume of the NETVOL type is not permitted. The file can be imported only to the pubset which is allocated to the Net-Storage volume of the NETSTOR type which is specified in the VOLUME operand.
Tape files:
File attributes of a foreign file cannot be changed by means of a CATAL macro.
If the foreign tape file has standard labels, the file attributes RECFORM, RECSIZE, BLKSIZE and CODE are transferred from the HDR2 label to the catalog entry when the file is opened. The file may be cataloged under more than one user ID; the system then ensures that the catalog entries and the label information are kept consistent.
If the foreign file has nonstandard labels or no labels, the user must specify the operands RECFORM, RECSIZE and BLKSIZE in the FILE macro. If the file is cataloged under more than one user ID, each user is responsible for ensuring that the catalog entry and the label information are kept consistent.
If a foreign tape file with standard labels is to be imported, the following must apply: if the user is not the file owner, the volume and the file must be shareable (indicators in the VOL1 and HDR1 labels).
STOCLAS
Only for VERSION=3:
When a file is created on an SM pubset, it can be assigned a storage class. This then contains an attribute that satisfies the file storage location requirement. If the storage class is assigned to a volume set list, the file is preferably stored on a volume set from this list.
A storage class-relevant entry exists in the following cases:
If one of the operands AVAIL, DISKWR, VOLUME, VOLSET or WORKFIL is specified.
If a value other than NETSTOR and other than STDDISK is specified for the DEVICE operand.
If a value not equal to the null operand is specified for either the IOPERF or IOUSAGE operand.
A default storage class can be stored in the entry for each user ID in an SM pubset's user catalog. This can be displayed using SHOW-USER-ATTRIBUTES INF= PUBSET-ATTR.
When a file or file generation is created on an SM pubset under a user ID which possesses a default storage class on the SM pubset then the following applies: if there is no right to perform physical allocation and the file has not been created on a volume set for work files then specifications relating to storage classes and STOCLAS=*NONE become ineffective, i.e. they are ignored, provided that they are not rejected. (IOPERF and IOUSAGE are nevertheless entered in the TFT entry.)
If a file (not a file generation) is created on an SM pubset under a user ID which possesses a default storage class on the SM pubset then the user-specific default storage class is assigned to the file if no STOCLAS is specified and no storage class-relevant entry exists.
A default storage class can also be stored in an FGG index. This is assigned to an SM pubset when a file generation is created if no STOCLAS is specified and no storage class-relevant entry exists.
If a default storage class is stored in the file user ID entry or the FGG index and this storage class does not exist on the SM pubset concerned or the user is not authorized to access it, the value NONE or another storage class must be specified in the STOCLAS operand in order to create the file or file generation.
If the file is created on an SF pubset or a private volume, it is not assigned a storage class even if a storage class name is specified or a default storage class exists.
A storage class can also be assigned if a file is created on a Net-Storage volume; in this case no work file can be created, nor a file with a PAM key.
= *NONE
The file is not assigned a storage class, an existing default storage class is also not assigned.
= <c-string 1..8>
Name of the storage class assigned to the file. The entry is rejected in the following cases:
the file already occupies storage space
SPACE has been specified with a non-positive primary allocation
an storage class-relevant entry exists
the storage class does not exist on the SM pubset concerned
the caller is not authorized to access the storage class.
STREAM
For BTAM tape files:
Enables streaming mode to be used for I/O. This means that the chained I/O jobs (CHAINIO operand) offered in MAV mode (BTAMRQS operand in the FCB call and REQNO in the BTAM call) are themselves chained. It also means that hardware “streaming” mode is to be set if a tape streamer is used.
= NO
Streaming mode is not set unless STREAM=YES is specified in the FCB of the program.
= YES
Streaming mode is set.
TAPEWR
Only as of VERSION=1, for files on tape cartridges:
The user can specify whether or not output is to be buffered.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= DEVICE-BUFFER
Output is buffered in the tape controller, thus causing a high data transfer rate.
= IMMEDIATE
Output is not buffered.
TPMARK
For tape files without standard labels (LABEL=NO/NSTD):
Specifies whether tape marks are to be written when a tape file is created. Tape files with LABEL=(STD,n) automatically receive tape marks after the labels.
= NO
No tape mark is written for tape files without standard labels, unless TPMARK=YES is defined in the FCB of the program.
= YES
Tape files with nonstandard labels: the tape mark follows the label.
Tape files without labels: the tape mark is written at the beginning of the tape.
TRANS
For tape files used as input files and not created with CODE=EBCDIC:
specifies how the code of the file is to be converted during reading.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= YES
ISO 7-bit code or OWN code is converted into EBCDIC code.
= NO
ISO 7-bit code is converted into 8-bit format by inserting a leading zero.
TSET
For output tape files with standart labels:
Together with the LINK operand, this creates a tape set for the file via a TST entry (in the tape set table) or sets up a link to an existing TST entry. The corresponding TFT entry then points to the linked TST entry.
A TST entry consists basically of a TSET name and a volume list; the volume list can be defined or extended via the VOLUME operand. Subsequent FILE calls may refer to this volume list by specifying the TSET name, and may extend the list if necessary.
The following applies if TSET is specified together with LINK:
If the current TSET name does not yet exist in a TST entry, a new entry is created with TSET-SHR=1 (TSET-SHR shows the number of TFT entries linked to this TST entry; see the output of the SHOW-FILE-LINK command).
If there is already a TST entry with the same name, and if a file link name which does not exist in the TFT is specified, TSET-SHR is incremented by 1.
When a TFT entry which is linked to a TST entry is released, the TSET-SHR of this entry is decremented by 1. If this results in TSET-SHR=0, the TST entry is also released.
The following conditions must be fulfilled if TSET is specified:
The volume table in the catalog entry must be empty if a cataloged file is specified.
The DEVICE operand must be specified if a new file is specified.
If the DEVICE operand is specified, its value must be a tape type.
The following operands must not be specified together with TSET:
STATE=FOREIGN, DEVICE=WORK, VSEQ, TVSN, FSEQ=UNK, FSEQ=n where n>1, FSEQ=null operand, VOLUME=REMOVE-UNUSED
= <name 1..4>
Tape set name in the TST entry which is used as a reference. If the TST entry does not exist or has no file set identifier and the VOLUME operand is specified, the first VSN received via the VOLUME operand is entered as the file set identifier.
= (<name 1..4>,<name 1..6>)
The four-character name designates a TST entry, the six-character name (VSN) is the file set identifier.
If the TST entry already exists, the file set identifier in the TSET specification must match the file set identifier in the TST entry. When a file is opened, the file set identifiers in the TST entry and in the HDR1 label must be the same.
TVSN
Only for tape files used as input files:
Specifies a temporary list of volume serial numbers for processing, which constitutes the volume list. If the TVSN operand is specified, the volume list in the catalog entry is ignored during file processing; only the volumes specified via TVSN are used. However, the catalog entry is not changed.
The following operands must not be specified together with TVSN:
*DUMMY, STATE=FOREIGN, TSET, VOLUME
= <@addr>
Only as of VERSION=2:
addr is a symbolic address in the program at which a TVSN list was stored with the macro FILELST TVSN=....
The “@” character is part of the operand value and must be specified.
= list-poss (255): <name 1..6>
Defines the volume VSN required for input.
VALLEN = <integer 0..255>
For K-ISAM files:
specifies the length of the value flag in the ISAM index.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
For K-ISAM files, the value flags are evaluated block-by-block and transferred to the next higher index entry as specified in the VALPROP operand. For NK-ISAM files, the VALLEN specification is ignored.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The VALLEN value from the reference file catalog entry is ignored.
VALPROP
For K-ISAM files:
VALPROP (VALue PROPagation) specifies how the value flag is to be included in the index entries.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= *BY-PROG
Only as of Version=3 and only relevant if the DATATTR operand is specified:
The VALPROP value from the reference file catalog entry is ignored.
= MIN
The lowest value of the value flag within a data or index block is included in the index entry at the next higher level.
= MAX
The highest value of the value flag in a data or index block is included in the index entry at the next higher level.
VERSION
Specifies which version of the operand list and which SVC are to be generated.
Default value: | VERSION=0 |
Note
The VERSION operand must have the same value in all FILE macros distinguished by the MF operand
(MF=L/E/D/C).
= 0
The “old” format (SVC 159) of the operand list (as for BS2000 V9.0) is generated. If support is required for device types and functions which have been introduced since this version, a new format of the operand list (as of VERSION=1) must be used.
= 1
Valid from BS2000 V9.5 onwards:
An operand list with a standard header (SVC 144) is generated. Over and above the operands of BS2000 Version 9.0, this format also supports the operands BLKCTRL, CLOSMSG, DESTOC, POOLLNK and TAPEWR introduced in BS2000 Version 9.5 and the device types valid from V9.5 onwards.
= 2
Valid from BS2000 V10.0 onwards:
An operand list with a standard header (SVC 144) is generated. In contrast to the operand list for VERSION=1, the variable parts (for the operands VOLUME, DVOLUME, TVSN, MOUNT and VSEQ) of this operand list are stored in separate areas. These areas can be created by means of the FILELST macro.
The following operands and operand values are only supported as of VERSION=2:IOPERF, IOUSAGE, CLOSE, BLKCTRL=DATA2K/DATA4K, SHARUPD=WEAK and SPACE=(...,*KEEP)
= 3
Valid as of BS2000/OSD-BC V3.0: an operand list with a standard header (SVC 144) is created.
The following operands and operand values are only supported as of VERSION=3:AVAIL, CLOSE=KEEP-DATA-IN-CACHE, CODE=ISO7D, DATATTR, DISKWR, EXC32GB, LOCKENV, NFTYPE, POOLSIZ, STOCLAS, VOLSET, VOLUME=REMOVE-UNUSED, WORKFIL and the value =*BY-PROG with some operands.
This format of the operand list offers the best programming support; another factor that speaks in its favor is its suitability for use with future developments in the FILE macro.
VOLSET
Only as of VERSION=3 for files on SM pubsets:
Defines the volume set on which the file is to be created. The specification is rejected if the file already occupies storage space, if it is to be created on a Net-Storage volume, or if SPACE is specified with a non-positive primary allocation.
Specifying a volume set with permanent data storage requires permission for physical allocation.
= <c-string: catid 1..4>
Catalog ID of the volume set on which the file is to be created.
= *CONTROL
The file is created on the control volume set of the SM pubset.
VOLUME
Specifies which volumes are required for file processing.
If, when a file is being created, neither DEVICE nor VOLUME is specified, the file is created on public volumes.
Net-Storage volumes are regarded as disks and can be specified without the authorization for physical allocation.
If the first VSN obtained using the VOLUME operand identifies a Net-Storage volume which is assigned to the pubset on which the file resides or is to be created, the VSN remains assigned to the Net-Storage volume even if it also identifies a private disk.
For files on public disks, Net-Storage volumes or private disks:
The volume list contains all disks on which extents of the file are located (possibly after storage space allocation is completed).
DMS attempts to reserve all the space specified via SPACE on the first disk. “Unused” volume serial numbers are moved to the volume list of the catalog entry for subsequent file extensions.
If no storage space allocation is necessary, the specified volume serial numbers will be ignored.
For files on a Net-Storage volume:
The volume list consists of the VSN of the Net-Storage volumes on which the file is located or will be created. This VSN also determines the Net-Storage volume type (NETSTOR or NETVOL) on which the file is created. The volume table in the catalog entry and (if the LINK operand is specified) the volume table in the in the generated TFT entry also consist of this one VSN. The pubset on which the file is or will be cataloged must be assigned to the Net-Storage volume on which the file is located or will be created.
For tape files:
The volume list consists of the volume serial numbers in the catalog entry (if these exist), followed logically by the volume serial numbers from the VOLUME operand. By default, the first volume from the volume list is requested (unless MOUNT=0 is specified). If the uses requests more than one volume, the number of volumes to be mounted concurrently must be specified in the MOUNT operand.
If “pathname” is not yet cataloged, the volume serial numbers from the VOLUME operand are transferred to the catalog entry. Furthermore, the TSET operand can be used to establish a link to a TST entry.
The effects of the VOLUME operand depend on whether the TSET operand is specified. If it is not specified, the volume list is copied unchanged into the catalog entry. If TSET is specified, first the volume list of the TST entry is updated or created and then the volume list of the catalog entry is created according to the TST entry. After a file has been opened, the catalog entry is then updated with the information from the volume list of the TST entry.
If “pathname” is already cataloged, the volume serial numbers from the VOLUME operand form an extension to the volume table of the catalog entry. This means that the VOLUME operand may contain no volume serial numbers which already exist in the catalog entry.
= @addr
Only as of VERSION=2:
addr is a symbolic address in the program at which a VOLUME list has been created by means of the macro FILELST VOLUME=...
The character “@” is part of the operand value and must be specified.
= REMOVE-UNUSED
Only for already cataloged tape files:
All tapes which do not contain data from the file are removed from the catalog entry volume table.
LINK and TSET must not be specified together with REMOVE-UNUSED.
= PRIVATE
A private volume is required for file processing. The operator is requested via a message on the console to enter the volume serial number of the required volume.VOLUME=PRIVATE is ignored in a FILE call for the dummy file *DUMMY.
= (PRIVATE,<integer 1..9>)
A number of private volumes are required for file processing. The operator is requested via a message on the console to enter the volume serial numbers of the required volumes.
VOLUME=(PRIVATE,<integer 1..9>) is ignored in a FILE call for the dummy file *DUMMY.
= list-pos(255): <name 1..6>
Volume serial numbers of the requested volume.
VSEQ
For cataloged tape files with standard labels:
the VSEQ operand permits section-by-section processing of files. A file section is that part of a multivolume file which is stored on one tape (see the programming notes on "FILE - Define file attributes / control file processing" for the effect on the structure of the TFT volume list).
The VSEQ operand refers to the volume list (see the VOLUME operand). The file section numbers correspond to relative volume serial numbers, i.e. they specify the position of the volume serial number in the volume list.
Single value: | If only one file section number is specified in the VSEQ operand, all volumes from the specified entry onwards are transferred to the volume table of the TFT entry. |
List: | If a list of file section numbers is specified in the VSEQ operand, the specified entries are transferred to the volume table of the TFT entry. |
VSEQ must not be specified together with TSET or STATE=FOREIGN. If the file has not been cataloged or only cataloged with CATAL, all VSEQ specifications apart from VSEQ=1 are rejected.
= @addr
Only as of VERSION=2:
addr is a symbolic address in the program at which a VSEQ list has been created by means of the macro FILELST VSEQ=...
The character “@” is part of the operand value and must be specified.
= <integer 1..255>
Number of the section at which processing is to start.
If “pathname” is an output file (OPEN=OUTPUT/OUTIN), VSEQ=1 must be specified.
If “pathname” is an input file, VSEQ=number designates the file section at which processing is to start.
If “pathname” is opened with OPEN EXTEND, VSEQ specifies the file section at which extension is to begin.
In conjunction with OPEN REVERSE, it is possible to process individual tapes of a file, but tape swapping is inhibited.
= (L=list-poss (255): <integer 1..255>)
Specifies the order in which the file sections are to be processed. this may be used only for input files, not for output files. For files opened with OPEN REVERSE, only one file section number may be specified and automatic tape swapping is not supported.
WORKFIL
Only as of VERSION=3, for files on SM pubsets:
Defines whether the file is created on a work file volume set or a volume set with permanent data retention. Work file volume sets are deleted at a time defined by system administration. Work files cannot be created on a Net-Storage volume. If the file is created on an SM pubset by means of non-physical allocation and WORKFIL is not specified, it is created on a volume set with permanent data retention. The specification of WORKFIL is rejected in the following cases:
for generations
if the file already occupies storage space
if SPACE is specified with a non-positive primary allocation
if the file ends up on a private disk.
= NO
The file is created on a volume set with permanent data retention.
= YES
The file is created on a work file volume set. This specification is not permitted for temporary files.
WRCHK
For the processing of disk files:
specifies whether a read-after-write check is to be executed. “WRCHK” is not placed in the catalog entry and must therefore be repeated each time before the file is opened or processed.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
The read-after-write check serves to detect recording errors ( -> error recovery measures). If the error cannot be recovered, control is passed to the EXLST exit ERRADR. Due to the additional disk revolutions required, the read-after-write function has a decidedly negative effect on system performance.
= NO
No read-after-write check is executed.
= YES
A read-after-write check is executed.
WROUT
For ISAM processing:
WROUT controls how often updated blocks are written back to disk. For shared-update processing or in cross-task ISAM pools and in task-local ISAM pools, WROUT=YES is set implicitly: updated blocks are written back to disk immediately.
If no value is specified in the FILE or FCB macro, the default value of the FCB takes effect on opening the file.
= NO
An updated block is written back to disk only when the contents of the relevant buffer area need to be overwritten or, at the latest, when the file is closed.
= YES
Each updated block is written back to disk immediately, thus always ensuring the consistency of the data on the disk and in virtual memory. However, this also increases the I/O rate.
Programming notes
Structure of the input area if VERSION=0 or VERSION=1 is specified
The operand list of the FILE macro consists of several fixed and variable areas:
|
|
|
: |
|
: |
|
|
|
: |
|
: |
For the two fixed areas of the operand list, two DSECTs are generated by means of MF=D in the FILE macro. The IDPFL macro generates a DSECT for fixed area 1 and IDPFX generates a DSECT for the FILE extension. However, the macros IDPFL and IDPFX support only the old (pre-V9.5) macro format.
Structure of the operand list as of VERSION=2
This format supports all operands and operand values which were introduced after BS2000 V10.0.
If VERSION=2 and higher applies instead of VERSION=0/1, the user can move the variable parts for the VOLUME, TVSN, MOUNT, DVOLUME and VSEQ specifications to separate areas outside the operand list by means of creating a pointer in each operand (specification “@addr”) to a symbolic address “addr” within the program at which he/she has created a list with the corresponding operand values by means of the FILELST macro.
In this case, the operand list created by the FILE macro is an area of fixed length containing solely address pointers to the externally stored variable lists. This list has the following structure:
DSECTs for the fixed area and the externally stored variable areas can be generated using the D form of the FILE and FILEST macros.
Example
The program TAPEFIL reads the tape file TAPE.FILE via the file link name INTAPE.
The list of required volumes is specified by way of the TVSN operand in the FILE macro:
TAPEFIL START
.
.
FILE TAPE.FILE,LINK=INTAPE,TVSN=@TVSNLIST,VERSION=3,MF=L ———— (1)
.
.
TVSNLIST FILELST TVSN=(VOL003,VOL009,VOL017) —————————————————————————— (2)
.
.
END
(1) | The specification @TVSNLIST in the TVSN operand generates in the operand list of the FILE macro an address pointer to the symbolic address TVSNLIST. At this address the FILE macro expects the (variable) area with the list of TVSN values. |
(2) | The FILELST macro generates at the address TVSNLIST a list containing the values for the TVSN operand in the FILE macro. |
Notes on the processing of tape files
Operand STATE=FOREIGN
A FOREIGN indicator is set in the catalog entry, thus making it impossible to change the file attributes by means of a CATAL macro. This FOREIGN indicator is reset when the file is opened.
If sequential file generations of a group belong to the same MF/MV set, DISP=REUSE should never be used in the CATAL macro, since this can lead to the destruction of file generations.
The method for importing foreign files is not the same as that used for private disk files. The reason for this is that the catalog entry for a foreign disk file is unique. For foreign tape files, this uniqueness could be achieved if the user IDs of the file owners already exist in the system into which the file is to be imported. However, if these user IDs do not exist, it is not possible to change the owner identifier on the tape (a hardware restriction would cause the file to be destroyed). Even if the system administrator imports a file for an existing user ID, it cannot be guaranteed that the catalog entry will be unique, since he can also catalog the file under another user ID.
Nevertheless, by virtue of the restrictions in the CATAL macro, tape files with standard labels enjoy the same protection as disk files against conflicts between the file attributes specified in the labels and those in the catalog entry. The only risk factor is that the file owner may change the file attributes by specifying SECLEV=LOW in the FCB. For this reason, there should never be more than one catalog entry in the same system for one file, even if the owner of the file is also working in this system.
Return codes
As of version 3, the error code is returned in the parameter list standard header and no longer in general purpose register 15 as in version 2. The standard header must not reside in the read-only area, otherwise the program will be terminated.
Standard header: ccbbaaaa
The following code relating to execution of the CATAL macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'0000' | No error | |
X'40' | X'0501' | Requested catalog not available | |
X'82' | X'0502' | Requested catalog in the rest state | |
X'40' | X'0503' | Incorrect information in the MRSCAT | |
X'82' | X'0504' | Catalog access error | |
X'40' | X'0505' | Computer communication error (MRS) | |
X'80' | X'0506' | Operation cancelled because of master change | |
X'40' | X'0510' | Error while calling an internal function | |
X'40' | X'0511' | No allocation because of MVDF inconsistency | |
X'40' | X'0512' | Catalog ID not entered in the MRSCAT | |
X'40' | X'0515' | Call rejected by the system exit routine | |
X'40' | X'051B' | User ID not known in specified pubset | |
X'40' | X'051C' | No access right to specified pubset | |
X'40' | X'051D' | LOGON password different on specified pubset | |
X'02' | X'00' | X'051E' | Only partial allocation because of MVDF inconsistency |
X'20' | X'0531' | Unexpected catalog access error | |
X'82' | X'0532' | File locked because it is in use | |
X'40' | X'0533' | File not found | |
X'82' | X'0534' | Private volume cannot be allocated | |
X'40' | X'0535' | No access right to the file catalog entry | |
X'20' | X'0536' | Error in file management system | |
X'40' | X'053A' | Error while updating the F1 label on a private disk | |
X'20' | X'053B' | System error during catalog access | |
X'82' | X'053C' | Catalog file of the pubset is full | |
X'40' | X'053D' | Catalog or F1 label block is destroyed | |
X'40' | X'053E' | File on private volume already cataloged | |
X'82' | X'053F' | File reserved by another task | |
X'40' | X'0540' | Pubset contains no appropriate volume set | |
X'82' | X'0541' | No disk storage space assigned | |
X'82' | X'0542' | Device not available / disk exclusive | |
X'20' | X'0543' | Faulty allocator parameter area | |
X'20' | X'0544' | Incorrectly formatted catalog entry | |
X'40' | X'0545' | Public volume not connected | |
X'02' | X'00' | X'0546' | File catalog entry full |
X'40' | X'0547' | Volume cannot be mounted | |
X'82' | X'0548' | Not enough storage space | |
X'20' | X'0549' | System error with REQM or AQIR call | |
X'02' | X'00' | X'054A' | Storage space only partially allocated |
X'40' | X'054B' | No volume set available for specified catalog ID | |
X'82' | X'054D' | Storage space contingent exhausted | |
X'82' | X'0550' | File opened and therefore locked | |
X'01' | X'0551' | VSN for tape file specified more than once | |
X'01' | X'0553' | Illegal absolute storage space request | |
X'01' | X'0554' | Illegal file name format | |
X'40' | X'0555' | STATE=FOREIGN: file already cataloged | |
X'01' | X'0556' | STATE=FOREIGN: device type invalid or missing | |
X'40' | X'0557' | Incorrect VSN specification | |
X'01' | X'0558' | Public VSN illegal | |
X'01' | X'0559' | Illegal specification with MOUNT | |
X'82' | X'055A' | Tape device currently reserved | |
X'40' | X'055C' | F1 label missing | |
X'40' | X'055D' | User has no physical allocation right | |
X'40' | X'055E' | Foreign user ID for non-cataloged file | |
X'40' | X'055F' | Volume could not be reserved | |
X'01' | X'0576' | Incorrect operand combination or undeleted UNUSED fields | |
X'20' | X'0578' | Internal error while checking access rights | |
X'01' | X'0579' | Invalid operand for temporary or work file | |
X'40' | X'057A' | Storage class incompatible with file attributes | |
X'40' | X'057B' | Illegal operand for migrated file | |
X'40' | X'057C' | HSMS has rejected recall | |
X'40' | X'057E' | HSMS not available | |
X'01' | X'0590' | Device type specification missing for private volume | |
X'01' | X'0592' | Private disk file has rejected catalog entry without extents or device type definition for public disk rejected | |
X'01' | X'0593' | Absolute allocation: illegal number of half-pages | |
X'82' | X'0594' | Insufficient virtual memory available | |
X'01' | X'0595' | Illegal mix of public and private VSNs | |
X'01' | X'0596' | Device type specification not according to catalog entry | |
X'01' | X'0597' | Absolute allocation: first half-page not on unit border | |
X'01' | X'0599' | Operand not supported in the remote version | |
X'01' | X'05A3' | Incorrect SPACE entry | |
X'01' | X'05A4' | Incorrect use of DSPACE/DVOLUME/DDEVICE | |
X'01' | X'05A8' | Device type not in system | |
X'82' | X'05B0' | No suitable tape device available | |
X'82' | X'05B1' | A file lock is in effect for the file | |
X'40' | X'05B4' | Volume request was rejected | |
X'40' | X'05BD' | Illegal combination of file and volume set attributes | |
X'01' | X'05C2' | Chain name = X'0000000000000000' | |
X'82' | X'05C3' | File generation to be deleted is locked | |
X'40' | X'05C4' | An error occurred during operator logon | |
X'20' | X'05C7' | Internal error in DMS | |
X'82' | X'05C8' | CE limit for user ID exceeded | |
X'20' | X'05CA' | Internal error while modifying CE limits | |
X'40' | X'05D8' | File protected with password | |
X'40' | X'05DA' | Storage space release on foreign user ID | |
X'01' | X'05DF' | Illegal specification for BLIM / CHKPT | |
X'20' | X'05E0' | File locked because of storage management system error | |
X'01' | X'05E8' | File name invalid for disk file | |
X'01' | X'05EE' | File name too long after completion | |
X'01' | X'05EF' | File protection using GUARD only possible for public files | |
X'01' | X'05FA' | Pubset not locally accessible | |
X'40' | X'05FC' | User ID not registered | |
X'40' | X'05FD' | File protected via release date or access type | |
X'40' | X'0606' | Volume request rejected by MAREN | |
X'40' | X'0609' | Storage space release not permitted for system file | |
X'40' | X'060D' | Incorrect name specified for reference file | |
X'40' | X'060E' | Reference file not found or not accessible | |
X'40' | X'0613' | Incorrect specification of a storage class | |
X'40' | X'0640' | Access to Net-Storage is rejected by the ONETSTOR subsystem | |
X'40' | X'0641' | File already exists on Net-Storage | |
X'40' | X'0642' | Large files are not permitted on the specified pubset | |
X'40' | X'0643' | Net client reports access error | |
X'40' | X'0644' | Net client reports internal error | |
X'40' | X'0645' | File does not exist on Net-Storage | |
X'40' | X'0647' | Specified file does not match the file’s catalog entry | |
X'40' | X'0648' | Specification of the file type, device and volume are not compatible | |
X'40' | X'0649' | Net server reports POSIX ACL error | |
X'40' | X'064A' | Net client reports that access to files on the Net-Storage volume is forbidden | |
X'40' | X'064B' | Access to node files from the net client not supported | |
X'40' | X'0652' | Absolute storage space request not permitted on Net-Storage | |
| X'40' | X'0653' | Net-Storage volume of type NETVOL cannot be imported | |
X'40' | X'0666' | File is protected against requested access | |
X'40' | X'0683' | File already exists | |
X'40' | X'0689' | Operand only permitted for file without storage | |
X'40' | X'06B5' | File is not correctly closed | |
X'01' | X'06C7' | Invalid generation number | |
X'01' | X'06C8' | Attribute illegal for file generations | |
X'40' | X'06CD' | FGG protected against extension | |
X'01' | X'06CF' | Illegal specification of an FGG | |
X'40' | X'06D0' | STATE=FOREIGN for non-existent file generation | |
X'40' | X'06D1' | FGG index locked by another task | |
X'01' | X'06DA' | Illegal public/private mix for FGG | |
X'01' | X'06DF' | Illegal specification for FSEQ/VSEQ/TSET | |
X'01' | X'06FD' | Illegal parameter range address | |
X'40' | X'06FF' | BCAM connection severed | |
X'01' | X'FFFF' | Incorrect function number in standard header | |
X'03' | X'FFFF' | Incorrect version number in standard header |