Operating System BS2000 OS DX V1.0 (en)

&pagelevel(3)&pagelevel

Create TFT entry and assign values

Component:	BS2000
Functional area:	File processing
Domain:	FILE
Privileges:	STD-PROCESSING HARDWARE-MAINTENANCE SAT-FILE-EVALUATION SAT-FILE-MANAGEMENT
Routing code:	$ (with NBCONOPI=N) or E (with NBCONOPI=Y)

Function

The ADD-FILE-LINK command creates a TFT (Task File Table) entry for the link name specified in the LINK-NAME operand. At the same time, the command assigns values to the TFT entry. If there is already a TFT entry for the specified link name, it is overwritten by the new entry.

The command cannot create new catalog entries or modify the catalog entries of disk files. The command can, however, modify the catalog entries of tape files (using the ADD-CATALOG-VOLUME, TAPE-SET-NAME and FILE-SEQUENCE operands, for example). The command cannot be used to modify the storage space allocation of a disk file.

The command cannot modify an existing TST (Tape Set Table) entry; this is the job of the EXTEND-TAPE-SET command.

The command is rejected in the following situations:

A value other than *BY-PROGRAM, *DUMMY or the name of a file which is already in the catalog has been specified in the FILE-NAME operand.
No disk space has been reserved for the disk file specified in the FILE-NAME operand (though a tape file which is in the catalog may be specified even if the volume table in the catalog entry is empty).

Overview of functions

Function / Meaning	Level 1 operands	Level 2/3 operands
Define the file link name for which a TFT entry is to be created	LINK-NAME =
Name of file/file generation to which the ADD-FILE-LINK command refers	FILE-NAME =
Access method (ISAM, SAM, BTAM ...)	ACCESS-METHOD =
File OPEN mode	OPEN-MODE =
File CLOSE mode	CLOSE-MODE =
Import file attributes from the file	DATA-ATTRIBUTES =
Record format	RECORD-FORMAT =
Variable record format
feed control		PRINT-CONTROL =
Fixed record format	RECORD-FORMAT = *FIXED(...)
feed control		PRINT-CONTROL =
Undefined record format	RECORD-FORMAT =*UNDEFINED(...)
feed control		PRINT-CONTROL =
Record length	RECORD-SIZE =
Block length	BUFFER-LENGTH =
Block control information	BLOCK-CONTROL-INFO =
Number of mount requests	NUMBER-OF-PREMOUNTS =
Retention period	RETENTION-PERIOD =
Define volume type	SUPPORT =
Volume: disk	SUPPORT = *DISK(...)
write access for shared updating		SHARED-UPDATE =
concurrent writing by jobs from different systems		LOCK-ENVIRONMENT =
file size restriction		EXCEED-32GB =
read-after-write checking		WRITE-CHECK =
Performance requirements		IO-ATTRIBUTES =
performance attribute for the file		PERFORMANCE =
scope of performance requirements		USAGE =
ISAM processing specifications		ISAM-ATTRIBUTES =
Key position		KEY-POSITION =
Key length		KEY-LENGTH =
Length of value flag		VALUE-FLAG-LENGTH =
evaluation of value flags		PROPAGATE-VALUE-FLAG =
length of logical flags		LOGICAL-FLAG-LENGTH =
block padding (for sequential processing)		PADDING-FACTOR =
define pool link name for ISAM pool (NK-ISAM files)		POOL-LINK =
Size of the file-specific ISAM pool (NK-ISAM files)		POOL-SIZE =
Immediate writing out of updated blocks		WRITE-IMMEDIATE =
Overlapped processing		READ-IN-ADVANCE =
Duplicate keys		DUPLICATE-KEY =
Volume: tape	SUPPORT = *TAPE(...)
list of tapes to process		VOLUME-LIST =
tape type		DEVICE-TYPE =
label processing specifications		LABEL-PROCESSING =
label types		LABEL-TYPE =
Bypass label checking		BYPASS-LABEL-CHECK =
Protection level		PROTECTION-LEVEL =
tape marks		TAPE-MARK-WRITE =
define translation table		CODE =
EBCDIC translation		EBCDIC-TRANSLATION =
define position in file set		FILE-SEQUENCE =
automatic checkpoint writing		CHECKPOINT-WRITE =
file usage on restart		RESTART-USAGE =
maximum number of blocks per tape		BLOCK-LIMIT =
Buffer offset		BLOCK-OFFSET =
buffered/unbuffered processing		TAPE-WRITE =
overwrite data on remainder of tape		DESTROY-OLD-CONTENTS =
Chained input/output		IO-CHAINING =
Message output on completion of CLOSE processing	FILE-CLOSE-MSG =

Table 18: Overview of ADD-FILE-LINK command functions

Format

ADD-FILE-LINK

Alias: ADFL

LINK-NAME = <filename 1..8 without-gen>

,FILE-NAME = *BY-PROGRAM / *DUMMY / <filename 1..54>

,ACCESS-METHOD = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *SAM / *ISAM /

*BTAM / *UPAM

,OPEN-MODE = *BY-PROGRAM / *INPUT / *OUTPUT / *EXTEND / *REVERSE / *UPDATE / *OUTIN /

*INOUT / *SINOUT

,CLOSE-MODE = *BY-PROGRAM / *REWIND / *REPOS / *UNLOAD / *LEAVE / *INVALIDATE /

*KEEP-DATA-IN-CACHE

,DATA-ATTRIBUTES = *STD / *FROM-FILE(...) / *BY-CATALOG

*FROM-FILE(...)

|

FILE-NAME = <filename 1..54>

,RECORD-FORMAT = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *VARIABLE(...) /

*FIXED(...) / *UNDEFINED(...)

*VARIABLE(...)

|

PRINT-CONTROL = *NONE / *ASA / *EBCDIC

*FIXED(...)

|

PRINT-CONTROL = *NONE / *ASA / *EBCDIC

*UNDEFINED(...)

|

PRINT-CONTROL = *NONE / *ASA / *EBCDIC

,RECORD-SIZE = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / <integer 0..32768>

,BUFFER-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *STD(...) /

*STD(...)

|

SIZE = 1 / <integer 1..16>

,BLOCK-CONTROL-INFO = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *NO /

*WITHIN-DATA-BLOCK / *WITHIN-DATA-2K-BLOCK /

*WITHIN-DATA-4K-BLOCK / *PAMKEY

,NUMBER-OF-PREMOUNTS = *STD / <integer 0..255>

,RETENTION-PERIOD = *BY-PROGRAM / <integer 0..32767 days>

,SUPPORT = *NONE / list-poss(2): *DISK(...) / *TAPE(...)

*DISK(...)

|

SHARED-UPDATE = *BY-PROGRAM / *NO / *YES / *WEAK

|

,LOCK-ENVIRONMENT = *BY-PROGRAM / *HOST-SYSTEM / *XCS

|

,EXCEED-32GB = *BY-PROGRAM / *FORBIDDEN / *ALLOWED

|

,WRITE-CHECK = *BY-PROGRAM / *NO / *YES

|

,IO-ATTRIBUTES = *BY-PROGRAM / [*PARAMETERS](...)

|

[*PARAMETERS](...)

|

PERFORMANCE = *BY-PROGRAM / *BY-CATALOG / *STD / *HIGH / *VERY-HIGH /

|

*USER-MAXIMUM

|

,USAGE = *BY-PROGRAM / *BY-CATALOG / *READ-WRITE / *WRITE / *READ

|

,ISAM-ATTRIBUTES = *BY-PROGRAM / [*PARAMETERS](...)

|

[*PARAMETERS](...)

|

KEY-POSITION = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /

|

|

,KEY-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /

|

|

,VALUE-FLAG-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /

|

|

,PROPAGATE-VALUE-FLAG = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *MINIMUM /

|

MAXIMUM / *BY-CATALOG

|

,LOGICAL-FLAG-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /

|

|

,PADDING-FACTOR = *BY-PROGRAM / <integer 0..99>

|

,POOL-LINK = *BY-PROGRAM / <name 1..8>

|

,POOL-SIZE = *BY-PROGRAM / <integer 128..1048576 2Kbyte>

|

,WRITE-IMMEDIATE = *BY-PROGRAM / *NO / *YES

|

,READ-IN-ADVANCE = *BY-PROGRAM / *YES / *NO

|

,DUPLICATE-KEY = *BY-PROGRAM / *YES / *NO

*TAPE(...)

|

VOLUME-LIST = *CATALOG (...) / *TEMPORARY(...) / *TAPE-SET(...)

|

*CATALOG(...)

|

ADD-CATALOG-VOLUME = *NONE / *ANY(...) / list-poss(255): <alphanum-name 1..6>

|

*ANY(...)

|

NUMBER-OF-DEVICES = 1 / <integer 1..9>

|

,VOL-SEQUENCE-NUMBER = *NONE / *FROM-START-POSITION(...) /

|

list-poss(255): <integer 1..255>

|

*FROM-START-POSITION(...)

|

START-POSITION = <integer 1..255>

|

*TEMPORARY(...)

|

PROCESS-VOLUME = list-poss(255): <alphanum-name 1..6>

|

*TAPE-SET(...)

|

TAPE-SET-NAME = <alphanum-name 1..4>

|

, FILE-SET-IDENTIFIER = *BY-TAPE-SET / <alphanum-name 1..6>

|

,DEVICE-TYPE = *ANY / <device>

|

,LABEL-PROCESSING = *BY-PROGRAM / [*PARAMETERS](...)

|

[*PARAMETERS](...)

|

LABEL-TYPE = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *NO / *NON-STD / *STD(...)

|

*STD(...)

|

DIN-REVISION-NUMBER = *BY-PROGRAM / <integer 0..3>

|

,BYPASS-LABEL-CHECK = *BY-PROGRAM / *NO-POSITIONING /

|

*ABSOLUTE-POSITIONING(...) / *FORWARD-POSITIONING(...) /

|

*BACKWARD-POSITIONING(...)

|

*ABSOLUTE-POSITIONING(...)

|

TAPE-MARK-NUMBER = <integer 0..32767>

|

*FORWARD-POSITIONING(...)

|

NUMBER-OF-TAPE-MARKS = <integer 0..127>

|

*BACKWARD-POSITIONING(...)

|

NUMBER-OF-TAPE-MARKS = <integer 0..127>

|

,PROTECTION-LEVEL = *BY-PROGRAM / *LOW(...) / *HIGH(...)

|

*LOW(...)

|

OVERWRITE-PROTECTION = *NO / YES

|

*HIGH(...)

|

OVERWRITE-PROTECTION = *NO / YES

|

,TAPE-MARK-WRITE = *BY-PROGRAM / *YES

|

,CODE = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *EBCDIC / *ISO7 / *ISO7D /

|

*OWN

|

,EBCDIC-TRANSLATION = *BY-PROGRAM / *YES / *NO

|

,FILE-SEQUENCE = *BY-PROGRAM / *BY-CATALOG / *UNKNOWN / *NEW / <integer 0..9999>

|

,CHECKPOINT-WRITE = *BY-PROGRAM / [*PARAMETERS](...)

|

[*PARAMETERS](...)

|

CHKPT-AT-BLOCK-LIMIT = *BY-PROGRAM / *YES

|

,CHKPT-AT-FORCED-EOV = *BY-PROGRAM / *YES

|

,RESTART-USAGE = *BY-PROGRAM / *DUMMY

|

,BLOCK-LIMIT = *BY-PROGRAM / <integer 1..999999>

|

,BLOCK-OFFSET = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *BY-HDR2 /

|

|

,TAPE-WRITE = *BY-PROGRAM / *DEVICE-BUFFER / *IMMEDIATE

|

,DESTROY-OLD-CONTENTS = *BY-CATALOG / *NO / *YES

|

,IO-CHAINING = *BY-PROGRAM / <integer 1..16>

,FILE-CLOSE-MSG = *STD / *NO / *YES

Operands

LINK-NAME = <filename 1..8 without-gen>
A link name under which programs can open the file.
The file link name/TFT links the program and file together. A TFT entry is set up for the file link name specified here, and the remaining operands are evaluated and the values copied into this TFT entry. If there is already an entry in the TFT under the specified link name, it is overwritten by the new one.

If the old TFT entry was locked by a LOCK-FILE-LINK command, the new entry is also locked.
The old volume and device reservations are canceled; tape devices remain available to the job but can be released by a SECURE-RESOURCE-ALLOCATION command.
A TSET name cannot be used as a file link name.

FILE-NAME = *BY-PROGRAM / *DUMMY / <filename 1..54>
Identifies the file to which the ADD-FILE-LINK command refers; FILE-NAME must not be a file generation group. The file specified by FILE-NAME must already be cataloged. Unless it is a tape file, it must already have been allocated storage space.
Otherwise, the ADD-FILE-LINK command is rejected.

FILE-NAME = *BY-PROGRAM
The file name specified in the program is used.

FILE-NAME = *DUMMY
Creates a TFT entry for a DUMMY file under the specified link name. No devices, volumes or storage space are allocated.
DUMMY files are typically used during program debugging to simulate I/O transactions or during a restart with the RESTART-PROGRAM command to replace files which are no longer required for processing but without which the program will not run (see the RESTART-PROGRAM command description).
DUMMY file as input file: if an attempt is made to read the file, EOF processing is initiated, which means that the program acts as though the file had already been read. DUMMY file as output file: if an attempt is made to write to the file, the data is transferred to the program’s buffer areas, but output to a volume is suppressed.

FILE-NAME = <filename 1..54>
This is the file the ADD-FILE-LINK command refers to.

ACCESS-METHOD = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *SAM / *ISAM / *BTAM / *UPAM
Specifies the access method for file processing.
Access methods are described in the “Introductory Guide to DMS” [13].

ACCESS-METHOD = *BY-DATA-ATTRIBUTES
The access method of the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, ACCESS-METHOD defaults to *BY-PROGRAM.

ACCESS-METHOD = *BY-PROGRAM
The access method specified in the program is used.

ACCESS-METHOD = *BY-CATALOG
The access method entered in the catalog is used (see SHOW-FILE-ATTRIBUTES command, FILE-STRUCT output field).

ACCESS-METHOD = *SAM
The file specified in the FILE-NAME operand is to be processed using the SAM access method. Both disk and tape files can be processed.

ACCESS-METHOD = *ISAM
The file specified in the FILE-NAME operand is to be processed using the ISAM access method. Only disk files can be processed.

ACCESS-METHOD = *BTAM
The file specified in the FILE-NAME operand is to be processed using the BTAM access method. Only tape files can be processed. BTAM processing is not supported by all programming languages. BTAM-specific operands: IO-CHAINING, OPEN-MODE=*SINOUT

ACCESS-METHOD = *UPAM
The file specified in the FILE-NAME operand is to be processed using the UPAM access method. Both disk and tape files can be processed.

OPEN-MODE = *BY-PROGRAM / *INPUT / *OUTPUT / *EXTEND / *REVERSE / *UPDATE / *OUTIN / *INOUT / *SINOUT
Specifies the OPEN mode for the file. This setting may be overridden by the OPEN statement in the program when the file is actually opened. The following table shows which OPEN modes are permissible for the various access methods ( D, T, X ) and which are not permissible (-).

OPEN-MODE=	Access method
OPEN-MODE=	ISAM	BTAM	SAM	UPAM
*INPUT	P	T	X	X
*EXTEND	P	-	X	-
*INOUT	P	T	-	X
*OUTIN	P	T	-	X
*OUTPUT	P	T	X	-
*REVERSE	-	T	X	-
*SINOUT	-	T	-	-
*UPDATE	-	-	P	-

Table 19: OPEN modes and access methods

The name sections have the following meanings:
P: Disk files (SUPPORT=*DISK)
B: Tape files (SUPPORT=*TAPE)
X: Disk and tape files
-: OPEN mode not supported

OPEN-MODE = *BY-PROGRAM
The OPEN mode specified in the program is used.

OPEN-MODE = *INPUT
The file specified under FILE-NAME is used as an input file (and must therefore already exist).

OPEN-MODE = *OUTPUT
The file is created or, if it already exists, overwritten from the file start. If it is a tape file, a label is created.

OPEN-MODE = *EXTEND
Extends an existing file, i.e. adds blocks to the file end or overwrites the file from a specific point onwards; only sequential writes are allowed. For tape files, labels are generated as appropriate to the LABEL-TYPE specification.

OPEN-MODE = *REVERSE
The file, which is opened as an input file for sequential reading, must already exist. It is processed in reverse order, i.e. from the file end to its start. With tape files, automatic tape swapping is not possible. On completion of OPEN processing, the tape is positioned at the end of the file section.

OPEN-MODE = *UPDATE
For SAM disk files only: the records in the file can be modified using the GET macro followed by the PUTX macro (possible only in move mode).

OPEN-MODE = *OUTIN
The file is created or, if it already exists, overwritten from the file start. Both (nonsequential) writes and reads are allowed. Labels are written in the case of tape files.

OPEN-MODE = *INOUT
Opens an existing file for nonsequential processing; both reads and writes are allowed. Tapes are positioned to start of tape on completion of OPEN processing; no labels are written.

OPEN-MODE = *SINOUT
For tape files only: the file must exist, and the tape must not be positioned at the tape start; data blocks can be read or written, and no label processing is performed. Unlike *INOUT, this mode does not position the tape.

CLOSE-MODE = *BY-PROGRAM / *REWIND / *REPOS / *UNLOAD / *LEAVE / *INVALIDATE /
*KEEP-DATA-IN-CACHE
Specifies the CLOSE mode to be used to close the file. This setting may be overridden by a CLOSE macro when the file is actually closed.
See the CLOSE macro description in the “DMS Macros” manual [12].

CLOSE-MODE = *BY-PROGRAM
The CLOSE mode is defined by the CLOSE macro in the program.

CLOSE-MODE = *REWIND
For tape files only: regardless of the LABEL-TYPE specification, the tape is rewound to the start once the file has been closed.

CLOSE-MODE = *REPOS
For tape files only: the tape is repositioned to the start of the current file section once the file has been closed.

CLOSE-MODE = *UNLOAD
For tape files only: the tape is rewound, unloaded and released once the file has been closed.

CLOSE-MODE = *LEAVE
For tape files only: depending on the LABEL-TYPE specification, the tape is positioned to the logical file end once the file has been closed.

CLOSE-MODE = *INVALIDATE
Cached writes for the file are not written out to disk. All the data in the cache is marked as invalid.
This value is useful for files for which (cached) writes are no longer needed once they have been closed. This avoids wasting time writing unsaved cache data out to disk.
Once a file has been closed with CLOSE-MODE=*INVALIDATE, any writes for it are lost. Thereafter, the file must under no circumstances be opened with OPEN-MODE= *INPUT or *OUTPUT.

CLOSE-MODE = *KEEP-DATA-IN-CACHE
Cached writes for the file are not written out to disk. All the data in the cache is retained there.
This value is useful for follow-up processing on the file since no time is wasted writing the cache data out to disk when the file is closed. The cache data is not invalidated, and the next time the file is opened, read accesses can again be serviced immediately from the cache without the need to read the data back into it.

DATA-ATTRIBUTES = *STD / *FROM-FILE(...) / *BY-CATALOG
Specifies whether the *BY-DATA-ATTRIBUTES defaults of the following operands are to be the same as the corresponding file attributes of a cataloged file. The operands which support the importing of file attributes are ACCESS-METHOD, RECORD-FORMAT, RECORD-SIZE, BUFFER-LENGTH, BLOCK-CONTROL-INFO, KEY-POSITION, KEY-LENGTH, LOGICAL-FLAG-LENGTH, VALUE-FLAG-LENGTH, PROPAGATE-VALUE-FLAG, BLOCK-OFFSET, LABEL-TYPE, and CODE.

DATA-ATTRIBUTES = *STD
The *BY-DATA-ATTRIBUTES defaults are the same as the corresponding *BY-PROGRAM operand values.

DATA-ATTRIBUTES = *FROM-FILE(...)
Operands for which *BY-DATA-ATTRIBUTES is specified are assigned the operand value corresponding to the matching file attribute of the named file. If the operand value thus imported initiates a structure, the values of the lower-level operands are likewise set to match the equivalent file attributes. This affects the PRINT-CONTROL, SIZE and DIN-REVISION-NUMBER operands.

FILE-NAME = <filename 1..54>
Name of the file from which the corresponding file attributes are to be imported. The caller must have the authorization to read the file’s catalog entry with SHOW-FILE-ATTRIBUTES. The file must be cataloged on the same pubset as the file to which the ADD-FILE-LINK command refers.

DATA-ATTRIBUTES = *BY-CATALOG
The operand values are taken over as with DATA-ATTRIBUTES=*FROM-FILE(...), namely from the file to which the ADD-FILE-LINK command refers.

RECORD-FORMAT = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *VARIABLE(...) / *FIXED(...) / *UNDEFINED(...)
Specifies the record format of the file identified by FILE-NAME. The block-oriented access method UPAM ignores the RECORD-FORMAT argument. BTAM is also a block-oriented access method, but it does accept specifications in the RECORD-FORMAT operand. *UNDEFINED is treated as if it were *VARIABLE.
The SAM and ISAM access methods interpret the record format argument, except that *UNDEFINED is not allowed with ISAM.

Record formats are completely described in the “Introductory Guide to DMS” [13].

For the relationship between the RECORD-FORMAT and RECORD-SIZE arguments see the description of the RECORD-SIZE operand.

RECORD-FORMAT = *BY-DATA-ATTRIBUTES
The record format of the file specified in the DATA-ATTRIBUTES operand is used. The setting of the print control byte (PRINT-CONTROL) is also copied. If DATA-ATTRIBUTES is *STD, RECORD-FORMAT defaults to *BY-PROGRAM.

RECORD-FORMAT = *BY-PROGRAM
The record format selected in the program is used.

RECORD-FORMAT = *BY-CATALOG
The record format set in the catalog is used.

RECORD-FORMAT = *VARIABLE(...)
The file specified by FILE-NAME consists of variable-length records, which means that the user must bear in mind, when programming, that each record is preceded by a 4-byte field, where bytes 1-2 contain the record length in binary. The bytes 3-4 are used by the system. For input files, the record length field is specified by the system, for output files, this must be done by the user.

PRINT-CONTROL = *NONE / *ASA / *EBCDIC
Identifies the feed control character (see the PRINT-DOCUMENT command, operand DOCUMENT-FORMAT=*TEXT(LINE-SPACING=...)).

PRINT-CONTROL = *NONE
The file specified by FILE-NAME is not a print file; therefore, it does not contain any print control characters and when printed should not be subject to control character evaluation.

PRINT-CONTROL = *ASA
The first data byte in each record is to be interpreted as an ASA feed control character for the printer (print with LINE-SPACING=*BY-ASA-CONTROL in the PRINT-DOCUMENT command).

PRINT-CONTROL = *EBCDIC
The first data byte in each record is to be interpreted as an EBCDIC feed control character for the printer (print with LINE-SPACING=*BY-EBCDIC-CONTROL in the PRINT-DOCUMENT command). With ISAM files the ISAM index is taken into account.

RECORD-FORMAT = *FIXED(...)
The file specified by FILE-NAME consists of fixed-length records, which means that the user does not need to allow for record length and control fields. All the records in the file are of the same length, this length is defined in the RECORD-SIZE operand.

PRINT-CONTROL = *NONE / *ASA / *EBCDIC
Identifies the feed control character (see the PRINT-DOCUMENT command, operand DOCUMENT-FORMAT=*TEXT(LINE-SPACING=...)).

PRINT-CONTROL = *NONE
The file specified by FILE-NAME is not a print file; therefore, it does not contain any print control characters and when printed should not be subject to control character evaluation.

PRINT-CONTROL = *ASA
The first data byte in each record is to be interpreted as an ASA feed control character for the printer (print with LINE-SPACING=*BY-ASA-CONTROL in the PRINT-DOCUMENT command).

PRINT-CONTROL = *EBCDIC
The first data byte in each record is to be interpreted as an EBCDIC feed control character for the printer (print with LINE-SPACING=*BY-EBCDIC-CONTROL in the PRINT-DOCUMENT command). With ISAM files the ISAM index is taken into account.

RECORD-FORMAT = *UNDEFINED(...)
The file specified by FILE-NAME consists of records of “undefined” length; each data block contains a single record, the length of which is passed in a register; the value in this register is set by the system on input and by the user on output (see the RECORD-SIZE operand). RECORD-FORMAT=*UNDEFINED converts the specification LABEL-TYPE=*STD(DIN-REVISION-NUMBER=3) to LABEL-TYPE=*STD(DIN-REVISION-NUMBER=2).

PRINT-CONTROL = *NONE / *ASA / *EBCDIC
Identifies the feed control character (see the PRINT-DOCUMENT command, operand DOCUMENT-FORMAT=*TEXT(LINE-SPACING=...)).

PRINT-CONTROL = *NONE
The file specified by FILE-NAME is not a print file; therefore, it does not contain any print control characters and when printed should not be subject to control character evaluation.

PRINT-CONTROL = *ASA
The first data byte in each record is to be interpreted as an ASA feed control character for the printer (print with LINE-SPACING=*BY-ASA-CONTROL in the PRINT-DOCUMENT command).

PRINT-CONTROL = *EBCDIC
The first data byte in each record is to be interpreted as an EBCDIC feed control character for the printer (print with LINE-SPACING=*BY-EBCDIC-CONTROL in the PRINT-DOCUMENT command). With ISAM files the ISAM index is taken into account.

RECORD-SIZE = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / <integer 0..32768>
With RECORD-FORMAT=*FIXED, the RECORD-SIZE operand specifies the common length of all records in bytes.
With RECORD-FORMAT=*VARIABLE, the value of RECORD-SIZE is ignored. This does not apply to ISAM file reads, where the value in RECORD-SIZE is interpreted as a maximum record length (in bytes); with RECORD-SIZE=0, the length of a logical block is used as the maximum record length. If the program reads a record which is longer than the maximum record length, only the maximum length as defined by RECORD-SIZE is transferred and error handling is initiated.
With RECORD-FORMAT=*UNDEFINED, the value of RECORD-SIZE is interpreted as the number of a general-purpose register (2 <= register <= 12) containing the current record length. On input, the system supplies the register with the record length; on output, the user must supply the value.
With tape files there is a significant interaction with the CODE and LABEL-PROCESSING operands: when used together with CODE=*EBCDIC or LABEL-PROCESSING= *PARAMETERS LABEL=*STD (DIN-REVISION-NUMBER > 1), the RECORD-SIZE operand must have a value <= 9999 (international standard).

RECORD-SIZE = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, RECORD-SIZE defaults to *BY-PROGRAM.

RECORD-SIZE = *BY-PROGRAM
The value specified in the program is set.

RECORD-SIZE = *BY-CATALOG
The record format set in the catalog is used.

RECORD-SIZE = <integer 0..32768>
Specifies the maximum record length in bytes. Note with NK-ISAM files that overflow blocks are generated if the maximum record length is utilized.

BUFFER-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / <integer 1..32768> / *STD(...)
Defines the logical block length. A logical block is the unit of information transmitted to and from the I/O devices as seen by the user calling the access methods.

In the case of disk files, there are interactions with space allocation (CREATE-FILE/MODIFY-FILE-ATTRIBUTES command, SPACE operand) and record length (ADD-FILE-LINK command, RECORD-SIZE operand). In the case of tape files, there is an interaction with the label attributes (ADD-FILE-LINK command, LABEL-TYPE operand). See also table "Tape files: block length and record format" and table at LABEL-TYPE = *STD(...).
Disk files/tape files with standard blocks: data blocks may consist of a number of PAM pages. The system automatically links together the PAM pages which form a transmission unit.

BUFFER-LENGTH = *BY-DATA-ATTRIBUTES
The logical block length of the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, BUFFER-LENGTH defaults to *BY-PROGRAM. If the file consists of standard blocks (BUFFER-LENGTH=*STD), the number of PAM pages (SIZE operand) is also copied from the file.

BUFFER-LENGTH = *BY-PROGRAM
The value set in the program is used.

BUFFER-LENGTH = *BY-CATALOG
The value set in the catalog is used.

BUFFER-LENGTH = <integer 1..32768>
For tape files only: defines the block length in bytes and specifies that the file consists of nonstandard blocks (i.e. blocks which are not PAM blocks). Each nonstandard block is also a logical block.
With RECORD-FORMAT=*FIXED, all nonstandard blocks in the file are of the length specified here (buffer offset not included; see BLOCK-OFFSET operand).
With RECORD-FORMAT=*VARIABLE/*UNDEFINED, the nonstandard blocks may be of differing lengths, with the specified block length defining the upper limit (buffer offset included).

The ACCESS-METHOD and IO-CHAINING operand settings must also be taken into account.

BUFFER-LENGTH = *STD(...)
The file consists of standard PAM pages.

SIZE = 1 / <integer 1..16>
For K files: each logical block consists of the number of PAM blocks specified here. For NK files: each logical block consists of the number of 2048-byte data fields specified here. With NK4 volumes (NK4 files) this number must be even; in other words, the logical block length is a multiple of 4K.
For tape files: if CODE is anything other than EBCDIC, or if BLOCK-CONTROL-INFO is set to *WITHIN-DATA-BLOCK or *NO, STD block specifications are converted to nonstandard block specifications.

RECORD-FORMAT operand

Effects

RECORD-FORMAT=*FIXED

BUFFER-LENGTH specifies the block length including the length of the buffer offset (see BLOCK-OFFSET operand); all blocks are of the same length

RECORD-FORMAT= *VARIABLE/*UNDEFINED

BUFFER-LENGTH specifies the maximum block length including the length of the buffer offset (see the BLOCK-OFFSET operand), so the block length (like the record length) is variable

If RECORD-FORMAT=VARIABLE and CODE=*EBCDIC or LABEL=*STD(DIN-REV-NUM=n) (n> 1), BUFFER-LENGTH must be less than 10000 (internal conversion to record format D)

Table 20: Tape files: block length and record format

ACCESS-METHOD operand	Values allowed for BUFFER-LENGTH
SAM / BTAM	1 <= n <= 32768
UPAM

Table 21: Tape files: block length and access method

BLOCK-CONTROL-INFO = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *NO /
*WITHIN-DATA-BLOCK / *WITHIN-DATA-2K-BLOCK / *WITHIN-DATA-4K-BLOCK / *PAMKEY
Specifies the location of the block control field containing the block control information used for logical block management.
K files have the block format PAMKEY and can only be stored on K volumes.
NK files can have any of the following formats: NO, WITHIN-DATA-BLOCK, WITHIN-DATA-2K-BLOCK, and WITHIN-DATA-4K-BLOCK. They can be stored on N or NK volumes. NK files are subdivided into:

NK2 files, which may have the following structural attributes in the catalog entry:
- FILE-STRUCT = ISAM and BLK-CONTR = DATA (2K)
- FILE-STRUCT = SAM and BLK-CONTR = DATA and BUF-LEN = STD(n), where n is an odd number
- FILE-STRUCT = PAM and BLK-CONTR = DATA or NO and BUF-LEN = STD(n), where n is an odd number
NK2 files cannot be stored on NK4 pubsets.
NK4 files, which may have the following structural attributes in the catalog entry:
- FILE-STRUCT = ISAM and BLK-CONTR = DATA (4K)
- FILE-STRUCT = SAM and BLK-CONTR = DATA and BUF-LEN = STD(n), where n is an even number
- FILE-STRUCT = PAM and BLK-CONTR = DATA or NO and BUF-LEN = STD(n), where n is an even number

If the user does not specify a block format, the system parameter ISBLKCTL defines the block format for an ISAM file when the file is created. The default value is *NONKEY; i.e. by default, ISAM files are created as NK-ISAM on K volumes as well (equivalent to specifying BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK). If *PAMKEY is specified in the system, a K-ISAM file is created (equivalent to BLOCK-CONTROL-INFO=*PAMKEY).

BLOCK-CONTROL-INFO = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, BLOCK-CONTROL-INFO defaults to *BY-PROGRAM.

BLOCK-CONTROL-INFO = *BY-PROGRAM
The value specified in the program is used.

BLOCK-CONTROL-INFO = *BY-CATALOG
The value set in the catalog is used.

BLOCK-CONTROL-INFO = *NO
The block format does not include a PAM key, i.e. the system does not store any block control information in PAM keys.

This block format is allowed for NK files only. It is available only for PAM files and SAM tape files. For SAM disk files and ISAM, *NO is treated in the same way as *WITHIN-DATA-BLOCK.
Functions which used to be linked to data in the PAM key are no longer supported (this typically applies to partial backups using ARCHIVE).

BLOCK-CONTROL-INFO = *WITHIN-DATA-BLOCK
The block format does not include a PAM key, i.e. the system does not store any block control information in PAM keys. This block format is allowed for NK files only. The block control information is within the first twelve bytes of each logical block, except in NK-ISAM files. Incompatibilities arise if the maximum record length (16 PAM blocks = 32K bytes) is used up, as there is no room left for the block control information.

Special features of NK-ISAM files

There are two block formats:

2K format: The block control information is stored at the start of each 2K block (one PAM page). The 2K format can be selected explicitly using BLOCK-CONTROL-INFO=*WITHIN-DATA-2K-BLOCK.
4K format: The block control information is stored at the start of each 4K block (two PAM pages). The 4K format can be selected explicitly using BLOCK-CONTROL-INFO=*WITHIN-DATA-4K-BLOCK.

The block format used to create an NK-ISAM file (OPEN=*OUTPUT/*OUTIN) is governed by the format of the volume on which the file is stored:

K pubset/private disk NK2(6K) pubset/private disk NK2(8K) pubset NK2(64K) pubset	\| \| \| \|	K format (NK2 ISAM file): catalog entry where BLK-CONTR=DATA (2K)

NK2(8K)-Pubset NK2(64K)-Pubset	\| \|	4K Format (NK4 ISAM file): catalog entry where BLK-CONTR=DATA (4K)

Note that it is not possible to create the NK-ISAM file in 4K format unless the logical block length is a multiple of 4K. If this is not the case, any attempt to open the file is rejected as an error.

An existing NK-ISAM can be opened regardless of the block format.

BLOCK-CONTROL-INFO = *WITHIN-DATA-2K-BLOCK
This is a variant of *WITHIN-DATA-BLOCK designed for use with NK-ISAM files. When an NK-ISAM file is created (OPEN=*OUTPUT/*OUTIN), 2K format is generated. Any attempt to open the file for an NK4 volume is rejected as an error. An existing NK-ISAM file can be opened only if it was created in 2K format.

BLOCK-CONTROL-INFO = *WITHIN-DATA-4K-BLOCK
This is a variant of *WITHIN-DATA-BLOCK designed for use with NK-ISAM files.
When an NK-ISAM file is created (OPEN=*OUTPUT/*OUTIN), 4K format is generated. The logical block length must be a multiple of 4K. If this is not the case, any attempt to open the file is rejected as an error.
An existing NK-ISAM file can be opened only if it was created in 4K format.

BLOCK-CONTROL-INFO = *PAMKEY
This value is possible for K files only.
A block format using PAM keys which is supported by all access methods. The block control information is stored in the PAM key.
A file may be created in PAMKEY format provided that the volume supports PAMKEY recording (K pubset or K private disk).

NUMBER-OF-PREMOUNTS = *STD / <integer 0..255>
Number of volumes to be requested for premounting.

NUMBER-OF-PREMOUNTS = *STD
Number of volumes to be requested depends on the volume type

disk files: All disks are requested on which the extent of the file is existing.
tape files: Exactly one tape is requested.

NUMBER-OF-PREMOUNTS = <integer 0..255>
Specifies the number of volumes to premount.

RETENTION-PERIOD = *BY-PROGRAM / <integer 0..32767 days >
This operand allows users to define a retention period for their files.
When the output file is closed, the date on which the retention period expires is calculated from the current data and the length of the retention period. This date is added to the catalog entry as the expiration date. No write access (updating, deletion) to this file is possible until the retention date has been reached.

RETENTION-PERIOD = *BY-PROGRAM
The value specified in the program is used.

RETENTION-PERIOD = <integer 0..32767 days >
The RETENTION-PERIOD operand is effective only if a TFT entry is created using the LINK-NAME operand, and file identified by the FILE-NAME operand is then opened.
The value of RETENTION-PERIOD defines the length of the retention period in days. Expiration of the retention period does not mean that the file will automatically be destroyed, merely that write access will then be granted again.
RETENTION-PERIOD=0 means that there is no retention period and the file can be updated or deleted at any time.
A retention period can also be set with the MODIFY-FILE-ATTRIBUTES command; a retention period specified with that command is added to the catalog entry immediately; but note that for tape files the retention period must be defined before the file is opened for the first time.

SUPPORT = *NONE / list-poss(2): *DISK(...) / *TAPE(...)
Type of volume on which the file is located.

SUPPORT = *NONE
No device specification.

SUPPORT = *DISK(...)
The file to be processed is a disk file.

SHARED-UPDATE = *BY-PROGRAM / *NO / *YES / *WEAK
For ISAM and UPAM disk files only: defines whether write access to the file is to be possible if other jobs open it at the same time (shared updating).

SHARED-UPDATE = *BY-PROGRAM
The value specified in the program is used.

SHARED-UPDATE = *NO
Once one job has opened the file in an OPEN mode other than INPUT, it is locked for all other jobs. Thus shared updating is not possible. The contents of the file remain constant for the duration of file processing. Concurrent access to the file by a number of jobs is not possible unless the file is opened as an input file, i.e. with OPEN INPUT, in all jobs. If the file has already been opened in INPUT mode, any attempt to open it in any other mode is rejected.

SHARED-UPDATE = *YES
For ISAM and PAM files only: the file can be edited concurrently by a number of jobs; but SHARED-UPDATE=*YES must be set in all jobs. With UPAM, users can protect data blocks they are processing against access by other jobs.
With ISAM, these locks are set automatically by the system as required. With NK-ISAM, files opened for shared updating must be processed in cross-task user ISAM pools. With ISAM files the WRITE-IMMEDIATE function is enabled concurrently (WRITE-IMMEDIATE operand set to *YES).

SHARED-UPDATE = *WEAK
For UPAM processing only: guarantees write but not read protection. Only one job can open the file for writing. Other jobs can use it concurrently as an input file, but allowance has to be made for the fact that the contents of the file may change.

LOCK-ENVIRONMENT = *BY-PROGRAM / *HOST-SYSTEM / *XCS
Specifies whether the file can be open for concurrent writing by jobs from different systems, depending on the open mode (OPEN-MODE) and the shared update mode setting (SHARED-UPDATE).

LOCK-ENVIRONMENT = *BY-PROGRAM
The setting specified in the program is used.

LOCK-ENVIRONMENT = *HOST-SYSTEM
The file cannot be open for concurrent writing with SHARED-UPDATE=*YES by jobs from different systems.

LOCK-ENVIRONMENT = *XCS
The file can be open for concurrent writing with SHARED-UPDATE=*YES by jobs from different systems in an XCS network.

EXCEED-32GB = *BY-PROGRAM / *FORBIDDEN / *ALLOWED
Specifies whether the file size may exceed 32 GB during processing.

EXCEED-32GB = *FORBIDDEN
The file may grow to a maximum of 32 GB.

EXCEED-32GB = *ALLOWED
The file may grow beyond 32 GB.

WRITE-CHECK = *BY-PROGRAM / *NO / *YES
Specifies whether records written out to disk are to be checked immediately (read-afterwrite check) so that recording errors are detected promptly. The WRITE-CHECK specification is not added to the catalog entry, so it must be repeated beforehand each time the file is processed or opened.
Read-after-write checking: checking for recording errors (-> error recovery actions). If the error is unrecoverable, control is passed to the EXLST exit ERRADR. Read-afterwrite checking slows down performance considerably on account of the extra disk rotations.

WRITE-CHECK = *BY-PROGRAM
The setting specified in the program is used.

WRITE-CHECK = *NO
No read-after-write checking is done.

WRITE-CHECK = *YES
Read-after-write checking is done.

IO-ATTRIBUTES = *BY-PROGRAM / *PARAMETERS(...)
Specifies the performance requirements demanded by the user for input/output operations. The highest permissible performance attribute is defined in the user entry. The cache medium defined for the associated pubset governs whether and to what extent performance requirements are implemented (see the output of the SHOW-MASTER-CATALOG-ENTRY command). Read and write access is performed through a fast cache. The number of disk accesses and the access times are reduced.

IO-ATTRIBUTES = *BY-PROGRAM
The value specified in the program is used (see the FCB macro description in the “DMS Macros” manual [12]).

IO-ATTRIBUTES = *PARAMETERS(...)
The overall performance requirement is derived from the values specified for the PERFORMANCE and USAGE operands.

PERFORMANCE = *BY-PROGRAM / *BY-CATALOG / *STD / *HIGH / *VERY-HIGH /
*USER-MAXIMUM
Specifies the file’s performance attribute. It indicates the priority required for the I/O operations selected in the USAGE operand. The highest permissible performance attribute is defined in the user entry (see the output of the SHOW-USER-ATTRIBUTES command).

PERFORMANCE = *BY-PROGRAM
The value set in the program is used.

PERFORMANCE = *BY-CATALOG
The value specified in the catalog entry is used.

PERFORMANCE = *STD
There are no special performance attributes for the file, so a cache should not be used to process it.

PERFORMANCE = *HIGH
The file is to be processed through a cache (high performance priority). This specification is only possible for users who have the DMS tuning privilege CONCURRENT-USE or EXCLUSIVE-USE for the pubset (see the output field DMS-TUNING-RESOURCES in the output of the SHOW-USER-ATTRIBUTES command).

PERFORMANCE = *VERY-HIGH
The file is to be processed through a cache. The referenced data in the file is to be kept permanently in the cache (highest performance priority). The cache data is only evicted from the cache when the file is closed. The specification is only possible for users who have the DMS tuning privilege EXCLUSIVE-USE for the pubset (see the output for the SHOW-USER-ATTRIBUTES command, output field DMS-TUNING-RESOURCES).

Note

All cache segments used for this file are locked until the file is closed. If there are many files open with this attribute at the same time, the cache memory available for normally cached files may, as a result, be so greatly restricted that data accesses to such files can no longer be implemented with an adequate level of performance.

PERFORMANCE = *USER-MAXIMUM
The file is assigned the highest performance attribute contained in the user catalog for the user.

USAGE = *BY-PROGRAM / *BY-CATALOG / *READ-WRITE / *WRITE / *READ
Specifies the I/O operations for which enhanced performance (caching) is required. The default setting is *READ-WRITE, i.e. the requirements apply to read and write operations. If the file does not have a particular performance attribute (PERFORMANCE= *STD) and if the cache area for the pubset is not defined in such a way that all existing files are served (see the operand CACHED-FILES=*ALL for the MODIFY-PUBSET-CACHING-ATTRIBUTES command), then the USAGE operand has no effect on processing.

USAGE = *BY-PROGRAM
The value specified in the program is used (see the FCB macro description in the “DMS Macros” manual [12]).

USAGE = *BY-CATALOG
The value specified in the catalog entry is used.

USAGE = *READ-WRITE
The performance requirements apply both to read and to write operations.

USAGE = *WRITE
The performance requirements apply to write operations only.

USAGE = *READ
The performance requirements apply to read operations only.

Note

With USAGE=*READ-WRITE or *WRITE, write caching is performed only if the conditions for the DISK-WRITE file attributes are met (see CREATE-FILE or MODIFY-FILE-ATTRIBUTES). For write caching with DISK-WRITE= *IMMEDIATE, the cache medium being used must be failsafe (see the CACHE-MEDIUM output field of the SHOW-MASTER-CATALOG-ENTRY command with INFORMATION=*USER).

ISAM-ATTRIBUTES = *BY-PROGRAM / *PARAMETERS(...)
Parameters relating to ISAM processing.

ISAM-ATTRIBUTES = *BY-PROGRAM
Information relating to ISAM-specific features is taken from the program or from the file specified in the DATA-ATTRIBUTES operand.

ISAM-ATTRIBUTES = *PARAMETERS(...)
Information relating to ISAM-specific features is derived from the values specified for the operands which follow.

KEY-POSITION = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /
<integer 1..32767>
Specifies the position of the ISAM key within the record. In variable-length records, allowance must be made for a 4-byte record length and control field. There is no fixed position for ISAM keys, but the key must always be in the same position throughout a file.

KEY-POSITION = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, KEY-POSITION defaults to *BY-PROGRAM.

KEY-POSITION = *BY-PROGRAM
The value specified in the program is used (see the FCB macro description in the “DMS Macros” manual [12]).

KEY-POSITION = *BY-CATALOG
The value set in the catalog is used.

KEY-POSITION = <integer 1..32767>
Specifies the position of the ISAM key within the record.

KEY-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / <integer 1..255>
Length of the ISAM key in bytes. Each record in the file must use the specified key length. The sum of the lengths specified in KEY-LENGTH, LOGICAL-FLAG-LENGTH, and VALUE-FLAG-LENGTH must not come to more than 255 during processing.

KEY-LENGTH = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, KEY-LENGTH defaults to *BY-PROGRAM.

KEY-LENGTH = *BY-PROGRAM
The value specified in the program is used.

KEY-LENGTH = *BY-CATALOG
The value set in the catalog is used.

KEY-LENGTH = <integer 1..255>
Specifies the length of the ISAM key in bytes.

VALUE-FLAG-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /
<integer 0..255>
For K-ISAM files only: defines the length (in bytes) of the value flag in the ISAM index. This flag may form part of the ISAM record index together with the ISAM key and the logical flag. The sum of the lengths specified in KEY-LENGTH, LOGICAL-FLAG-LENGTH, and VALUE-FLAG-LENGTH must not come to more than 255 during processing.

VALUE-FLAG-LENGTH = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, VALUE-FLAG-LENGTH defaults to *BY-PROGRAM.

VALUE-FLAG-LENGTH = *BY-PROGRAM
The value set in the program is used.

VALUE-FLAG-LENGTH = *BY-CATALOG
The value set in the catalog is used.

VALUE-FLAG-LENGTH = <integer 0..255>
VALUE-FLAG-LENGTH = 0: the ISAM index does not include a value flag.

There is a difference in the treatment of value flags in NK-ISAM (BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK) and K-ISAM (BLOCK-CONTROL-INFO=*PAMKEY).
In K-ISAM they are evaluated block by block and propagated to the next higher index entry, as specified in the PROPAGATE-VALUE-FLAG operand.
In NK-ISAM no flags are evaluated for the index entry.

Note

If the “secondary key” function is used, the ISAM key must not include a value flag.

PROPAGATE-VALUE-FLAG = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *MINIMUM / *MAXIMUM / *BY-CATALOG
For K-ISAM files only (BLOCK-CONTROL-INFO=PAMKEY): defines how the value flag is to be propagated to the index entries.
(NK-ISAM ignores PROPAGATE-VALUE-FLAG specifications)

PROPAGATE-VALUE-FLAG = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, PROPAGATE-VALUE-FLAG defaults to *BY-PROGRAM.

PROPAGATE-VALUE-FLAG = *BY-PROGRAM
The value specified in the program is used (see the FCB macro description in the “DMS Macros” manual [12]).

PROPAGATE-VALUE-FLAG = *MINIMUM
The lowest value for the value flag within a data or index block is propagated to the next higher level.

PROPAGATE-VALUE-FLAG = *MAXIMUM
The highest value of the flag in the data/index block is propagated.

PROPAGATE-VALUE-FLAG = *BY-CATALOG
The value specified in the catalog entry is used.

LOGICAL-FLAG-LENGTH = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /
<integer 0..255>
For K-ISAM files only: defines the length in bytes of a logical flag in the ISAM index; the maximum length is governed by the length of the ISAM key, in that the sum of the lengths specified in KEY-LENGTH, LOGICAL-FLAG-LENGTH, and VALUE-FLAG-LENGTH must not come to more than 255 during processing.

LOGICAL-FLAG-LENGTH = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, LOGICAL-FLAG-LENGTH defaults to *BY-PROGRAM.

LOGICAL-FLAG-LENGTH = *BY-PROGRAM
The value specified in the program is used (see the FCB macro description in the “DMS Macros” manual [12]).

LOGICAL-FLAG-LENGTH = *BY-CATALOG
The value specified in the catalog entry is used.

LOGICAL-FLAG-LENGTH = <integer 0..255>
LOGICAL-FLAG-LENGTH=0: The ISAM index contains no logical flag. The ISAM key in the ISAM index may be followed by a logical flag in which selection criteria are defined bit by bit and encoded in binary. In K-ISAM files, all the logical flags of a block are evaluated and the result is propagated to the next higher index entry. There is no logical flag evaluation with NK-ISAM files.

Note

If the “secondary key” function is used, the ISAM key must not include a logical flag.

PADDING-FACTOR = *BY-PROGRAM / <integer 0..99>
Only for ISAM files created sequentially: the block padding factor specifies how much space to keep free in the data block for subsequent extension of the file (as a percentage of the block length defined in BUFFER-LENGTH). The PADDING-FACTOR specification thus affects the block splitting rate when a file is extended nonsequentially.
K-ISAM requests a new logical block for the current record if the free space would otherwise fall below the padding factor.
NK-ISAM does not request a new logical block until the free space has already fallen below the padding factor.

PADDING-FACTOR = *BY-PROGRAM
The value specified in the program is used.

PADDING-FACTOR = <integer 0..99>
A PADDING-FACTOR specification has different effects on NK-ISAM and K-ISAM. For NK-ISAM the block is filled at least up to the specified padding limit, for K-ISAM at most up to the padding limit.

POOL-LINK = *BY-PROGRAM / <name 1..8>
Only for ISAM files process in ISAM pools (NK-ISAM): specifies the pool link name to be recorded in the TFT.
The file blocks required for processing are transferred from disk to the ISAM pool and buffered there.

POOL-LINK = *BY-PROGRAM
The pool link name specified in the program is used.

POOL-LINK = <name 1..8>
At OPEN time the pool link name is passed to NK-ISAM. This name must have been allocated using the ADD-ISAM-POOL-LINK command to an ISAM pool created with the CREATE-ISAM-POOL command.

POOL-SIZE = *BY-PROGRAM / <integer 128..1048576 2Kbyte >
For NK-ISAM files:
Determines the size of the file-specific ISAM pool in units of 2048 bytes. The specification does not relate to the ISAM pool addressed with POOL-LINK.

WRITE-IMMEDIATE = *BY-PROGRAM / *NO / *YES
Controls how updated blocks are written out to disk.
WRITE-IMMEDIATE=*YES applies implicitly to shared updating and to cross-task ISAM pools, which means that updated blocks are always written out to disk immediately.

WRITE-IMMEDIATE = *BY-PROGRAM
The value specified in the program is used.

WRITE-IMMEDIATE = *NO
An updated block is not written out to disk until the contents of the associated buffer area need to be replaced or the file is closed.

WRITE-IMMEDIATE = *YES
Each updated block is written out to disk immediately, thus ensuring consistency at all times between the data on disk and in virtual memory. The downside is a higher I/O frequency.

READ-IN-ADVANCE = *BY-PROGRAM / *YES / *NO
Specifies whether I/Os should be overlapped.

READ-IN-ADVANCE = *BY-PROGRAM
The setting defined in the program is used.

READ-IN-ADVANCE = *YES
If a second I/O area is defined in the program, read operations can be overlapped. With NK-ISAM, “overlapped processing” means that adjacent blocks are also read into the ISAM pool. READ-IN-ADVANCED =*YES should be used only for reads which are primarily sequential.
With K-ISAM, “overlapped processing” means that if two I/O buffers are specified in the FCB a block can be read from one buffer to the other in the course of a read operation.

READ-IN-ADVANCE = *NO
Reads are not overlapped.

DUPLICATE-KEY = *BY-PROGRAM / *YES / *NO
Specifies whether the same ISAM key is allowed to occur more than once when records are being added using PUT or STORE macros.

DUPLICATE-KEY = *BY-PROGRAM
The value defined in the program is used.

DUPLICATE-KEY = *YES
If a number of records have the same ISAM key, they do not overwrite each other but are written one after the other in the order of their creation. With NK-ISAM, records with identical keys have an 8-byte timestamp added to them internally. This must be allowed for when defining the record length.
See the section on overflow blocks in the “Introductory Guide to DMS” [13].

DUPLICATE-KEY = *NO
If the record being added has an ISAM key which has already occurred, the PUT macro causes the program to branch to the EXLST “DUPEKY” exit, while the STORE macro causes the existing record to be overwritten.

SUPPORT = *TAPE(...)
The file to be processed is a tape file.

VOLUME-LIST = *CATALOG(...) / *TEMPORARY (...) / *TAPE-SET (...)
Specifies the volume serial numbers (VSNs) of the tapes which are to be processed. With work files (DEVICE-TYPE= *WORK), the ADD-CATALOG-VOLUME operand is ignored and the TAPE-SET-NAME operand is rejected.

VOLUME-LIST = *CATALOG(...)
The VSNs from the volume table in the catalog entry are transferred to the volume list.

ADD-CATALOG-VOLUME = *NONE / *ANY (...) / list-poss(255): <alphanum-name 1..6>
This operand is ignored for work files (DEVICE-TYPE=*WORK).
As well as the VSNs from the volume table in the catalog entry, other VSNs can be added to the volume list. These VSNs are then also added to the volume table in the catalog entry.

ADD-CATALOG-VOLUME = *NONE
No other VSNs are added to the volume list.

ADD-CATALOG-VOLUME = *ANY (...)
The selection of VSNs is made either by the operating personnel (in response to a console message) or, where available, by the MAREN utility.
This specification is ignored for the dummy file *DUMMY.

NUMBER-OF-DEVICES = 1 / <integer 1..9>
Number of extra VSNs to add to the volume list.

ADD-CATALOG-VOLUME = list-poss (255): <alphanum-name 1..6>
Extra VSNs to add to the volume list.

VOL-SEQUENCE-NUMBER = *NONE / *FROM-START-POSITION (...) /
list-poss (255): <integer 1..255>
Defines which VSNs from the volume list are to be added to the volume table in the TFT entry and which order to add them in. This order has a significant impact on the subsequent processing of the file.

VOL-SEQUENCE-NUMBER = *NONE
All the VSNs in the volume list are added to the volume table in the TFT entry.

VOL-SEQUENCE-NUMBER = *FROM-START-POSITION (...)
Indicates that VSNs from the volume table are to be added to the volume table in the TFT entry starting from a specified VSN.

START-POSITION = <integer 1..255>
All VSNs from the specified position onwards are added to the volume table in the TFT entry.

VOL-SEQUENCE-NUMBER = list-poss (255): <integer 1..255>
Selected VSNs in the volume list which are to be added to the volume table in the TFT entry. A number given here (such as 12) refers to the position of a VSN in the volume list (in this case the twelfth VSN). Thus the number entered here is the file section number.

VOLUME-LIST = *TEMPORARY(...)
The volume table of the existing catalog entry remains unchanged and is ignored while the file is being processed.

PROCESS-VOLUME = list-poss (255): <alphanum-name 1..6>
Defines a temporary list of VSNs for processing. This list forms the volume list and the volume table of the generated TFT entry.

VOLUME-LIST = *TAPE-SET(...)
This operand is rejected for work files (DEVICE-TYPE=*WORK).
Selects the tape file VSN set which was created or extended using CREATE- or EXTEND-TAPE-SET. The catalog entry must not yet have any VSNs in its volume table. The volume list is formed from the VSNs of a TST entry. All the VSNs in the volume list are added to the volume table of the catalog entry and to the volume table of the TFT entry.

TAPE-SET-NAME = <alphanum-name 1..4>
A maximum of 255 VSNs from the specified TST entry is added to the volume list, starting at the current VSN. The TFT entry which is generated is linked to the specified TST entry. If this TST entry does not exist, a TST entry is created with the specified name and an empty volume list. The final tape sequence for the (output) file is not fixed until OPEN processing is initiated. A reference to a tape set is allowed only for output files with standard labels.

FILE-SET-IDENTIFIER = *BY-TAPE-SET / <alphanum-name 1..6>
File set identifier of the TST entry. The VSN given here must match the file set identifier in the TST entry.

FILE-SET-IDENTIFIER = *BY-TAPE-SET
The file set identifier is defined by the TST entry.

FILE-SET-IDENTIFIER = <alphanum-name 1..6>
The VSN given here must match the file set identifier in the TST entry.

DEVICE-TYPE = *ANY / <device>
Device type for the required tapes. Only device types or volume types known within the system are accepted. In interactive mode, the possible device and volume types are displayed with DEVICE-TYPE=?.
If a volume type of WORK is specified, a work tape is made available when the file is opened.

LABEL-PROCESSING = *BY-PROGRAM / *PARAMETERS(...)
Label processing options.

LABEL-PROCESSING = *BY-PROGRAM
The settings specified in the program are used.

LABEL-PROCESSING = *PARAMETERS(...)
The values set in the operands which follow are used.

LABEL-TYPE = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *NO / *NON-STD / *STD(...)
File label type. For existing tape files, the label standard specified in the VOL1 label always applies. For output files (OPEN OUTIN/OUTPUT) the LABEL-TYPE operand is evaluated and the label standard in the VOL1 label is defined or modified accordingly.

LABEL-TYPE = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, LABEL-TYPE defaults to *BY-PROGRAM.

LABEL-TYPE = *BY-PROGRAM(...)
The values defined in the program are used.

LABEL-TYPE = *NO
No file labels are read or written (no file label processing). If the tape has standard labels, the system processes the tape labels and checks for access authorization.

LABEL-TYPE = *NON-STD
The tape file has/is given nonstandard labels; file label processing is done in the user program. If the volume has standard labels, the system performs tape label processing and checks for access authorization.

LABEL-TYPE = *STD(...)
Selects standard labels for the file. The volumes containing the file must also have standard labels.

DIN-REVISION-NUMBER = *BY-PROGRAM / <integer 0..3>
The file and the volume have/are given standard labels conforming to the designated interchange level of DIN standard 66029.

0:	only 2 HDR labels are generated (oldest standard label format; old BS2000 or BS1000 or IBM)
1:	DIN standard 66029 dated August 1972
2:	DIN standard 66029 dated June 1976
3:	DIN standard 66029 dated May 1979

If the tape already contains files or file sections, the value specified here must be compatible with the label standard in the VOL1 label.

	*LABEL=STD(DIN-REVISION-NUMBER=...)**
	0	1	2	3
DIN 66029 interchange level Edition	-	1 8/1972	2 6/1976	3 3/1978
Label standard in VOL1 label	'BLANK' (blank)	1	2	3
CODE=ISO-7/ OWN	not allowed	STD blocks converted to nonstandard blocks	STD blocks converted to nonstandard blocks	STD blocks converted to nonstandard blocks
		REC-FORM=V: conversion to record format D	REC-FORM=V: conversion to record format D	REC-FORM=V: conversion to record format D
		REC-SIZE> 9999 or BUF-LEN> 9999 OPEN error	REC-SIZE> 9999 or BUF-LEN> 9999 OPEN error	REC-SIZE> 9999 or BUF-LEN> 9999 OPEN error
CODE=*EBCDIC			STD blocks converted to nonstandard blocks	STD blocks converted to nonstandard blocks
Access method			SAM only	SAM only
RECORD-FORMAT = *UNDEFINED				not allowed for output files; converted to DIN-REV-NUM=2

Table 22: Effect of the LABEL=*STD(DIN-REV-NUM=...) operand

Restrictions

DIN-REVISION-NUMBER=1 is assumed for:

- RECORD-FORMAT=*VARIABLE and CODE=*EBCDIC
- BUFFER-LENGTH=*STD(...)
- ACCESS-METHOD=*UPAM or ACCESS-METHOD=*BTAM
If DIN-REVISION-NUMBER is 0, CODE must be *EBCDIC.
If the number in the label standard indicator (VOL1 label) is lower than the number given in the DIN-REVISION-NUMBER operand, the label standard indicator number applies.
In all other cases: DIN-REVISION-NUMBER=3 applies (e.g. with CODE=*ISO7 and RECORD-FORMAT=*VARIABLE).

For a file opened in INPUT, INOUT, EXTEND or REVERSE mode, the system ignores the number specified here and refers to the number (label standard indicator) given in the volume label (VOL1).
For an output file, the significant number is the number given here or, if only *STD is specified, the most recent number; but note the following:
If the allocated volume already contains one or more files or file sections, the number must match the label standard indicator in the first volume label. Otherwise, the label standard indicator will be set according to the specified number.
This if a volume already contains one or more files or file sections and the label standard indicator in the first volume label is lower than the implicitly assumed standard version (number), the version number is taken from the volume label.

BYPASS-LABEL-CHECK = *BY-PROGRAM / *NO-POSITIONING /
*ABSOLUTE-POSITIONING(...) / *FORWARD-POSITIONING(...) / *BACKWARD-POSITIONING(...)
Allows users with the appropriate authorization in their user entry (see the TPIGNORE output field of the SHOW-USER-ATTRIBUTES command) to bypass label checking so as to process tapes which were written on other operating systems or which have a structure and a label format that the system does not recognize. Code checking is also bypassed. If the tape is written in a code other than EBCDIC or ISO, the user must work with a dedicated code table (CODE= *OWN). A BYPASS-LABEL-CHECK specification applies only for the duration of file processing; it is not added to the catalog.

BYPASS-LABEL-CHECK = *BY-PROGRAM
The setting which applies in the program is used.

BYPASS-LABEL-CHECK = *NO-POSITIONING
Label handling is bypassed; header labels are not read or check; the tape position is not changed.

BYPASS-LABEL-CHECK = *ABSOLUTE-POSITIONING(...)
Absolute positioning. The tape is transported to the tape mark indicated in the next parameter. Counting from the tape start.

TAPE-MARK-NUMBER = <integer 0..32767>
Number of the tape mark to transport the tape to. TAPE-MARK-NUMBER = 0: position at the tape start.

BYPASS-LABEL-CHECK = *FORWARD-POSITIONING(...)
Forward positioning. The tape is wound forward by the number of tape marks indicated in the next parameter. Counting relative to the current tape position. No label checking is done.

NUMBER-OF-TAPE-MARKS = <integer 0..127>
Number of tape marks by which the tape is to be forwarded when the file is opened. NUMBER-OF-TAPE-MARKS = 0: the tape is not repositioned.

BYPASS-LABEL-CHECK = *BACKWARD-POSITIONING(...)
Backward Positioning. The tape is wound back by the number of tape marks indicated in the next parameter. Counting relative to the current tape position. No label checking is done.

NUMBER-OF-TAPE-MARKS = <integer 0..127>
Number of tape marks by which the tape is to be reversed when the file is opened. NUMBER-OF-TAPE-MARKS=0: the tape is not repositioned.

PROTECTION-LEVEL = *BY-PROGRAM / *LOW(...) / *HIGH(...)
Protection level (level of security) that label checking is to provide. Affects file processing in batch mode only. This operand is allowed only for tape or files with standard labels.

PROTECTION-LEVEL = *BY-PROGRAM
The setting selected in the program is used.

PROTECTION-LEVEL = *LOW(...)
If file processing is running in batch mode under the ID of the system administrator or the tape or file owner and appropriate authorization is allocated in the user entry (see the TPIGNORE output field of the SHOW-USER-ATTRIBUTES command), certain label processing error messages are suppressed.

OVERWRITE-PROTECTION = *NO / *YES
Indicates whether any other label checks are to be performed in addition to write protection.

OVERWRITE-PROTECTION = *NO
No other label checks are to be performed in addition to write protection.

OVERWRITE-PROTECTION = *YES
The system performs additional checks:

- - If a new tape file is placed after an existing file on the tape, the labels of the preceding file are checked.
  - the expiration date of the new file must not be later than that of the preceding file.
  - ACCESS=READ must not be declared for the new file if ACCESS=WRITE has been declared for the preceding file.

PROTECTION-LEVEL = *HIGH(...)
Error messages are displayed on the console in batch mode. If the job is running under a user ID with TPIGNORE=YES authorization in the user catalog, operating personnel may ignore the error messages.

OVERWRITE-PROTECTION = *NO / *YES
See the PROTECTION-LEVEL=*LOW operand.

TAPE-MARK-WRITE = *BY-PROGRAM / *YES
Only for tape files without standard labels: specifies whether tape marks are written, i.e. the TAPE-MARK-WRITE operand is evaluated only when a tape file with LABEL set to *NO or *NON-STD is opened. Tape files with LABEL set to *STD (DIN-REV-NUM=n) are by default given tape marks after the labels.

TAPE-MARK-WRITE = *BY-PROGRAM
The value set in the program is used.

TAPE-MARK-WRITE = *YES
There is a tape mark after the label. Tape files without labels: the tape mark is placed at the start of the tape.

CODE = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG / *EBCDIC / *ISO7 / *ISO7D / *OWN
For SAM or BTAM tape files: code in which the data and labels of the file are processed. Code translation is possible only for files with nonstandard blocks and may modify the record length field on output in locate mode. The value of the EBCDIC-TRANSLATION operand must be taken into account.

CODE = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, CODE defaults to *BY-PROGRAM.

CODE = *BY-PROGRAM
The setting which applies in the program is used.

CODE = *BY-CATALOG
The setting defined in the catalog entry is used.

CODE = *EBCDIC
No code translation is required during processing.

Note

The German and international character sets use the same coding. Differences in the presentation may be caused by different character set settings of the terminal emulation. The same applies to CODE=*ISO7.

CODE = *ISO7
The tape file is written in ISO 7-bit code, which means that EBCDIC code is converted to ISO 7-bit on output and ISO 7-bit code is converted to EBCDIC on input. Code conversion is based on the international ISO table.

Notes

- - The block length must be given in the form BUFFER-LENGTH=<integer 1..32767>, as otherwise the output blocks will be preceded by a (hexadecimal) PAM key. The same applies to CODE=*OWN.
  - For output in locate mode with variable record format (RECORD FORMAT= *VARIABLE), the contents of the record length field (i.e. the first four bytes) are modified. In move mode, the record length field is not modified. The same applies to CODE=*OWN.
  - The German and international character sets use the same coding. Differences in the presentation may be caused by different character set settings of the terminal emulation. The same applies to CODE=*EBCDIC.

CODE = *ISO7D
Code conversion is as for CODE=*ISO7. It is, however, based on the German ISO table rather than the international version.

CODE = *OWN
All tape I/O is performed on the basis of user-defined code translation tables. The addresses of these tables must have been defined in the file control block (FCB) of the program (using the TRTADR and TRTADW parameters in the FCB macro call).

Notes

- - The block length must be given in the form BUFFER-LENGTH=<integer 1..32767>, as otherwise the output blocks will be preceded by a (hexadecimal) PAM key. The same applies to CODE=*ISO7.
  - For output in locate mode with variable record format (RECORD FORMAT= *VARIABLE), the contents of the record length field (i.e. the first four bytes) are modified. In move mode, the record length field is not modified. The same applies to CODE=*ISO7.

EBCDIC-TRANSLATION = *BY-PROGRAM / *YES / *NO
Only for tape files used as input files and not created using CODE= *EBCDIC: defines how the code in the file is to be translated when the file is read.

EBCDIC-TRANSLATION = *BY-PROGRAM
The setting selected in the program is adopted.

EBCDIC-TRANSLATION = *YES
ISO 7-bit code or OWN code is translated to EBCDIC.

EBCDIC-TRANSLATION = *NO
No translation to EBCDIC. ISO 7-bit code is translated to an 8-bit format with a leading zero.

FILE-SEQUENCE = *BY-PROGRAM / *BY-CATALOG / *UNKNOWN / *NEW / <integer 0..9999>
Specifies the sequence number of a tape file within a file set. If there are several files of the same name on a tape, access is under FILE-SEQUENCE control. The same applies to MF/MV sets. If the VOLUME-LIST *TAPE-SET(...) operand is also set, only FILE-SEQUENCE=*NEW or FILE-SEQUENCE=1 is allowed.

FILE-SEQUENCE = *BY-PROGRAM
The value set in the program is used.

FILE-SEQUENCE = *BY-CATALOG
If there is a file sequence number in the catalog entry, it is transferred to the TFT entry. If not, no file sequence number is added to the catalog entry, and *BY-CATALOG is added to the TFT entry.

FILE-SEQUENCE = *UNKNOWN
If there is a file sequence number in the catalog entry, it is transferred to the TFT entry. If not, no file sequence number is added to the catalog entry, and *UNKNOWN is added to the TFT entry. The effect of this on a foreign tape file with standard labels is that, when an attempt is made to open the file, the tape is searched for the file and positioned accordingly.

FILE-SEQUENCE = *NEW
Allowed only for files which have been opened (OPEN OUTPUT) but not yet actually created. This operand adds a new file to an existing file set. The tape is transported to the end of the file set, and the new file is written after the last existing file in the set. The system reports an OPEN error if it fails to find the end of the file set. The sequence number of the new file is the sequence number of the old last file plus 1. If there is no file on the tape at the time the file is opened, the file is made the first in the file set and accordingly assigned a file sequence number of 1.

FILE-SEQUENCE = <integer 0..9999>
Specifies the sequence number of a file with a file set; FILE-SEQUENCE=0, like FILE-SEQUENCE=1, designates the first file in the set. If the file has already been cataloged with the creation date, the file sequence number that the user specifies must match the number which appears in the catalog entry.
If a new file is to be created, it is appended to the end of the file set, which means that the file sequence number must be 1 higher than the last existing file in the file set.

Note

If the sequence number of an existing file in the file set is specified, the existing file will be overwritten.

CHECKPOINT-WRITE = *BY-PROGRAM / *PARAMETERS(...)
Controls whether and when a checkpoint is automatically written at the volume end.

CHECKPOINT-WRITE = *BY-PROGRAM
The setting selected in the program is adopted.

CHECKPOINT-WRITE = *PARAMETERS(...)

CHKPT-AT-BLOCK-LIMIT = *BY-PROGRAM
The setting selected in the program is adopted.

CHKPT-AT-BLOCK-LIMIT = *YES
A checkpoint is written automatically when the maximum number of logical blocks per tape as defined in the BLOCK-LIMIT operand is reached.

CHKPT-AT-FORCED-EOV = *BY-PROGRAM
The setting selected in the program is adopted.

CHKPT-AT-FORCED-EOV = *YES
Checkpoint at forced end of the volume. A checkpoint is written automatically in response to each FEOV macro call in the Assembler program.

RESTART-USAGE = *BY-PROGRAM / *DUMMY
Indicates whether, in the event of a restart (RESTART-PROGRAM command), the file specified in the FILE-NAME operand is to continue being processed or is to be treated as a DUMMY file.

RESTART-USAGE = *BY-PROGRAM
The setting selected in the program is adopted.

RESTART-USAGE = *DUMMY
In the event of a restart, the file is treated as a DUMMY file.

BLOCK-LIMIT = *BY-PROGRAM / <integer 1..999999>
Only when creating SAM tape files with standard labels: maximum number of logical blocks of the file per tape.

BLOCK-LIMIT = *BY-PROGRAM
The setting selected in the program is adopted.

BLOCK-LIMIT = <integer 1..999999>
Specifies how many logical data blocks are allowed to be written on one tape. Once this limit is reached, tape swapping is initiated (EOV processing). The user is sent an error message if the end of the tape is reached before the number of blocks specified by BLOCK-LIMIT has been written.

BLOCK-OFFSET = *BY-DATA-ATTRIBUTES / *BY-PROGRAM / *BY-CATALOG /
*BY-HDR2 / <integer 0..99 byte >
Only for SAM tape files with BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK or SAM tape files with nonstandard blocks: defines the buffer offset, i.e. the length in bytes of a field inserted at the start of each logical data block. If present, this field contains the block control information/block length field.

BLOCK-OFFSET = *BY-DATA-ATTRIBUTES
The value defined for the file specified in the DATA-ATTRIBUTES operand is used. If DATA-ATTRIBUTES is *STD, BLOCK-OFFSET defaults to *BY-PROGRAM.

BLOCK-OFFSET = *BY-PROGRAM
The value set in the program is used.
If there is no value set in the program, the following defaults apply:

- - tape file with BLOCK-CONTROL-INFO=*WITHIN-DATA-BLOCK:

- - - BLOCK-OFFSET=16 applies with ACCESS-METHOD=*SAM
    - BLOCK-OFFSET=12 applies with ACCESS-METHOD=*UPAM
  - tape file with BLOCK-CONTROL-INFO=*NO:
    - BLOCK-OFFSET=4 applies with RECORD-FORMAT=*VARIABLE
    - BLOCK-OFFSET=0 applies with RECORD-FORMAT=*FIXED/*UNDEFINED

BLOCK-OFFSET = *BY-CATALOG
The value set in the catalog is used.

BLOCK-OFFSET = *BY-HDR2
The BLOCK-OFFSET value is taken from the HDR2 label. If there is no HDR2 label, or if the “buffer offset” field in the HDR2 label contains blanks (X’4040’), the default is used (see *BY-PROGRAM).

BLOCK-OFFSET = <integer 0..99 byte >
Specifies the length of the buffer offset.
For variable-length records (RECORD-FORMAT=*VARIABLE) the buffer offset may have a length between 0 and 4 bytes. If BLOCK-OFFSET=4 is set, this field contains the current block length.

TAPE-WRITE = *BY-PROGRAM / *DEVICE-BUFFER / *IMMEDIATE
Only for files on tape cartridges (CREATE-FILE/MODIFY-FILE-ATTRIBUTES command, DEVICE-TYPE operand): defines whether the output is to be buffered.

TAPE-WRITE = *BY-PROGRAM
The value specified in the program is used.

TAPE-WRITE = *DEVICE-BUFFER
Output is buffered by the device controller, resulting in a high data transfer rate.

TAPE-WRITE = *IMMEDIATE
Output is not buffered.

DESTROY-OLD-CONTENTS = *BY-CATALOG / *NO / *YES
The user can specify whether other files on the tape are to be destroyed by overwriting after EOF/EOV processing. The operand has the same function as the DESTROY parameter in the catalog entry, but it takes precedence over the catalog entry created by the CREATE-FILE or MODIFY-FILE-ATTRIBUTES command, DESTROY-BY-DELETE operand. Values specified for this operand are not transferred to the FCB or the catalog entry.

DESTROY-OLD-CONTENTS = *BY-CATALOG
When the file is processed, the value assigned to DESTROY-BY-DELETE in the catalog entry takes effect.

DESTROY-OLD-CONTENTS = *NO
The old contents are not destroyed.

DESTROY-OLD-CONTENTS = *YES
The data on the remainder of the tape is destroyed once the EOF/EOV labels have been written.

IO-CHAINING = *BY-PROGRAM / <integer 1..16>
Only for BTAM files and chained I/O: defines the number of logical blocks per transport unit (chaining factor specifying the of the I/O transport unit/transmission unit).

IO-CHAINING = *BY-PROGRAM
The value specified in the program is used.

IO-CHAINING = <integer 1..16>
Designates a number of logical blocks such that the length of the transport unit is computed as (IO-CHAINING ✕ BUFFER-LENGTH). Although specifications in the program (BTAM macro, LEN operand) take precedence over the product (IO-CHAINING ✕ BUFFER-LENGTH), IO-CHAINING must be specified in the ADD-FILE-LINK command if chained I/O is used.

FILE-CLOSE-MSG = *STD / *NO / *YES
For SAM files the user can specify whether the close message DMS0DE7 is to be written to SYSOUT on completion of CLOSE processing. If system parameter CONSDDE7=Y is set, the message is also output on the console.

FILE-CLOSE-MSG = *STD
The following default applies:

for tape disk files: FILE-CLOSE-MSG = *NO
for tape files: FILE-CLOSE-MSG = *YES

FILE-CLOSE-MSG = *NO
The file close message is suppressed.

FILE-CLOSE-MSG = *YES
The file close message is sent.

Return codes

SC1	Maincode	Meaning/Guaranteed messages
0	CMD0001	Command executed successfully
1	CMD0202	Syntax or semantic error
1	DMS0576	Invalid operand combination
32	DMS0584	A state that does not allow the function to continue was reported during processing
32	DMS05C7	Unexpected internal error in DMS
64	CMD0216	Required authorization not available
64	DMS0501	Requested catalog not available
64	DMS0512	Requested catalog not found
64	DMS051B	Requested user ID not in pubset Guaranteed messages: DMS051B, DMS0681
64	DMS051C	User not authorized to access pubset Guaranteed messages: DMS051C, DMS0681
64	DMS0535	Specified file not shareable
64	DMS0585	Error detected when processing catalog or multiprocessor system.
64	DMS0586	It is not possible to access or reserve a volume at present
64	DMS0587	Use of the specified command has been restricted by the system administrator
64	DMS05FC	Specified user ID not in HOME pubset
64	DMS060D	Invalid reference file name
64	DMS0616	Volume set in SM pubset cannot be accessed
64	DMS0684	File does not exist Guaranteed message: DMS0684
64	DMS0685	File not yet allocated storage space
64	DMS06FF	BCAM connection severed
130	DMS0524	System address space exhausted
130	DMS053C	No space in pubset catalog file
130	DMS0582	File is currently locked or being used and cannot be processed
130	DMS0585	Error detected when processing catalog or multiprocessor system.
130	DMS0586	It is not possible to access or reserve a volume at present
130	DMS0594	Not enough virtual memory available
130	DMS05C8	CE limit reached

Examples

Example 1: Creating a TFT entry with values from the catalog entry

/show-file-attr savlst.hsmsmac,inf=(org=yes)

 %0000000027 :2OSG:$USER1.SAVLST.HSMSMAC
 %  ------------------------------- ORGANIZATION -------------------------------  
 %  FILE-STRUC = SAM         BUF-LEN    = STD(1)      BLK-CONTR  = PAMKEY 
 %  IO(USAGE)  = READ-WRITE  IO(PERF)   = STD         DISK-WRITE = IMMEDIATE 
 %  REC-FORM   = (V,N)       REC-SIZE   = 0 
 %  AVAIL      = *STD 
 %  WORK-FILE  = *NO         F-PREFORM  = *K          S0-MIGR    = *ALLOWED 
 %:2OSG: PUBLIC:      1 FILE  RES=        27 FRE=         4 REL=         3 PAGES

/add-file-link link=edtsam,file-name=avlst.hsmsmac, access-method=*by-cat, rec-form=*by-cat,buffer-length=*by-cat,block-contr-info=*by-cat /show-file-link link=edtsam,inf=*all

 %-- LINK-NAME --------- FILE-NAME --------------------------------------------- 
 %   EDTSAM              :2OSG:$USER1.SAVLST.HSMSMAC 
 %  -------------------- STATUS ---------------------------------------------- 
 %  STATE      = INACTIVE    ORIGIN     = FILE 
 %  -------------------- PROTECTION ------------------------------------------ 
 %  RET-PER    = *BY-PROG    PROT-LEV   = *BY-PROG 
 %  BYPASS     = *BY-PROG    DESTROY    = *BY-CAT 
 %  -------------------- FILE-CONTROL-BLOCK - GENERAL ATTRIBUTES ------------- 
 %  ACC-METH   = *BY-CAT     OPEN-MODE  = *BY-PROG    REC-FORM   = *BY-CAT 
 %  REC-SIZE   = *BY-PROG    BUF-LEN    = *BY-CAT     BLK-CONTR  = *BY-CAT 
 %  F-CL-MSG   = STD         CLOSE-MODE = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - DISK FILE ATTRIBUTES ----------- 
 %  SHARED-UPD = *BY-PROG    WR-CHECK   = *BY-PROG    IO(PERF)   = *BY-PROG 
 %  IO(USAGE)  = *BY-PROG    LOCK-ENV   = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - TAPE FILE ATTRIBUTES ----------- 
 %  LABEL      = *BY-PROG   (DIN-R-NUM  = *BY-PROG,   TAPE-MARK  = *BY-PROG) 
 %  CODE       = *BY-PROG    EBCDIC-TR  = *BY-PROG    F-SEQ      = *BY-PROG 
 %  CP-AT-BLIM = *BY-PROG    CP-AT-FEOV = *BY-PROG    BLOCK-LIM  = *BY-PROG 
 %  REST-USAGE = *BY-PROG    BLOCK-OFF  = *BY-PROG    TAPE-WRITE = *BY-PROG 
 %  STREAM     = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - ISAM FILE ATTRIBUTES ----------- 
 %  KEY-POS    = *BY-PROG    KEY-LEN    = *BY-PROG    POOL-LINK  = *BY-PROG 
 %  LOGIC-FLAG = *BY-PROG    VAL-FLAG   = *BY-PROG    PROPA-VAL  = *BY-PROG 
 %  DUP-KEY    = *BY-PROG    PAD-FACT   = *BY-PROG    READ-I-ADV = *BY-PROG 
 %  WR-IMMED   = *BY-PROG    POOL-SIZE  = *BY-PROG 
 %  -------------------- VOLUME ---------------------------------------------- 
 %  DEV-TYPE   = *NONE       T-SET-NAME = *NONE 
 %  VSN/DEV    = GVS2.2/D3435

All the file attributes for which *BY-CATALOG is specified in the ADD-FILE-LINK command are marked *BY-CAT in the TFT entry. When the file named LST.HSMSRECALL is accessed via its link name of EDTSAM, these attributes will be taken from the file’s catalog entry.

Example 2: File attributes in the command

/create-file max.file.1 /show-file-attr max.file.1,org=*yes

%0000000003 :2OSG:$USER1.MAX.FILE.1
 %  ------------------------------- ORGANIZATION -------------------------------  
 %  FILE-STRUC = NONE        BUF-LEN    = NONE        BLK-CONTR  = NONE 
 %  IO(USAGE)  = READ-WRITE  IO(PERF)   = STD         DISK-WRITE = IMMEDIATE 
 %  REC-FORM   = NONE        REC-SIZE   = 0 
 %  AVAIL      = *STD 
 %  WORK-FILE  = *NO         F-PREFORM  = *K          S0-MIGR    = *ALLOWED 
 %:2OSG: PUBLIC:      1 FILE  RES=         3 FRE=         3 REL=         3 PAGES

/add-file-link link=output1,file-name=max.file.1,acc-method=*isam, support=*disk(isam-attr=*par(key-pos=5,key-length=10)) /show-file-link link=output1,inf=*par(file=*yes)

 %-- LINK-NAME --------- FILE-NAME --------------------------------------------- 
 %   OUTPUT1             :2OSG:$USER1.MAX.FILE.1 
 %  -------------------- FILE-CONTROL-BLOCK - GENERAL ATTRIBUTES ------------- 
 %  ACC-METH   = ISAM        OPEN-MODE  = *BY-PROG    REC-FORM   = *BY-PROG 
 %  REC-SIZE   = *BY-PROG    BUF-LEN    = *BY-PROG    BLK-CONTR  = *BY-PROG 
 %  F-CL-MSG   = STD         CLOSE-MODE = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - DISK FILE ATTRIBUTES ----------- 
 %  SHARED-UPD = *BY-PROG    WR-CHECK   = *BY-PROG    IO(PERF)   = *BY-PROG 
 %  IO(USAGE)  = *BY-PROG    LOCK-ENV   = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - TAPE FILE ATTRIBUTES ----------- 
 %  LABEL      = *BY-PROG   (DIN-R-NUM  = *BY-PROG,   TAPE-MARK  = *BY-PROG) 
 %  CODE       = *BY-PROG    EBCDIC-TR  = *BY-PROG    F-SEQ      = *BY-PROG 
 %  CP-AT-BLIM = *BY-PROG    CP-AT-FEOV = *BY-PROG    BLOCK-LIM  = *BY-PROG 
 %  REST-USAGE = *BY-PROG    BLOCK-OFF  = *BY-PROG    TAPE-WRITE = *BY-PROG 
 %  STREAM     = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - ISAM FILE ATTRIBUTES ----------- 
 %  KEY-POS    = 5           KEY-LEN    = 10          POOL-LINK  = *BY-PROG 
 %  LOGIC-FLAG = *BY-PROG    VAL-FLAG   = *BY-PROG    PROPA-VAL  = *BY-PROG 
 %  DUP-KEY    = *BY-PROG    PAD-FACT   = *BY-PROG    READ-I-ADV = *BY-PROG 
 %  WR-IMMED   = *BY-PROG    POOL-SIZE  = *BY-PROG

A new file, MAX.FILE.1 , is created with the CREATE-FILE command. The attributes specified in the ADD-FILE-LINK command are transferred to the TFT entry. When the new file is processed by way of the link name OUTPUT1, these attributes are copied into the file control block.

Example 3: Importing file attributes from a reference file

/cre-file abk.neu /show-file-attr abk.isam,inf=(org=*yes)

%0000000126 :2OSG:$USER1.ABK.ISAM
 %  ------------------------------- ORGANIZATION -------------------------------  
 %  FILE-STRUC = ISAM        BUF-LEN    = STD(1)      BLK-CONTR  = PAMKEY 
 %  IO(USAGE)  = READ-WRITE  IO(PERF)   = STD         DISK-WRITE = IMMEDIATE 
 %  REC-FORM   = (V,N)       REC-SIZE   = 0 
 %  KEY-LEN    = 30          KEY-POS    = 8 
 %  AVAIL      = *STD 
 %  WORK-FILE  = *NO         F-PREFORM  = *K          S0-MIGR    = *ALLOWED 
 %:2OSG: PUBLIC:      1 FILE  RES=       126 FRE=         5 REL=         3 PAGES

/add-file-link link=output2,file-name=abk.neu, data-attr=*from-file(abk.isam) /show-file-link link=output2,inf=*all

 %-- LINK-NAME --------- FILE-NAME --------------------------------------------- 
 %   OUTPUT2             :2OSG:$USER1.ABK.NEU 
 %  -------------------- STATUS ---------------------------------------------- 
 %  STATE      = INACTIVE    ORIGIN     = FILE 
 %  -------------------- PROTECTION ------------------------------------------ 
 %  RET-PER    = *BY-PROG    PROT-LEV   = *BY-PROG 
 %  BYPASS     = *BY-PROG    DESTROY    = *BY-CAT 
 %  -------------------- FILE-CONTROL-BLOCK - GENERAL ATTRIBUTES ------------- 
 %  ACC-METH   = ISAM        OPEN-MODE  = *BY-PROG    REC-FORM   = VARIABLE 
 %  REC-SIZE   = 0           BUF-LEN    = (STD,1)     BLK-CONTR  = PAMKEY 
 %  F-CL-MSG   = STD         CLOSE-MODE = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - DISK FILE ATTRIBUTES ----------- 
 %  SHARED-UPD = *BY-PROG    WR-CHECK   = *BY-PROG    IO(PERF)   = *BY-PROG 
 %  IO(USAGE)  = *BY-PROG    LOCK-ENV   = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - TAPE FILE ATTRIBUTES ----------- 
 %  LABEL      = *BY-PROG   (DIN-R-NUM  = *BY-PROG,   TAPE-MARK  = *BY-PROG) 
 %  CODE       = *BY-PROG    EBCDIC-TR  = *BY-PROG    F-SEQ      = *BY-PROG 
 %  CP-AT-BLIM = *BY-PROG    CP-AT-FEOV = *BY-PROG    BLOCK-LIM  = *BY-PROG 
 %  REST-USAGE = *BY-PROG    BLOCK-OFF  = 0           TAPE-WRITE = *BY-PROG 
 %  STREAM     = *BY-PROG 
 %  -------------------- FILE-CONTROL-BLOCK - ISAM FILE ATTRIBUTES ----------- 
 %  KEY-POS    = 8           KEY-LEN    = 30          POOL-LINK  = *BY-PROG 
 %  LOGIC-FLAG = 0           VAL-FLAG   = 0           PROPA-VAL  = MINIMUM 
 %  DUP-KEY    = *BY-PROG    PAD-FACT   = *BY-PROG    READ-I-ADV = *BY-PROG 
 %  WR-IMMED   = *BY-PROG    POOL-SIZE  = *BY-PROG 
 %  -------------------- VOLUME ---------------------------------------------- 
 %  DEV-TYPE   = *NONE       T-SET-NAME = *NONE 
 %  VSN/DEV    = GVS2.3/D3435

A new file, ABK.NEU, is created with the CREATE-FILE command. For processing purposes, the new file is to have the same attributes as an existing file, ABK.ISAM. For this purpose ABK.ISAM is specified as the reference file in the ADD-FILE-LINK command (see DATA-ATTRIBUTES operand). The file attributes of the reference file specified in the ADD-FILE-LINK command are copied into the TFT entry. When the new file is processed by way of the link name OUTPUT2, these attributes are copied into the file control block.

Your Browser is not longer supported

Please use Google Chrome, Mozilla Firefox or Microsoft Edge to view the page correctly

ADD-FILE-LINK

Function

Overview of functions

Format

Operands

Special features of NK-ISAM files

Restrictions

Return codes

Examples

Example 1: Creating a TFT entry with values from the catalog entry

Example 2: File attributes in the command

Example 3: Importing file attributes from a reference file