FCB - Define file control block

Macro type: type O

The file control block is the central source of information for the access methods BTAM, ISAM, SAM and UPAM. A file control block is required whenever a file is processed.

DMS takes the necessary information from various sources:

• the user can specify values for FCB fields in the FCB macro;

• in user programs, values can be placed in FCB fields during program execution, but before the file is opened;

• specifications in the FILE macro with the appropriate link name are placed in the TFT and are given precedence over the corresponding FCB fields when the file is opened;

• the FCB can also be modified while the file is being opened using routines in the application program (see the EXLST macro, "EXLST - Define exit address list", OPENX and OPENZ routines).

• further information is taken from the catalog entry for the file during OPEN processing.

The events which lead to the construction of a complete FCB are listed below in chronological order:

• FCB macro during assembly

• modification during program execution, before the OPEN macro is called

• at OPEN time, construction of the FCB

  • from the TFT (FILE call with appropriate link name)

  • from the catalog entry (regardless of the OPEN mode)

  • in OPEN routines (see the EXLST macro, "EXLST - Define exit address list", OPENX and OPENZ routines) by the user program

The complete FCB also sets up the connection to the logical routines which handle the blocking and unblocking of records for the record-oriented access methods (SAM, ISAM).

DSECTs

Using the IDFCB macro, a DSECT can be generated for the FCB so that the user can address its fields symbolically. If files are processed via the 24-bit interface, a DSECT for the FCB extension can be generated by means of the IDFCBE macro.

NULL operands

If the file/file generation group specified directly in the FCB macro or indirectly via the LINK operands already exists (i.e. if the file has already been opened using OPEN modes OUTPUT or OUTIN), certain FCB macro operands can be specified as “NULL operands”. This means that the operand is specified but no operand value (i.e. the operand value is an empty character string).

FCB LINK=name, FCBTYPE=, BLKSIZE=, RECFORM=, ...

For a list of the operands that can be specified as NULL operands, see table "Operands for disk files".

FCB and access methods

Various access methods use the FCB, but each only evaluates certain operands. The following table provides an overview of which access methods use which operands. Operands which an access method cannot evaluate are ignored. No error message is issued.

Operand in FCB	Meaning	BTAM	ISAM	PAM	SAM
BLIM	Tape only: number of data blocks per tape				x
BLKCTRL	Block format (UPAM: tape)		x	x	x
BLKSIZE	Length of data block (UPAM: tape)	x	x	x	x
BTAMRQS	Number of I/O requests	x
BUFOFF	Tape only: buffer offset				x
CHAINIO	Chaining factor	x
CHKPT	Tape only: checkpoint				x
CODE	Translation table (SAM: tape)	x			x
DUPEKY	Duplicate key		x
EXIT	Error exit	x	x	x	x
FCBTYPE	Access method	x	x	x	x
FILE	Designates the file to be processed	x	x	x	x
FORM	Memory space reservation				x
FSEQ	Tape only: number of a file within a file set	x			x
IOAREA1	Program buffer	x	x	x	x
IOAREA2	Second program buffer	x	x	x	x
IOPERF	Performance attribute (pubset only)		x	x	x
IOREG	Register for file processing in locate mode		x		x
IOUSAGE	Usage of cache (pubset only)		x	x	x
KEYARG	Address of field containing ISAM key		x
KEYLEN	Length of ISAM key		x
KEYPOS	Beginning of ISAM key		x
LABEL	Tape only: label attributes	x			x
LARGE_ FILE	Disks only: file size allocation over 32 GB		x	x	x
LBP_ REQUIRED	last-byte pointer (LBP) processing requested			x
LINK	File link name	x	x	x	x
LOCKENV	Lock log for synchronization (shared-update processing)		x	x
LOGLEN	Length of logical flag		x
OPEN	OPEN mode	x	x	x	x
OPTION	Options	x	x	x	x
OVERLAP	Overlapping		x
PAD	Block padding for files created sequentially		x
PAMREQS	Asynchronous I/O operations			x
PAMTOUT	Waiting time			x
PARMOD	Generation mode	x	x	x	x
PASS	Password	x	x	x	x
POOLLNK	Pool link name		x
RECFORM	Record format	x	x		x
RECSIZE	Record length	x	x		x
RETPD	Retention period	x	x	x	x
SAM_NODE _FILE_ ENABLE	SAM node file processing enabled				x
SECLEV	Tape only: security level	x			x
SHARUPD	Multi-user mode		x	x
STREAM	Streaming mode	x
TAPEWR	Tape only: buffered output	x			x
TPMARK	Tape only: tape marks	x			x
TRANS	Tape only: code translation	x			x
TRTADR	Tape only: user' s own translation table (for reading)	x			x
TRTADW	Tape only: user' s own translation table (for writing)	x			x
UPAM_ RAW_ ACCESS	UPAM RAW access on SAM node files			x
VALLEN	Length of value flag		x
VALPROP	Value flag		x
VARBLD	Register for the free space in the block to be written				x
WRCHK	Read-after-write check when writing blocks		x	x	x
WROUT	Immediate writing back		x

Format

Operation

Operands

FCB

[BLIM = number] [,BLKCTRL = PAMKEY / DATA / DATA2K / DATA4K / NO] [,BLKSIZE = STD / (STD,n) / length] [,BTAMRQS = number] [,BUFOFF = L / length] [,CHAINIO = number] [,CHKPT = NO / ANY / BLIM / FEOV,ACTIVE / DUMMY] [,CODE = EBCDIC / ISO7 / OWN] [,DUPEKY = YES] [,EXIT = (relexp) / number] [,FCBTYPE = ISAM / BTAM / PAM / SAM] [,FILE = pathname] [,FSEQ = UNK / NEW / number] [,IOAREA1 = NO / SECRET / number] [,IOAREA2 = NO / SECRET / number] [,IOPERF = VHIGH / HIGH / STD] [,IOREG = reg] [,IOUSAGE = RDWRT / WRITE / READ] [,KEYARG = relexp] [,KEYLEN = length] [,KEYPOS = number] [,LABEL = (STD,3) / STD / (STD,number) / NONSTD] [,LARGE_FILE = *FORBIDDEN / *ALLOWED] [,LBP_REQUIRED = NO / YES] [,LINK = name] [,LOCKENV = *HOST / *XCS] [,LOGLEN = length] [,OPEN = INPUT / EXTEND / INOUT / OUTIN / OUTPUT / REVERSE /          SINOUT / UPDATE] [,OPTION = code / (code1,code2)] [,OVERLAP = YES] [,PAD = number] [,PAMREQS = number] [,PAMTOUT = number] [,PARMOD = 24 / 31] [,PASS = password] [,POOLLNK = name] [,RETPD = days] [,SAM_NODE_FILE_ENABLE = NO / YES] [,SHARUPD = NO / YES / WEAK] [,RECFORM = V / F / U / (V / F / U [,N / M / A ])] [,RECSIZE = length / reg] [,SECLEV = HIGH / LOW / (HIGH / LOW,OPR)] [,STREAM = NO / YES] [,TAPEWR = DEVICE-BUFFER / IMMEDIATE] [,TPMARK = YES / NO] [,TRANS = YES / NOv [,TRTADR = relexp] [,TRTADW = relexp] [,UPAM_RAW_ACCESS = NO / YES] [,VALLEN = length] [,VALPROP = MIN / MAX] [,VARBLD = reg] [,WRCHK = NO / YES] [,WROUT = NO / YES]

Operand descriptions

BLIM = number

Only for creating files with standard labels which are to be processed with the SAM access method and extend over several tapes. The following operands must be specified along with BLIM in the FCB macro: FCBTYPE=SAM, OPEN=OUTPUT, LABEL=(STD,n).
“number” specifies the maximum number of data blocks, that are allowed to be written on a single tape, 1 <= number <= 999999.
When the block limit value is reached, a tape swap is initiated (EOV processing).

If requested via 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 number of blocks specified via BLIM has been written, an error message is entered in the FCB.

BLKCTRL

Only for 31-bit processing (PARMOD=31); the operand is ignored in 24-bit processing (PARMOD=24):
Specifies whether a file with the K format (with PAM keys) or NK format (without PAM keys) is to be processed.
The same functions, with identical user interfaces, as for the corresponding K files are available for the processing of NK-SAM and NK-PAM files. The access method NK-ISAM provides some functions over and above those of K-ISAM (ISAM pools, secondary keys; for details see the “Introductory Guide to DMS” [1].

When an existing file is opened, no value should be specified for BLKCTRL (i.e. a NULL operand) (for more information on the NULL operand, see "FCB - Define file control block"). The value is then transferred to the FCB from the catalog entry when the OPEN function is executed (for more information on “existing files” see also the note in the section “Sequence of OPEN processing” in the “Introductory Guide to DMS” [1]).
When a new file is created (with OPEN mode-OUTPUT or OUTIN), the BLKCTRL operand should be omitted. Depending on the file structure and the disk format, the following default setting will be assumed for BLKCTRL during OPEN processing.

BLKCTRL	File structure and disk format
PAMKEY	for files (PAM, SAM, ISAM) on K disks and tape files, unless FCBTYPE=BTAM.
DATA	for SAM files on NK2 and NK4 disks
DATA2K	for ISAM files on NK2 disks
DATA4K	for ISAM files on NK4 disks
NO	for PAM files on NK2 and NK4 disks and for BTAM files

= PAMKEY
The file has the K format: the block control information is kept in a PAM key outside the data block. Such a file cannot be created on an NK disk (FBA disk without simulation of PAM keys).

= DATA
The file has NK format: the block control information is kept at the beginning of each logical block (see also BLKSIZE operand description; 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
For ISAM files only:
explicitly creates or processes an NK2 file. This value cannot be used to create a file on an NK4 disk or to open a file located on one.
The block-specific management information is stored in the first 16 bytes of each 2-Kbyte block.

= DATA4K
For ISAM files only:
explicitly creates or processes an NK4 file. 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-Kbyte (BLKSIZE=(STD,n) where “n” is even).
The file can be created and/or opened on K disks, NK2 disks, and NK4 disks.

= 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.

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, and thus the length of the program's I/O area.

If there is no specification for BLKSIZE, the value from the catalog entry is used for existing files (for a definition, see also the note in the section “Sequence of OPEN processing” in the “Introductory Guide to DMS” [1]). With new files, (STD,2) files are created on NK4 volumes. (STD,1) files are created on other volumes.
If (STD,2) is specified, the user cannot user his own IOAREA's. He should have these created by the system in class 5 memory when the OPEN function is executed.

For processing, see the note under BLKCTRL on "FCB - Define file control block" and “Programming notes” on "FCB - Define file control block".

Disk files/tape files with standard blocks:
A logical block may consist of several PAM pages. The system automatically links the PAM pages belonging to one transfer unit.

For disk files, there are interactions between this operand and the RECSIZE operand, for tape files between this operand and the LABEL operand. 

Tape files with nonstandard blocks:
The data block is defined as the number of bytes which are written/read per write or read operation.

= STD
Equivalent to (STD,1); see below.
Data is transferred from and to devices in units of 2048 bytes; the usable length of the transfer unit (for user data) depends on the BLKCTRL specification (or 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 4 Kbytes. 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.

BLKCTRL	Block size available for user data (bytes)
= PAMKEY	n * 2048
= DATA	for ISAM: n * (2048 - 16) - 16 for SAM: (n * 2048) - 16 for PAM: (n * 2048) - 12
= DATA2K / DATA4K (only possible for ISAM)	n * (2048 - 16) - 16
= NO	n * 2048

Note

The following points should also be taken into account when determining whether a record will fit in a block or how many records will fit in a block:

• • • • • for NK-ISAM files with duplicate keys, the length of the time stamp;

        • for NK-ISAM files with RECFORM=F, the length of the record format field;

        • for NK-SAM files, the length of the length field (fill rate information).

= 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, i.e. no PAM keys are kept.

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 operand BUFOFF). All blocks are the same size.
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 record length, is variable. If RECFORM=V is used together with CODE=EBCDIC or LABEL=(STD,n) where n > 1 <, “length” must be less than 10000 (converted internally into record format D).

Operand FCBTYPE	Permissible values for “length”
SAM, BTAM	1 <= n <= 32768
PAM	-------

Note

If an existing file is to be opened, it is advisable to use the null operand, so the appropriate value is taken from the catalog entry at OPEN time.
If a file is being created for the first time, BLKSIZE=(STD,n) must be specified for NK4 volumes, where 1 <= n <= 16 and n is even; otherwise, the OPEN will be rejected.

BTAMRQS = number

Only for BTAM:
specifies the number of BTAM I/O requests which can be issued directly one after the other (without WAITs) to the system (MAV mode). All accepted requests are simultaneously present in the system for processing. The system ensures that they are processed sequentially, i.e. processing is asynchronous.

1 <= number <= 8.

Default value

BTAMRQS = 1

The BTAM access method is described in the “Introductory Guide to DMS” [1].

BUFOFF

Only for SAM tape files without standard blocking or tape files with BLKCTRL=DATA:
defines the buffer offset, i.e. the length of a field which is inserted at the beginning of each data block.

Default value: If the BUFOFF operand is not specified (neither in the TFT nor in the FCB), the following value will be assigned to the file after it is opened (assuming the value from the catalog entry has not been taken):

• for tape files with BLKCTRL=DATA

  • if FCBTYPE=SAM: BUFOFF=16

  • if FCBTYPE=PAM: BUFOFF=12

  • for SAM tape files without standard blocking

    • if RECFORM=V: BUFOFF=4

    • if RECFORM=F/U: BUFOFF=0

= 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 default value is used. 

= length
Specifies the length of the buffer offset. 

For files with RECFORM=V: 0 <= length <= 4; if BUFOFF=4 applies, this field contains the length of the current block.

CHAINIO = number

Only for BTAM files with chained I/O:
1 <= number <= 16; “number” is the chaining factor and defines the length of the transport/transfer unit for input and output. “number” is a number of physical blocks, which means that the length of the transport unit is n * BLKSIZE.

A value specified for the LEN operand in the BTAM action macro has priority over the result of “BLKSIZE times number”; nevertheless, CHAINIO must still be specified if chaining is to be used.

CHKPT

For tape files only:
Controls whether 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-PROGRAM command; see the “Commands” manual [3]).

Default value:

CHKPT=(NO,ACTIVE)

= (NO,...)
Checkpoints are not written automatically.

= (BLIM,...)
When the block limit specified by 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 written automatically when the BLIM limit is reached or when the FEOV macro is called. Specification of the BLIM operand is mandatory.

= (...,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 in the case of a restart using the RESTART-PROGRAM command.

CODE

For tape processing:
specifies whether code translation tables are to be used during input and output and, if so, which tables.

For CODE=EBCDIC and CODE=ISO7 the German and international character sets are encoded in the same manner. 

For CODE=ISO7 and CODE=OWN, the following points should be noted:

• the block size must be specified by BLKSIZE=length, so that no PAM keys are written;

• for output in locate mode with variable-length records (RECFORM=V), the contents of the record length field change.

= EBCDIC
No code conversion is necessary during processing. 
= 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. 
= OWN
Conversion is carried out with code tables provided by the user. The addresses of these tables must be specified in an FCB macro. At the same time, label processing must either be deactivated via the LABEL operand (LABEL=NO) or be carried out in the user program (LABEL=NSTD).

DUPEKY = YES

For ISAM files:
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. The operand DUPEKY=YES is significant only if an ISAM file is created sequentially using PUT macros or extended non-sequentially using STORE macros. The INSRT macro cannot be used to write records with duplicate primary keys.

Default value:

the file must not contain duplicate primary keys.

In NK-ISAM, an 8-byte time stamp is appended internally to records with duplicate primary keys. This must be taken into account when defining the record length.

The ISAM macros PUT, STORE and INSRT have different effects if there is a duplicate primary key.

Macro	Duplicate keys not permitted	Duplicate keys permitted (DUPEKY=YES)
PUT	A record with a duplicate key is not written; EXLST exit: DUPEKY	The records are written sequentially to the file
STORE	The “new” record overwrites the record already stored with this ISAM key	The new record is stored after the old record
INSRT	A record with a duplicate key is not written; EXLST exit: DUPEKY	A record with a duplicate key is not written; EXLST exit: DUPEKY

Note

No secondary keys may be defined in a file containing duplicate primary keys. 

EXIT

Specifies the address to which the program is to branch in the case of an error. If the operand is not specified, exception conditions during accessing of the file lead to abnormal program termination.
If the exit is taken, a flag is set in the FCB. The user routine can determine the relevant exit condition. If a hardware error occurs during input or output, a 5-byte field in the FCB is filled with information from the CCB (standard device byte, sense bytes 1-3, Executive flag byte; see the NDWERINF macro, "NDWERINF - Evaluate status bytes"). The meanings of these bytes are described in the appendix, "DMS error codes"). The Executive flag byte and the standard device byte are defined in the DSECT for the CCB (IDCCB).

= (relexp)
Address of a user routine in the user program which executes error handling.

= relexp
Address of the EXLST macro via whose exits various user routines are addressed for specific handling of the various error types.

FCBTYPE

Specifies the access method to be used for file processing.

= ISAM
Depending on the value specified for the BLKCTRL operand, it is processed as an NK-ISAM file (BLKCTRL=DATA/DATA2K/DATA4K) or as a K-ISAM file (BLKCTRL=PAMKEY). The ISAM access method is described in the “Introductory Guide to DMS” [1].

ISAM-specific operands: DUPEKY, KEYLEN, KEYPOS, LOGLEN, POOLLNK, VALLEN, WROUT and VALPROP.

= BTAM
A tape file is processed with the access method BTAM (The BTAM access method is described in the “Introductory Guide to DMS” [1].)

BTAM-specific operands: CHAINIO, OPEN=SINOUT, BTAMRQS.

= PAM
The file is processed with the access method UPAM (see description of corresponding access method). PAM files may be stored on tape or disk.

= SAM
The file is processed with the access method SAM and may be located on disk or tape. SAM files are generally processed sequentially with the access method SAM. They may also be processed with UPAM. (The SAM access method is described in the “Introductory Guide to DMS” [1].)

SAM-specific operands: BUFOFF, CLOSMSG, OPEN=UPDATE.

FILE = pathname

Designates the permanent or temporary file or the file generation to be processed with:<c-string 1..54: filename 1..54>

File generations can be addressed via their absolute or relative generation numbers.

Default value:

FILE=fcbaddr (= symbolic address of the FCB); if not present: blanks

Pathname means [:catid:][$userid.]filename

catid
Catalog ID; if omitted, the default catalog ID for the user ID is used.

userid
User ID; if omitted, the user ID specified in the LOGON command is used.

filename
Fully qualified file name.

FORM = SHORT

For the 24-bit interface only (non-XS processing):
specifies that no memory space is to be reserved for logical routines.

Default value:

space is reserved in the 24-bit FCB for the logical routines.

The logical routines handle the blocking and unblocking of records for SAM and ISAM; this means, for normal SAM/ISAM processing, that the file cannot be opened if FORM=SHORT is specified in the FCB macro. The logical routines are not needed for PAM files and the operand FORM=SHORT is ignored in this case.

For XS processing (PARMOD=31), FORM=SHORT is ignored since the 31-bit TU FCB contains only the addresses of the logical routines.

FSEQ

For tape files which belong to a file set:
specifies the (sequence) number of a file within the file set. For example, if several files with the same name are stored on one tape, access to a specific file is controlled by FSEQ. This also applies to MF/MV sets.

Default value:

FSEQ = 0 (tape processing begins with the first file)

= UNK
Permissible only for files with standard labels:
the start position of the file is unknown. The tape is rewound for file processing.

= NEW
Permissible only for files which are not yet cataloged:
a new file is to be added to a file set. The tape is positioned to the end of the file set and the new file is written behind the currently last file of the file set. The new file receives a file sequence number 1 higher than that of the “old” last file.

= number
Specifies the file sequence number of “pathname” within the file set;
0 <= number <= 9999.
FSEQ=0, just like FSEQ=1, denotes the first file of the file set.

If “pathname” is already cataloged, the FSEQ value must be the same as the file sequence number in the catalog entry. If a new file is to be created, it is written at the end of the file set, which means that its file sequence number must be 1 higher than that of the “old” last file in the file set.

The tape is not rewound on opening the file if it is already at the position specified with FSEQ. 

IOAREA1

Specifies whether a buffer area is to be allocated at OPEN time, and if so, at what address.

Default value:

DMS automatically requests a buffer area (in class 5 memory) at OPEN time – either above or below the 16-Mb boundary, dependingon the addressing and generation mode (see "Operands IOAREA1/2").

= NO
No buffer area is to be allocated at OPEN time (not permitted for SAM and K-ISAM processing).

= SECRET
At OPEN time, DMS requests an area in nonprivileged class 5 memory for IOAREA1;
in the event of a dump analysis, the pages in this area are not output.

= relexp
Address of a buffer area; if this area is less than or equal to one page in size (4096 bytes) it must be fully contained within one page and be aligned on a word boundary; if it is larger than a page, it must be aligned on a page boundary.

IOAREA2

Specifies whether a second buffer area is to be allocated at file opening time.

Default value:

DMS automatically requests a buffer area (in class 5 memory) at OPEN time – either above or below the 16-Mb boundary, depending on the addressing and generation mode (see "Operands IOAREA1/2").

= NO
Only one buffer area is allocated for the file, i.e. overlapped processing is not possible (see also the operand OVERLAP=YES); IOAREA2=NO cannot be specified for K-ISAM processing.

= SECRET
At OPEN time, DMS requests an area in nonprivileged class 5 memory for IOAREA2;
in the event of a dump analysis, the pages in this area are not output.

= relexp
Address of the second buffer area; if it is less than or equal to one page (4096 bytes), it must be contained within one page and aligned on a word boundary; if larger than one page, it must be aligned on a page boundary.

IOPERF

Only applicable to the 31-bit interface:
sets the desired performance attribute for I/O processing with regard to the use of a cache.

= VHIGH
Data should be permanently maintained in the cache.

= HIGH
If possible, the file should be processed via a cache.

= STD
There are no specific performance requirements. The file is not processed via a cache (for more information on cache processing, see the “Introductory Guide to DMS” [1]).

IOREG = reg

For SAM and ISAM only:
specifies that the file is to be processed in locate mode.
“reg” specifies the register containing the address of the current record (2 <= reg <= 12).

Default value:

The file is processed in move mode

In locate mode, the user is responsible for correctly addressing records in the buffer; no automatic blocking/deblocking of records is executed.

IOUSAGE

Only applies to the 31-bit interface:
This parameter specifies, how the cache should be used for the file.

= RDWRT
The performance attribute refers to read and write operations.

= WRITE
The performance attribute refers to write operations.

= READ
The performance attribute refers to read operations.

KEYARG = relexp

For ISAM only:
specifies the address of a field containing the ISAM key for the current record. This field is evaluated for the ISAM macros GETKY, GETFL, ELIM and SETL.

KEYLEN = length

For ISAM files:
specifies the length of the ISAM key in bytes,
where 1 <= length <= 255 - VALLEN - LOGLEN

Default value:

KEYLEN = 8

KEYPOS = number

For ISAM files :
specifies the position of the ISAM key in the record. In variable-length records, 4 bytes for the record length and control field must be taken into account. The ISAM key may be anywhere in the record, but must be in the same position in each record of one file.

Default value:

for files with RECFORM = V: KEYPOS = 5; for files with RECFORM = F: KEYPOS = 1.

LABEL

Only for tape files :
specifies the label type for files on tape or tape cartridge; the SECLEV operand determines how the labels are processed.

Default value:

LABEL = (STD,1)

For existing tape files, the standard identifier 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 indicator in the VOL1 label is set or updated as specified in the LABEL operand (see also section "Programming notes").

= STD
File and volume either already have or will receive standard labels in accordance with DIN 66029, exchange level 1.

= (STD,number)
File and volume either already have or will receive standard labels in accordance with the exchange level of DIN 66029 designated by “number”; 0 <= number <= 3.

Effects of the LABEL operand

	(STD,0)	(STD,1)	(STD,2)	(STD,3)
DIN 66029 exchange level Date	-	1 8/1972	2 6/1976	3 3/1978
Label standard version in VOL1 label	_ (blank)	1	2	3
CODE=ISO-7/ OWN	not permitted	STD blocks converted to nonstandard blocks	STD blocks converted to nonstandard blocks	STD blocks converted to nonstandard blocks
		RECFORM=V: conversion to D format (not for BTAM)	RECFORM=V: conversion to D format	RECFORM=V: conversion to D format
		RECSIZE > 9999 or BLKSIZE > 9999 OPEN error	RECSIZE > 9999 or BLKSIZE > 9999 OPEN error	RECSIZE > 9999 or BLKSIZE > 9999 OPEN error
CODE=EBCDIC			STD blocks converted to nonstandard blocks	STD blocks converted to nonstandard blocks
Access method			SAM only	SAM only
RECFORM=U				Invalid for output files; converted to (STD,2)

(STD,1) is assumed for:

• • • RECFORM=V and CODE=EBCDIC

    • BLKSIZE=STD

    • FCBTYPE=PAM or FCBTYPE=BTAM

For (STD,0), CODE=EBCDIC must be used.

If the value in the label standard version in the VOL1 label is less than (STD,number), the value from the label standard version is assumed for “number”.

= 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.

LARGE_FILE

Only for disk files (access methods ISAM, SAM and UPAM):
The LARGE_FILE operand determines whether or not the file size may grow beyond 32 GB (see "Files larger than 32 GB").

= *FORBIDDEN
The file size may not exceed 32 GB.

= *ALLOWED
Only for 31-bit interfaces and files with BLKCTRL ≠ PAMKEY:
The file size may exceed 32 GB.

LBP_REQUIRED

specifies, if a last-byte pointer (LBP) processing is requested. The LBP then specifies the exact logic file end of a PAM file in byte limitation. For non-PAM files, LBP_REQUIRED is ignored.

=*NO
No last-byte pointer processing is requested.

=*YES
It is requested that the PAM file on public space has a last-byte pointer (LBP). This request must be carried out for a new file at the time of OPEN OUTIN. Then, a valid last-byte pointer is generated for this file, in which the LBP_valid bit and the LBP value for UPAM processing to OPEN OUTIN or INOUT in CLOSE is set when the last page of the file has been written.

For files on private disk or tape, for encrypted files and for OPEN with SHARUP=YES, a last-byte pointer processing for PAM files is rejected with DMS0D09.

LINK = name

Via the file link name (“name”) specified here, DMS establishes a link to the TFT and thus to the file and processing attributes defined by means of the FILE macro.

“name” may be up to eight characters in length. If the file link name is to be addressed via the command interface, it must correspond to the data type <structured_name 1..8> (see the “Commands” manual [3]).

LOCKENV

For UPAM access method only:
specifies which lock log the user uses for synchronization.

= *HOST
Shared-update processing is only permitted on the user's own host. The synchronization takes place via the Task Lock Manager.

= *XCS
Shared-update processing is permitted within an XCS network; the synchronization must take place via the Distributed Lock Manager.

LOGLEN = length

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 VALLEN operand, "FCB - Define file control block"), since the entire ISAM index must not be longer than 255 bytes. The rule is thus:

length <= 255 - KEYLEN - VALLEN

Default value:

LOGLEN=0, i.e. there is no logical flag in the ISAM index.

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, and does not place the flags in the index entry.

OPEN

Specifies the OPEN mode for the file. This setting may be overwritten by the OPEN mode specified in the OPEN macro.

Default value:

OPEN = INPUT

The following table shows which OPEN modes are permissible for the various access methods.

OPEN modes with the FCB macro

OPEN mode	ISAM	BTAM	SAM	UPAM
INPUT	x	x	x	x
EXTEND	x	-	x	-
INOUT	x	x	-	x
OUTIN	x	x	-	x
OUTPUT	x	x	x	-
REVERSE	-	x	x	-
SINOUT	-	x	-	-
UPDATE	-	-	x	-

where:

x	OPEN mode is permitted
-	OPEN mode is not permitted

The various OPEN modes are described in detail in the descriptions of the access methods.

= INPUT
An existing file is read (for a definition of an existing file, see also the note in the section “Sequence of OPEN processing” in the “Introductory Guide to DMS” [1]).

= EXTEND
A 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.

= INOUT
An existing file is opened for non-sequential processing; write and read operations are permitted.

= OUTIN
A file is created or, if it already exists, overwritten from the beginning. Both read and write operations are permitted (non-sequential).

= OUTPUT
A file is created or, if it already exists, overwritten from the beginning.

= REVERSE
An existing file is opened as an input file for sequential reading from end-of-file -> beginning-of-file.The file section number of the file section to be processed can be specified via the VSEQ operand in the FILE macro. Tape files are positioned to the end of the file section on completion of OPEN processing. If no VSEQ is specified, the last file section is processed. Automatic tape switching is not supported.

= SINOUT
Only for BTAM tape files:
the file must exist and the tape must not be positioned to the beginning of the tape. Data blocks can be read or written; labels are not processed.
Files that extend over multiple reels cannot be processed with SINOUT.

= UPDATE
Only for SAM disk files:
the file is to be processed in locate mode.

OPTION = code

A list of options can be specified for this operand. By default, no codes are stored. Either GLODEF or NOWAIT may be specified for “code”.

= GLODEF
If the file name is specified without an explicit user ID, and the file is not found under the caller's user ID, a second read attempt is made under the system default user ID (see “Access via the system default user ID” in the “Introductory Guide to DMS” [1]). This applies only if no TFT entry for the file exists at OPEN time, since the TFT already contains the path name.

= NOWAIT
If an I/O operation encounters an error caused by a device (such as device INOP), the program does not wait for an operator reaction, but branches immediately to the EXLST exit ERRADDR. The code NOWAIT is accepted only together with PARMOD=31 and for the access methods PAM and ISAM.

OVERLAP = YES

Only 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.

Default value: OVERLAP = NO

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 primarily sequential.

PAD = number

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 BLKSIZE). PAD thus has an effect on the block splitting rate when a file is extended non-sequentially.

Default value:

PAD = 15

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 never filled above the PAD limit.

PAMREQS = number

For UPAM processing:
specifies how many asynchronous I/O operations can be requested simultaneously (in one PAM macro; see the PAM macro, operand REQNO, "PAM - Perform UPAM actions"; 0 <= number <= 100).

Default value:

PAMREQS = 1

PAMTOUT = number

For UPAM processing:
specifies how long a job is to wait for requested locks (in seconds).

0 <= number <= 43200

Default value:

PAMTOUT = 0

If the locks are still not available after the time specified here, control is passed to EXLST exit DLOCK or PGLOCK.
PAMTOUT=0 means that control is returned immediately, regardless of whether or not the requested locks are available.

PARMOD

Specifies the generation mode for the macro.

Default value:

the value defined with the GPARMOD macro or preset by the Assembler.

The generation mode can be set globally for all macros in a program by means of the GPARMOD macro.

The PARMOD operand in the DMS macros overrides the default value set by the GPARMOD macro or (if GPARMOD is not specified) preset in the Assembler.

All PARMOD specifications for one file must have the same value.

= 24
The macro is expanded in accordance with the format for the 24-bit interface. The object code is thus executable only in 24-bit addressing mode.

= 31
The macro is generated as addressing mode-independent.

PASS = password

If the file is password-protected, the password necessary for the desired access must either be stored in the password table of the job or specified by the PASS operand in the FCB macro.

The maximum length of the password is four bytes. The password field ID1PASS is padded on the left with zeros or, if the specified password is longer, truncated on the left (in accordance with the rules for the processing of address constants in Assembler programs).

The rules for specifying passwords and the password hierarchy are described in various parts of the manual, for example in the description of the CATAL macro.

POOLLNK = name

Only for ISAM files:
processed in user ISAM pools (NK-ISAM); “name” is the “pool link name” (up to 8 characters long) which is placed in the TFT. This pool link name must be assigned to an ISAM pool (see the macros ADDPLNK, "ADDPLNK - Define pool link name", and CREPOOL, "CREPOOL - Create ISAM pool").

RECFORM

Specifies the record format of the file “pathname” and also specifies which control characters are to be interpreted if the file is sent to a printer.

Default value:

RECFORM = (V,N)

The record format specification is evaluated only 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 under the section dealing with access methods in the “Introductory Guide to DMS” [1]. For information on the relationship between the RECFORM and RECSIZE specifications, see the RECSIZE operand. For details of the evaluation of print control characters, see the PRINT-DOCUMENT command (CONTROL-MODE and LINE-SPACING operands) in the manuals “Commands” [3] and “SPOOL” [4].

For tape files with RECFORM=V and CODE=EBCDIC or LABEL=(STD,n) – where n > 1 – the contents of the record length and block size fields are converted internally into the D-format: the value for the record/block size is represented as a decimal number. For such files, the block size must not exceed 10000 bytes. During input, format-D records are converted back to hexadecimal form before being transferred to the user's area.

= 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 the record length and control fields. All records in the file have the same length, which is defined via the RECSIZE operand. (The decisive factor here is the BLKSIZE value, not the RECSIZE value.)

= 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 RECSIZE operand). 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 out by specifying the PRINT-DOCUMENT command with the operand 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 out by specifying the PRINT-DOCUMENT command with the operand LINE-SPACING=*BY-ASA-CONTROL.

RECSIZE

Specifies the record length, depending on the specification in the RECFORM operand.

Default value:

for RECFORM = V: RECSIZE = BLKSIZE; for RECFORM = F: no default value.

= length
the maximum record length in bytes

For RECFORM=V:
For NK-ISAM files, it should be noted that overflow blocks may result if the maximum record length is fully utilized. For ISAM files, the maximum record length is BLKSIZE. For SAM files, the maximum record length is BLKSIZE-4, but with BLKCTRL=DATA only BLKSIZE-16.
For tape files, the interaction with the operands CODE and LABEL should be noted, see table "Effects of the LABEL operand".

For RECFORM=F (all records in the file are the same length):
For ISAM files, the maximum record length is BLKSIZE-4.
For SAM files, the maximum record length is BLKSIZE, but with BLKCTRL=DATA only BLKSIZE-16.

If a GET is used (to read) in move mode for files with RECFORM=V and RECSIZE=length in the FCB macro, and if the record to be read is longer than the specified RECSIZE, the following applies:

• • • ISAM files: the operation is aborted with error message DMS0AAD.

    • SAM files: the entire record is read into the program area, regardless of the RECSIZE specification. 

If a PUT is used (to write) in move mode for files with RECFORM=V and RECSIZE=length in the FCB macro, and if the record to be written is longer than the specified RECSIZE, the following applies:

• • • ISAM files: the entire record is written to the file, regardless of the RECSIZE specification.

    • SAM files: the entire record is written to the file, regardless of the RECSIZE specification.

= reg
For RECFORM=U: the RECSIZE operand must specify a general 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 = days

With “RETPD”, the user can define a retention period during which no write access (update, delete) is possible.

Default value:

RETPD=0, i.e. the file can be updated or erased at any time.

“days” is an integer (not greater than 32767) which specifies the length of the retention period in days.
Once the retention period has elapsed, the file is not automatically erased; this simply means that write access is permitted again.

The retention period can also be controlled by means of the MODIFY-FILE-ATTRIBUTES command or the CATAL macro (see "CATAL - Process catalog entry"): 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.

SAM_NODE_FILE_ENABLE

specifies if the processing of SAM node files is allowed or not.

=*NO
The processing of SAM node files is rejected with the return code DMS0D1A.

=*YES
The processing of SAM node files is requested by the user. As the processing of SAM node files is different from the processing of SAM files on public volumes, the SAM_NODE_FILE_ENABLE parameter prevents older applications from accidentally accessing the SAM node files.

When processing SAM node files, the retrieval addresses are currently calculated the same way as for SAM files on public volumes. The retrieval addresses that are given back to the application are only valid between OPEN and CLOSE.

These retrieval addresses are no longer valid after a CLOSE with subsequent OPEN.

In future versions of BS2000, the user will be able to use the PROCESSING_MODE parameter during the OPEN call to define, whether the retrieval addresses are to be calculated the same as now, whether only retrieval addresses still usable after CLOSE and OPEN will be given back or whether no retrieval addresses should be used at all and the files are only to be processed sequentially.

SECLEV

Only for tape files:
the operand SECLEV (security level) refers to the TPIGNORE entry in the JOIN file (cf. the SHOW-USER-ATTRIBUTES command). 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 file, the operator can ignore the error messages.

= LOW
Permissible only for the tape/file owner if TPIGNORE=YES is defined in the JOIN file of the user ID: 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

Only for ISAM or UPAM disk files:
specifies whether several jobs may concurrently open the file with an OPEN mode other than OPEN INPUT.

= 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, but SHARUPD=YES must be specified in all these jobs (if writing is allowed). In the case of UPAM, the user can protect data blocks from access by other jobs as long as he is processing them. In the case of ISAM, these locks – whenever necessary – are set automatically by the system. 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 the WROUT operand, below).

= WEAK
For UPAM processing only:
ensures write protection but not read protection, i.e. only one job can open the file for updating, but other jobs may use it simultaneously as an input file. The user must take into account in his program that the contents of the file may change while he is using it as an input file.

The following table shows the various contending levels, with the type of protection offered in each case:

SHARUPD options	User actions	Protection type READ	Protection type WRITE
YES	n users are reading and m users are writing	*	*
WEAK	n users are reading and 1 user is writing	-	*
NO	n users are reading or a user is writing	*	*

The WEAK operand is supported for PAM files only.
For information on permitted SHARUPD combinations see the section “UPAM” in the “Introductory Guide to DMS” [1].
If FCBTYPE≠PAM, SHARUPD=WEAK is processed as if it were SHARUPD=NO.

STREAM

Only for BTAM tape files:
The STREAM operand enables users to specify whether they wish to use “streaming mode”. This implies that the user is working with chained data blocks as well as MAV mode (for which appropriate specifications must be made by the user!) and that the individual jobs are to be internally concatenated. It also implies that if a streamer is being used, this mode is to be set in terms of hardware.

= NO
Streaming mode is not set.

= YES
Streaming mode is set.

TAPEWR

Only for files on tape cartridges:
the user can specify whether or not input and output are to be buffered.

= DEVICE-BUFFER
Input and output are buffered in the tape controller, resulting in a high data transfer rate.

= IMMEDIATE
Input and output are not buffered.

TPMARK

Only for tape files without standard labels:
specifies whether tape marks are to be written. The TPMARK operand is evaluated during OPEN only for tape files with LABEL=NO/NSTD. Tape files with LABEL=(STD,n) automatically receive tape marks after the labels.

= NO
No tape mark is written.

= YES
Tape files with NSTD labels: the tape mark follows the label.

Tape files without labels: the tape mark is written at the beginning of the tape.

TRANS

Only 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.

= 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.

TRTADR = relexp

Specifies the address of the user's own translation table for reading a tape file. This may be specified only together with CODE=OWN or if no value is specified for CODE.

TRTADW = relexp

Specifies the address of the user's own translation table for writing a tape file. This may be specified only together with CODE=OWN or if no value is specified for CODE.

UPAM_RAW_ACCESS

specifies, how an application accesses SAM node files using UPAM. If no SAM node file is accessed, the specification is ignored.

=*NO
At UPAM OPEN for a SAM node file, logical SAM blocks are accessed. They are created from UNIX data during the read process by using the SAM converter or they are converted to a UNIX byte flow during the write process and written to the UNIX file.

For OPEN OUTIN or INOUT with UPAM_RAW_ACCESS=*NO, SAM_NODE_FILE_ENABLE=*YES has to be specified in order to gain write access to the file. Otherwise, the processing is rejected with DMS0D1A. For OPEN INPUT, the specification of SAM_NODE_FILE_ENABLE=*YES is unnecessary.

=*YES
In case of a UPAM OPEN on a SAM node file, the SAM converter gets disabled, so that the application receives unstructured data or writes into the UNIX file. The value of the SAM_NODE-FILE_ENABLE parameter is not relevant.

VALLEN = length

Only for ISAM files:
specifies the length of the value flag in the ISAM index.

Default value:

VALLEN = 0, i.e. the ISAM index does not contain a value flag.

length <= 255 - KEYLEN - LOGLEN

Value flags are treated differently by NK-ISAM (BLKCTRL=DATA) and K-ISAM (BLKCTRL=PAMKEY). In K-ISAM, they are evaluated block-by-block and transferred to the next higher index entry as specified in the VALPROP operand. In NK-ISAM, no flags are evaluated for the index entry.

VALPROP

Only for K-ISAM files:
in conjunction with BLKCTRL=PAMKEY, i.e. with K-ISAM files (NK-ISAM will ignore a VALPROP specification);
specifies how the value flag is to be included in the index entries (VALPROP = VALue PROPagation).

= MIN
The lowest value of the value flag within one 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.

VARBLD=reg

Only for SAM files with RECFORM=V, which are processed in locate mode (see also the IOREG operand); specifies the register (2 <= reg <= 12) in which DMS is to show the free space (in bytes) in the block to be written.

WRCHK

Only 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.
A read-after-write check is designed to detect recording errors ( -> error recovery measures). If the error cannot be rectified, control is passed to the EXLST exit ERRADR. Due to the additional disk revolutions involved, 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, WROUT=YES is set implicitly: updated blocks are written back to disk immediately.

Default value:

• for “normal” file processing: WROUT = NO

• for shared-update processing: WROUT = YES

• in cross-task ISAM pools: WROUT = YES

• in task-local ISAM pools for which WROUT=YES is valid: WROUT = YES

= NO
An updated block is written back to disk only when the contents of the related 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. 

Return information (example)

The return code 0D33, which was kept in the FCB field ID1ECB by the OPEN has the following meaning, depending on the specifications made by the caller in the file name and in the OPTION parameter.

File name	OPTION	Meaning of 0D33
:cat:$user.file		The file is not present under the $user label on the cat pubset.
$user.file		The file is not present under the $user label on the default pubset of $user.
$.file		The file is not present on the pubset under the label specified with the DEFLUID system parameter.
:cat:$.file		The file is not present on the cat pubset under the label specified with the DEFLUID system parameter.
file	not GLODEF	The file is not present under the caller label on its default pubset.
file	GLODEF	The file is neither present under the caller label on its default pubset nor under the label specified with the DEFLUID system parameter on the pubset specified there.
:cat:file	not GLODEF	The file is not present under the caller label on the cat pubset.
:cat:file	GLODEF	The file is neither present on the cat pubset under the caller label nor the cat pubset under the label specified with the DEFLUID system parameter.

Any modification to the file name in field ID1FILE within an OPEN-EXIT routine is ignored.

Programming notes

FCB structure

The structure of a 31-bit FCB differs considerably from that of a 24-bit FCB:

• The FCB macro expands in 31-bit mode into a CSECT statement if no other DMS action macro has been called previously in 31-bit mode.

• There is no longer any FCB extension, i.e. all data is accommodated within the FCB itself.

• The logical routines of the SAM and ISAM access methods are no longer included in the FCB; the FCB now contains only the addresses of these routines.

• All 3-byte addresses have been eliminated and corresponding new 4-byte addresses have been introduced.

• The FCB has a fixed, uniform size.

FCB modification

When a file is opened, DMS checks the FCB entries and uses them to set up a privileged file control block (TPR FCB); any subsequent changes to the FCB values are ignored. The file control block can be modified only by closing the file (CLOSE) and then reopening it (OPEN).

If an operand is not specified in the FCB macro, the default value is assumed. If a null string operand is specified, it is assumed that the value of the operand is supplied by a FILE macro or by the catalog entry of the file (exception: LINK= operand).

Operands for disk files

FCB operand	Null operand: operand value supplied via the catalog	BTAM	SAM	ISAM	PAM	Operand in the FILE macro
BLIM		i	x	i	i	x
BLKCTRL	x	x	x	x	x	x
BLKSIZE	x	x	x	x	x	x
BTAMRQS		x	i	i	i
BUFOFF	x	i	x	i	i	x
CHAINIO		x	i	i	i	x
CHKPT		i	x	i	i	x
CODE	x	x	x	i	i	x
DUPEKY		i	i	x	i	x
EXIT		x	x	x	x
FCBTYPE	x	x	x	x	x	x
FILE		x	x	x	x	x
FORM		i	x	x	i
FSEQ	x	x	x	i	x	x
IOAREA1		x	x	x	x
IOAREA2		x	x	x	x
IOPERF		i	x	x	x	x
IOREG		x	x	x	i
IOUSAGE		i	x	x	x	x
KEYARG		i	i	x	i
KEYLEN	x	i	i	x	i	x
KEYPOS	x	i	i	x	i	x
LABEL		x	x	i	x	x
LBP_ REQUIRED		i	i	i	x
LINK		x	x	x	x	x
LARGE_FILE		i	x	x	x	x
LOCKENV		i	x	x	x	x
LOGLEN	x	i	i	x	i	x
OPEN		x	x	x	x	x
OPTION		x	x	x	x	x
OVERLAP		i	i	x	i	x
PAD		i	i	x	i	x
PAMREQS		i	i	i	x
PAMTOUT		i	i	i	x
PARMOD		x	x	x	x
PASS		x	x	x	x
POOLLNK		i	i	x	i	x
RECFORM	x	x	x	x	i	x
RECSIZE	x	x	x	x	i	x
RETPD		x	x	x	x	x
SAM_NODE_ FILE_ENABLE		i	x	i	i
SECLEV		x	x	i	x
SHARUPD		i	x	x	x	x
STREAM		x	x	i	i
TAPEWR		x	x	i	x	x
TPMARK		x	x	i	x	x
TRANS		x	x	i	i	x
TRTADR		x	x	i	i
TRTADW		x	x	i	i
UPAM_RAW_ ACCESS		i	i	i	x
VALLEN	x	i	i	x	i	x
VALPROP	x	i	i	x		x
VARBLD	x	i	x	x	i
WROUT		i	i	x	i	x
WRCHK		i	x	x	x	x

where:

i	Operands are ignored..
x	Operands may be specified.

Operand BLKSIZE

The user can/must specify “BLKSIZE=(STD,n)” if

• the record is longer than 2048 bytes, or

• the record length is uneconomic in conjunction with a block length of 2048 bytes. For example, if the user has fixed-length records (RECFORM=F), each 1500 bytes long, and defines the block length as BLKSIZE=STD, then 548 bytes would be wasted in each block. If, instead, the user were to specify BLKSIZE=(STD,3), then 6000 out of the 6144 bytes (3 x 2048) would be used, and only 144 bytes would be wasted in every three blocks. Using very large block sizes does, however, lead to an increase in the paging rate.

Operands IOAREA1/2

When a file is opened, the IOAREA addresses are created (if necessary) and validated. They are then moved into system memory. Consequently, any changes relating to these addresses are completely ignored in the FCB. For new addresses to become effective, a CLOSE macro has to be issued, followed by a new OPEN macro.

This method of processing was chosen to minimize internal system processing time (overhead), as the IOAREA addresses do not have to be checked before every action macro. PAM and BTAM allow buffer addresses to be defined in their action macros. These addresses are of course checked whenever action macros are issued.

If a SAM file is opened in UPDATE mode, the IOAREA2 buffer is not used.

If IOAREA1=NO is specified, then the value of IOAREA2 must also be NO. If IOAREA1 is defined with “relexp”, then the value of IOAREA2 must also be “relexp”, or NO. If IOAREA1 is not specified, then IOAREA2 is not allowed either, or must be defined as NO.

Operand LABEL

In the case of a file opened in INPUT, INOUT, EXTEND or REVERSE mode, the system ignores the specification LABEL=(STD,n) and refers to the exchange level (label standard version) specified in the volume label (VOL1).

In the case of an output file, the exchange level specified here applies. If only STD was specified, exchange level 3 applies.

If the allocated tape volume already contains one or more files or file sections, the exchange level must match the standard identifier in the first volume label.

Otherwise, the standard identifier is assigned a value as shown below:

Exchange level	0	1	2	3
Standard identifier	blank	1	2	3

Restrictions

• Exchange level 1: If CODE=ISO7/OWN is specified, STD block specifications are converted to NSTD block specifications and format V records (RECFORM=V) are converted to format D records. If this is not possible, e.g. when RECSIZE/BLKSIZE is greater than 9999, an OPEN error results.

• Exchange level 2: Only SAM files can be processed. STD block specifications are converted as for exchange level 1: in this case, tapes with CODE=EBCDIC are also affected.

• Exchange level 3: RECFORM=U is not allowed for output files.

Rules

• If FSEQ=0/1, then LABEL=(STD,3) is converted to (STD,1).

• If RECFORM=V and CODE=EBCDIC, then LABEL=(STD,1) is implicit.

• If BLKSIZE=STD, then LABEL=(STD,1) is implicit.

• If BLKSIZE=length and RECFORM=U, then LABEL=(STD,2) is implicit.

• If a tape volume already contains one or more files/file sections and the standard identifier in the first volume label is less than the implicitly assumed DIN exchange level, then the version number is taken from the volume label.

Operand WROUT

The WROUT function provides increased security for ISAM file processing, since in the event of a system crash only the records processed by the last macro will be corrupted or lost. (Exception: when the PUT macro is used, only blocks are written.)

The increased number of I/O operations reduces throughput.

The WROUT function takes effect after the ISAM action macros STORE, ELIM, INSRT and PUTX.

ISAM shared-update mode already includes the WROUT function, so in this case the WROUT operand is irrelevant.

A value other than YES or NO will always result in an error message.

The value specified in the FILE macro has priority over the value specified in the FCB macro. The latter value takes effect only if the WROUT operand is omitted from the FILE macro or is entered as a null operand (i.e. WROUT=,...).