MFCB (Mini File Control Block)

Structure of the MFCB

The table below shows the fields within the MFCB and the way in which they are interpreted according to the operation selected.

IDMFOPC (Operation code)	IDM FUNIT* Functional unit	IDM VERS* Version ID	IDM RETCO* Return code	IDM FOC Option byte	IDMFLBN Logical block number	IDM FFN File name	IDMFEB Sense byte	IDM FSB Status byte	IDMFIO A1* Address IOAREA1	IDMFNHP No. of blocks to be transf.	IDMFIO A2* Address IOAREA2
Open new file (IDMFO)	A	A	S	A	(+)	S	S	-	-	(A)	-
Reopen (IDMFRO)	A	A	S	A	S	A(+)	S	-	-	(A)	-
Read (IDMFRD)	A	A	S	A	A	A	S	S	(A)	-	(A)
Write (IDMFWR)	A	A	S	A	A	A	S	S	(A)	-	(A)
Check (IDMFCK)	A	A	S	-	-	A	S	S	-	-	-
Check and wait (IDMFCW)	A	A	S	-	-	A	S	S	-	-	-
Close file (IDMFCL)	A	A	S	-	S	A	S	S	-	-	-
Erase file (IDMFER)	A	A	S	-	-	A	S	-	-	-	-

where:

* E S +

applies only with PARMOD=31 field contents are evaluated field contents are set by the system exceptions in the case of object module files (see "Handling object module files with EAM")

Description of the MFCB

An overview of the fields contained in the MFCB and the way in which they are interpreted according to the operation selected is given in the table.

The MFCB is the communication area between EAM and the user. It must be aligned on a word boundary. The fields required for the selected operation must be supplied with the appropriate values before the EAM macro is called.

The IDMCB macro can be used to assign symbolic names to the MFCB.

Functional unit (IDMFUNIT)

If PARMOD=31 applies either explicitly or implicitly, the value 'DMFEAM' must be placed in IDMFUNIT. 

Operation code (IDMFOPC)

Code	Meaning
IDMFO	Create and open a new file (OPEN). EAM evaluates bit IDMFOO of the option byte and then opens either the object module file or a new job-specific file. A new object module file has its name recorded in the TCB (Task Control Block); an existing object module file is reopened (i.e. OPEN=REOPEN applies; see also section "Handling object module files with EAM"). A new EAM file is assigned a binary file name of between 1 and 14000, and this is written into the “file name” field (IDMFFN). In addition, bit IDMFCI of the option byte is evaluated. If this bit is set (i.e. indicating chained I/O mode), a check is made to test whether field IDMFNHP (= number of blocks to be transferred) contains a number between 1 and 16. The addresses of the I/O areas are not checked.
IDMFRO	Reopen an existing file (REOPEN). Bits IDMFOO, IDMFSBR and IDMFCI of the option byte are evaluated. For IDMFCI and hence for field IDMFNHP, the same applies as in the case of the OPEN operation. According to the result of the IDMFOO evaluation, either the job-specific object module file or the file named in the IDMFFN field is opened (see "Handling object module files with EAM").
IDMFRD	Read (READ). EAM evaluates bit IDMFI1 of the option byte and checks the address of an input area (field IDMFIO1 or IDMFIO2) selected via this bit. Input takes place at the corresponding address, even if the contents of IDMFIO1/2 were modified immediately after the operation was invoked. If the end-of-file condition is recognized during a read operation, bit IDMFEF of the sense byte is set. If bit IDMFCI of the option byte was set at OPEN/REOPEN time, chained input is operative. The number of blocks to be transferred is also taken from field IDMFNHP at OPEN/REOPEN time (see "Number of blocks to be transferred (IDMFNHP)"). The “logical block number” field (IDMFLBN) contains the number of the next block to be read, or a value of zero in the case of sequential reading. The read/write operation is asynchronous in EAM, i.e. control is returned to the user immediately after the EAM macro is called, unless a previous I/O operation has not yet terminated. Any error information entered in the MFCB (fields IDMFERR, IDMFSB) always relates to the preceding I/O operation. Consequently, when there are two I/O operations in immediate succession, the second has to wait. Overlapping I/O or double buffering can be implemented by specifying two different I/O area addresses (see section "Overlapping input/output" in chapter "EAM processing").
IDMFWR	Write (WRITE). As in the case of READ, bit IDMFI1 is evaluated and, depending on the result, either field IDMFIO1 or field IDMFIO2 is checked for the validity of the output area address it contains. If the “logical block number” field (IDMFLBN) contains a value of zero, the block is written sequentially at the end of the file. If its value is not equal 0, the block to be transferred is inserted at the position in the file designated by this value. In all other respects, the execution sequence for write operations is the same as for read operations (see above).
IDMFCK	Check for termination of an I/O operation (CHECK). A check is made to determine whether an outstanding I/O operation has terminated. Whatever the case, control is immediately returned to the user. If the operation is not yet completed, a value of 8 is placed in register 15. If the operation is completed, the status bytes are transferred to the MFCB (IDMFSB) and register 15 is set to the value 0.
IDMFCW	Check an I/O operation and wait (CHECK WAIT). EAM is instructed to wait for the last I/O operation to terminate. Following this, the status bytes are transferred. If another operation has already initiated the transfer of the status bytes, this EAM macro has no effect.
IDMFCL	Close file (CLOSE). Following termination of the final outstanding I/O operation, the file is marked as closed. The block number of the last block in the file is transferred to the “logical block number” field (IDMFLBN).
IDMFER	Erase file (ERASE). The file is erased, irrespective of whether or not it is open.

Version number (IDMVERS)

If PARMOD=31 applies either explicitly or implicitly, the value DMEAMV must be placed in IDMVERS. This is important with regard to future versions of BS2000, since it means that different versions of this interface can be supported without the need for recompilation.

Return code (IDMRETCO)

In the 31-bit version the return code is placed in the IDMRETCO field in the MFCB. This return code corresponds to that in register 15.

Return code	Meaning
0	Operation completed successfully
4	Operation not completed successfully; check sense byte (IDMFEB)
8	After check operation: checked I/O operation not yet terminated

Option byte (IDMFOC)

IDMFOO	Open object module file. This bit is evaluated in all operations. If the bit is set, the job-specific object module file is processed (see "Handling object module files with EAM"). If the bit is not set, a new file is opened in the OPEN function and its name is moved to the “file name” field (IDMFFN). In the REOPEN function, the file named in the IDMFFN field is opened.
IDMFCI	Chained I/O. This bit is evaluated at OPEN/REOPEN time and its contents are saved. Thus, when a file is (re)opened, if this bit is set, subsequent I/O operations will be chained. The length of the chain is specified by the contents of field IDMFNHP (= number of blocks to be transferred), which is also evaluated when the file is opened. If the bit is not set, no chained I/O will be performed.
IDMFSBR	Starting point for I/O in the file. This bit controls where I/O operations are to start in a file. It is evaluated when the file is reopened. If it is set, a value of 0 is moved to the “logical block number” field. If it is not set, the highest block number so far assigned to the file is placed in the field IDMFLBN (see the description of the IDMFLBN field).
IDMFI1	Control of the I/O area. This bit is evaluated during current I/O operations. If it is set, the I/O area 2 address specified in field IDMFIO2 is checked for validity, and this area is used for the pending I/O operation. If the bit is not set, the I/O area 1 address contained in field IDMFIO1 is checked. This area is then used for I/O operations (see section "Overlapping input/output" in chapter EAM processing).

Logical block number (IDMFLBN)

The logical block number is a 2-byte binary number (0 <= n <= 65535). If its value is 0, processing is performed sequentially. In a read operation, the block immediately following the last block accessed in a read/write operation is transferred. In a write operation, a block is added to the end of the file.

If the logical block number is not equal 0, it points directly to the block of the file that is to be read or written.

In chained I/O, the value specified applies to the first block in the chain.

File name (IDMFFN)

The file name is a 2-byte binary number (decimal: 1 <= n <= 14000). When a new file is opened by EAM, this number is placed in the “file name” field and must be specified whenever the file is subsequently referenced.

Sense byte (IDMFEB)

If an error occurs during an operation initiated by the EAM macro, bits are set in the sense byte according to the type of error (the bits can be addressed by their symbolic names). At the same time a value of X'00000004' is placed in register 15.

IDMFIC	Invalid operation. Invalid operations include, for example, illegal operation code, attempt to access a file which is not open, in chained I/O the value of field IDMFHNP is not between 1 and 16, and MFCB is not aligned on a word boundary.
IDMFIF	Invalid file name. The number specified in the “file name” field (IDMFFN) does not identify any EAM file associated with this job.
IDMFIB	Invalid block number. The number specified in the “logical block number” field (IDMFLBN) refers to a block outside the file (read access) or is greater than the number of the last block written + 1 (write access).
IDMFIA	Invalid I/O area address. The address contained in field IDMFIO1 or IDMFIO2 for I/O area 1 or I/O area 2 respectively is invalid.
IDMFNS	No more EAM space available. For example, the user has reached the maximum number of EAM files allowed (14000) or the total amount of space available on the system for all EAM files has been exhausted.
IDMFNP	Illegal access to a privileged file. A non-privileged user attempted to access a privileged file.
IDMFEF	End-of-file. End-of-file was reached during a read access: if a block chain encounters the end of the file during chained input, as much of the read operation as possible is completed and the end-of-file bit is set.
IDMFERR	Check status bytes. The preceding read or write operation was not completed successfully. The status bytes should be checked to determine the cause of the error.

Status field (IDMFSB)

The value of this field is set by the system if the following conditions are true simultaneously:

• the preceding operation was a read or write operation;

• the current operation is a read, write, check, check-and-wait, or close operation.

The following bytes are transferred from the channel control block (CCB): the standard device byte, 3 sense bytes, the Executive flag byte.

Address of I/O area 1 (IDMFIO1/IDMFIOA1)

This field contains the virtual address of the first byte of I/O area 1.
In write operations, a block or block chain is transferred from this address. In read operations, the block/block chain is transferred to this address.

If the I/O area is the same size as a block (2048 bytes), it should be located within a page (4096 bytes) and commence on a word boundary. In the case of chained I/O the area should commence on a page boundary; it must be able to hold as many blocks as can be transferred with a single I/O request.

If the area is not aligned as specified above, buffering may be required in conjunction with certain hardware, which in turn leads to a drop in performance.

Number of blocks to be transferred (IDMFNHP)

This field is evaluated at OPEN/REOPEN time if chained I/O (IDMFCI) is specified in the option byte. It contains a 1-byte binary number <= 16.

If end-of-file is reached during chained I/O in read mode, the system sets the value of this field equal to the number of blocks transferred.

Address of I/O area 2 (IDMFIO2/IDMFIOA2)

This field contains the virtual address of the first byte of I/O area 2. The same address can be used as for I/O area 1, but for asynchronous processing with overlapping input/output, the address specified in this field must refer to an area which does not overlap I/O area 1.

The same conditions apply here as in the case of I/O area 1.

Chained input/output

If bit IDMFCI for chained processing is set in the MFCB, I/O operations are performed at a faster rate. The blocks to be written as a chain need not be adjacent to each other. In write operations, block chains are always written in groups of 3 PAM pages. In read operations, adjacent pages are read as a chain. Field IDMFNHP (= number of blocks to be transferred) must therefore always contain a value that is a multiple of 3. In addition, I/O operations should always start at block numbers that can be represented in the form (3 x n) + 1, i.e. 1, 4, 7, ...

Note

In order to support NK4 pubsets (in later operating system versions), EAM users are requested to convert chained processing to the blocking factor 2 or a multiple of 2. In this case, odd block numbers (BLOCK#) should be specified for direct I/O operations, i.e. 1, 3, 5, ...

Increasing the blocking factor at the expense of main memory space (I/O buffer) leads to savings with regard to CPU time (initiation and termination of the I/O request) and channel and device times (seek and search times); this is because several blocks can be read or written in one physical I/O operation. The system has no influence on this optimization possibility, which lies effectively in the hands of the EAM user.