Files-11 QIO Notes - APR, 78 FILES-11 QIO NOTES This file documents the various QIO's used by Files-11 (F11ACP) and the format of each request. The material was compiled by Ralph Stamerjohn, working mostly from an article written by Andrew Goldstein of Digital in November, 1976. The reader is assumed to be a RSX-11/IAS systems programmer. The article is written as a reference guide. It is not an explanation of the file I/O mechanism. No guarentee of accuracy is implied by the author or Digital. The material should be used with great care. Improper use will lead to corruption of the file system. 1.0 FILES-11 QIO DPB All F11ACP QIO directive parameter blocks have the same format. The following diagram illustrates this format (note only the parameter fields are different from all other QIO's): ------------------------------------------------- ! Size ! DIC ! ------------------------------------------------- ! Function Code ! Modifier ! Q.IOFN Q.IOFN ------------------------------------------------- ! Reserved ! LUN ! Q.IOLU ------------------------------------------------- ! Priority ! EFN ! Q.IOPR Q.IOEF ------------------------------------------------- ! I/O Status Block ! Q.IOSB ------------------------------------------------- ! AST Address ! Q.IOAE ------------------------------------------------- ! FID Pointer ! Q.IOPL ------------------------------------------------- ! Attribute List Pointer ! ------------------------------------------------- ! Extend Control ! Delta Size (High) ! ------------------------------------------------- ! Delta Size (low 16 bits) ! ------------------------------------------------- ! Access Control ! Window Size ! ------------------------------------------------- ! FNB Pointer ! ------------------------------------------------- Each parameter field is used for a specific purpose. The the particular QIO does not require the field is must not be specified (typically set to zero). F11ACP checks range checks all parameter fields. Files-11 QIO Notes - APR, 78 PAGE 2 2.0 FILES-11 QIO PARAMETERS This section will discuss the six parameter words in a Files-11 QIO. While none of the parameters require the FCS data structures, it is obvious the fields are set up for use in the FCS environment. 2.1 Parameter Word #1 - FID Pointer This word contains the address of a three word block in the issuing task's space. This block is or will become the file ID. If the word is zero, no file ID is specified. In the FCS environment, this word will typically contain the address of the filename block. The file ID block has the following format: ------------------------------------------------- ! File Number ! ------------------------------------------------- ! File Sequence Number ! ------------------------------------------------- ! Reserved ! ------------------------------------------------- The file number is used by F11ACP has an index to the file header block in the index file. The file sequence number is used to maintain header integrity. Each time a header block is used for a new file, the file sequence number is inccremented. The final word has no current meaning. 2.2 Parameter Word #2 - Attribute List Pointer This word contains the address of an attribute list in the issuing task's space. This list controls which file attributes are to be read or written by F11ACP. If no attribute list is specified, the word is zero. File attributes are various fields in the file header. These fields are documented in Appendix F of the IAS/RSX-11 I/O Operations Reference Manual (AA-2515C-TC). An attribute list consists of zero to six attribute entries, followed by a byte of zero. Each attribute entry has the following format: .BYTE , Files-11 QIO Notes - APR, 78 PAGE 3 .WORD The sign of the attribute type determines the direction of the operation. If the attribute type is negative, the attribute is read from the file header to the buffer. If the attribute type is positive, the buffer is written to the file header as the new attribute. The magnitude of the attribute type and size of the buffer determine which fields in the file header will be accessed. The following table list all valid read attribute types, valid buffer sizes, and the starting offset in the file header. To write the attribute, make the sign of the attribute type positive. -01,02 Read file owner UIC (H.FOWN). The UIC is a binary word. The low byte (H.PROG) is the owner number. The high byte (H.PROJ) is the group number. Note that the file owner UIC is independent of the directory UIC. -01,04 Read file owner UIC, protection (H.FOWN). The UIC is returned as described above. The second word is set to the file protection code (see attribute -02,02). -01,05 Read file owner UIC, protection, characteristics (H.FOWN). The UIC and protection are returned as described above. The fifth byte is set to the user-controlled characterics (see attribute -03,01). -02,02 Read protection (H.FPRO). The file protection word is a bit mask with the following format: Bit 15 12 11 8 7 4 3 0 ----------------------------------------------- ! World ! Group ! Owner ! System ! ----------------------------------------------- Each of the four categories above has four bits. Each bit has the following meaning with respect to file access: Bit 3 2 1 0 ----------------------------------------------- ! Delete ! Extend ! Write ! Read ! ----------------------------------------------- A bit value of zero (0) indicates the respective type of access is allowed to the file. A bit value of one (1) indicates access is denied. -02,03 Read protection, characteristics (H.FPRO). The protection is returned as described above. The third byte is set to the user-controlled characteristics (see attribute -03,01). -03,01 Read characteristics (H.UCHA). The user Files-11 QIO Notes - APR, 78 PAGE 4 characteristics is a one byte field containing various bit definitions. The current bits defined are listed below: UC.CON = 200 Logically continuous file. When the file is extended, this bit is cleared. UC.DLK = 100 File improperly closed. When ever the file is opened for write, this bit is set. It is not cleared until the file is closed (deaccessed). This is the famous lock bit. In addition to the user-controlled characteristics, the next byte in the header is the system-controlled characteristics. This byte cannot be accessed by an attribute field. The current bits defined in this byte are listed below: SC.MDL = 200 File marked for delete. SC.BAD = 100 Bad data block in file. -04,40 Read record I/O area (U.UFAT). The first 7 words of this area are a direct copy of the first 7 words of the FDB when the file is opened (see Table A-1, I/O Operations Reference Manual, offsets F.RTYP to F.FFBY). The remaining 9 words of this area are not used. I do not know how this area is defined in the case of RMS-11. -05,06 Read filename (I.FNAM). The filename is stored as nine (9) RAD50 characters. -05,10 Read filename, type (I.FNAM). The filename is returned as described above. The type is returned to the fourth word (see attribute -06,02). -05,12 Read filename, type, version (I.FNAM). The filename and type are returned as described above. The version is returned to thr fifth word (see attribute -07,02). -06,02 Read type (I.FTYP). The type is stored as three (3) RAD50 characters. -06,04 Read type, version (I.FTYP). The type is returned as decsribed above. The version is returned to the second word (see attribute -07,02). -07,02 Read version (I.FVER). The version is stored as a binary number. Files-11 QIO Notes - APR, 78 PAGE 5 NOTE The filename, type, and version are set when the file is created. If the file is renamed by PIP, these fields are not changed. -10,07 Read expiration date (I.EXDT). The expiration date is intended to be the time the file becomes eligible for deletion. This feature is not implemented. The date is kept in ASCII form in the format day, month, and year (2 bytes, 3 bytes, and 2 bytes). -11,12 Read statistics block. The statistics block is defined in Appendix H of the I/O reference manual. This attribute is not any specific fields in the file header, therefore, this attribute cannot be written. -12,00 Read entire file header. The buffer size is assumed to be 1000(8) bytes. This attribute has no corresponding write function. The magitide of the attribute type determines the maximun valid buffer size. Any smaller size is legal. The sizes listed above are sufficient to handle the named attributes. The largest size for each attribute is also the largest buffer allowed. 2.3 Parameter Words #3 and #4 - Size/Extend Control These two parameters are used to specify how many blocks are to be allocated to a new file or added to an existing file. The words are also used to control the type of block allocation. The high bit of parameter word #3 (bit 15) controls whether the remaining fields are used by F11ACP. If the bit is zero (0), no size change is desired. If the bit is one (1), the remaining fields are processed. The high byte of parameter word #3 (extend control) determines the type of allocation desired. The low byte of this word and parameter word #4 form a 24-bit number of blocks to allocate (delta size). This number is the initial file size in the case of a create and the change in size in the case of an extend. The extend control byte consist of various bit mask. The bit mask have the following meanings: Bit 0 All blocks must be allocated contigously. Files-11 QIO Notes - APR, 78 PAGE 6 Bit 1 Allocate largest contigious chunk up to delta size. This bit is not examined unless bit 0 is on (1). Bit 2 File must end up contigious at operations end. Bit 3 Use volume default as delta size. Bit 4 Unused. Bit 5 Unused. Bit 6 Unused. Bit 7 Enable extend (see above). 2.4 Parameter Word #5 - Window Size/Access Control This word is used to specify the window size (low byte) and the access control (high byte). The word has is processed if the high bit (bit 15) is one (1). If this bit is zero (0), the word is disabled. The window size is the number of mapping entries the window is to hold at once. This is not the window size in bytes. If the byte is zero, the volume default is used. The access control byte consist of various bit mask. The bit mask have the following meanings: Bit 0 Lock file from further accesses for write and/or extend. Bit 1 Enable daaccess lock. Bit 2 Unused. Bit 3 Unused. Bit 4 Unused. Bit 5 Unused. Bit 6 Unused. Bit 7 Enable access (see above). Files-11 QIO Notes - APR, 78 PAGE 7 2.5 Parameter Word #6 - Filename Block Pointer This word contains the address of a 13(10) word block in the issuing task's space. This block is the filename block. See Appendix B in the I/O Reference Manual for a description of a filename block. If the word is zero, no filename block is specified. 3.0 FILES-11 QIO FUNCTIONS This section will discuss the various functions processed by F11ACP. This functions are normally issued by FCS or RMS, however, the clever user can use them directly and save the overhead of the run-time systems. At the same time, you also take your life into your own hands. The following table summarizes the optional and required parameters for each I/O request. The key to the table is as follows: * = Required parameter. O = Optional parameter. A = Optional if file already accessed. D = May be non-zero, but must be disabled (bit 15 = 0). If the entry is blank, the parameter must be zero or the I/O will be in error. Parmeter 4 is a part of parameter 3 and is not listed in the table. ------------------------------------------ ! Function ! P 1 ! P 2 ! P 3 ! P 5 ! P 6 ! ------------------------------------------ ! IO.ACE ! * ! O ! ! * ! ! ------------------------------------------ ! IO.ACR ! * ! O ! ! * ! ! ------------------------------------------ ! IO.ACW ! * ! O ! ! * ! ! ------------------------------------------ ! IO.CRE ! * ! O ! O ! D ! ! ------------------------------------------ ! IO.DAC ! O ! O ! ! D ! ! ------------------------------------------ ! IO.DEL ! A ! ! O ! ! ! ------------------------------------------ ! IO.ENA ! ! ! ! D ! * ! ------------------------------------------ ! IO.EXT ! A ! ! * ! ! ! ------------------------------------------ ! IO.FNA ! ! ! ! D ! * ! ------------------------------------------ ! IO.RAT ! A ! * ! ! ! ! Files-11 QIO Notes - APR, 78 PAGE 8 ------------------------------------------ ! IO.RNA ! ! ! ! D ! * ! ------------------------------------------ ! IO.WAT ! A ! * ! ! ! ! ------------------------------------------