DECNET DIGITAL NETWORK ARCHITECTURE DATA ACCESS PROTOCOL (DAP) Functional Specification Version 5.6 Date: 28-March-80 Doc. No. HAL-78-001-03-S DIGITAL EQUIPMENT CORPORATION MAYNARD, MASSACHUSETTS 01754 DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 2 Copyright (C) 1978 Digital Equipment Corporation, Maynard Mass. This material may be copied, in whole or in part, provided that the above copyright notice is included in each copy along with an acknowledgment that the copy describes the Data Access Protocol developed by Digital Equipment Corporation. This material may be changed without notice by Digital Equipment Corporation, and Digital Equipment Corporation is not responsible for any errors which may appear herein. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 3 PREFACE This document describes the features, message formats, and operation of the Data Access Protocol (DAP). DAP provides standardized formats and procedures for accessing and passing data between a user process and a file system existing in a network environment. It assumes a controlled conversation path provided by the network system. In DECnet, this path is created by the Network Services Protocol and its associated interface. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 4 Table of Contents Section Title 1.0 SCOPE 2.0 FUNCTIONAL DESCRIPTION 2.1 DAP Functions 2.2 Relationship to DECnet 2.3 Generic Model 3.0 MESSAGE FORMATS 3.1 Notation 3.2 General Message Format 3.3 Configuration Message 3.4 Attributes Message 3.5 Access Message 3.6 Control Message 3.7 Continue Transfer Message 3.8 Acknowledge Message 3.9 Access Complete Message 3.10 Data Message 3.11 Status Message 3.12 Key Definition Attributes Extension Message 3.13 Allocation Attributes Extension Message 3.14 Summary Attributes Extension Message 3.15 Date and Time Attributes Extension Message 3.16 Protection Attributes Extension Message 3.17 Name Message 3.18 Access Control List Attributes Extension Message 4.0 FILE ORGANIZATION 4.1 Types of Files 4.2 Record Formats/Attributes 4.3 Data Formats 4.4 Supported Data Types 5.0 OPERATION 5.1 Setting up the Link 5.2 Transferring Data over the Link 5.3 Closing a File and Terminating Data Streams 5.4 Terminating a Logical Link 5.5 File Security and Protection 5.6 DAP Based Applications Written by DIGITAL DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 5 APPENDIX A GLOSSARY APPENDIX B User Identification Message APPENDIX C REVISION HISTORY DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 6 List of Illustrations Figure Title Page 2-1 Typical DAP Message Exchange (Sequential File Retrieval) 5-1 Setup Sequence 5-2 File Retrieval Sequence 5-3 Sequential File Storage List of Tables Table Title Page 2-1 DAP Messages 3-1 MACCODE Field Values 3-2 MICCODE Field Values for Use with MACCODE Values of 2, 10, and 11 Octal 3-3 MICCODE Field Values for Use with MACCODE Values of 0, 1, 4, 5 and 7 Octal 3-4 MICCODE Field Values with MACCODE Value of 12 Octal 5-1 Responses to Setup Message Errors DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 7 1.0 SCOPE This document describes the functions, characteristics, capabilities, and operation of the Data Access Protocol (DAP). It is primarily intended to assist developers and implementers in understanding how DAP functions within a system. The document is not intended to address specific implementations. The Data Access Protocol is specifically designed for remote file access via a file system such as Record Management Services (RMS). Unit Record Devices and terminals can be accessed if supported by a file system. When Unit Record Devices and terminals are supported by a file system in a device-dependent manner, the device control features peculiar to the individual devices are not supported by DAP. 2.0 FUNCTIONAL DESCRIPTION The Data Access Protocol is an application level protocol. Its primary purpose is to permit remote file access within the DECnet environment independently of the I/O structure of the operating system being accessed. 2.1 DAP Functions Within DECnet, DIGITAL Operating Systems can employ DAP to provide the following remote file access functions: 1. Retrieve a file from an input device; 2. Store a file on an output device; 3. Provide ASCII file transportability between nodes; 4. Provide error recovery; 5. Allow multiple data streams to be sent over a logical link; 6. Command file execution and submission; 7. Provide for random access of records in a file; 8. Provide for file deletion; 9. Rename files; and 10. List directories. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 8 2.2 Relationship to DECnet DECnet is a family of products that create distributed networks from DIGITAL computers and their interconnecting data links. DECnet creates a general mechanism for sharing resources and providing interprocess communications within a distributed data processing environment. DECnet implementations adhere to a common network architecture which defines the structure and protocols used to communicate through the network. The DIGITAL Network Architecture provides a modular design for DECnet. Its functional components are defined within six distinct layers: the Physical Link Layer, the Data Link Layer, the Transport Layer, the Network Service Layer, the Network Application Layer, and the User Layer. Each layer performs a well-defined set of network functions (via network protocols) and presents a level of abstraction and capability to the layer above it: Physical Link Layer The Physical Link Layer, consisting of device specific modules, provides the interface to the communication hardware. Data Link Layer The Data Link Layer controls the physical link operation to ensure both data integrity and sequentiality. Transport Layer The Transport Layer provides a mechanism for the network service layer to send a unit of data (a packet) from any node in the network to any other node in the network. Network Service Layer The Network Service Layer provides the mechanism that permits node-to-node communications and process-to-process communications between processes in the same or different nodes. It provides a logical link service and a datagram service to the network. Application Layer The Application Layer supports the various user services and programs that utilize the network facilities. These services and programs must utilize the network communication mechanism provided by the Network Services Layer. DAP resides within the Application Layer. User Layer The User Layer contains all the user-supplied functions. It is the highest layer in the DNA structure. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 9 2.3 Generic Model As an aid toward understanding the Data Access Protocol, a generic model is presented in this section. This model consists of a summary of the DAP messages and a typical DAP message exchange sequence (illustrating how DECnet Sequential File Retrieval is accomplished between two dialogue processes). For a more detailed description of the DAP message formats and the protocol operation, refer to Sections 3.0 and 5.0, respectively. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 10 Table 2-1. DAP Messages Message Function Configuration Used to exchange system capability and Message configuration information between DAP speaking processes. This message is sent immediately after a link is established. It contains information about the operating system, the file system, protocol version, and buffering ability. Attributes Provides information on how data is struc- Message tured in the file being accessed. The message contains information on file organization, data type, format, record attributes, record length, size, and device characteristics. Access Specifies the file name and type of access Message requested. Control Used to send control information to a file Message system and to establish data streams. Continue-Transfer Allows recovery from errors. Used for Message retry, skip, and abort after an error is reported. Acknowledge Used to acknowledge access commands and Message control connect messages used to establish data streams. Access Complete Controls termination of file and stream access. Message Data Message Transfers the file data over the link. Status Used to return status and information on Message error conditions. Access Control When creating a file, this message is used List Attr. Ext. Msg. to specify the access rights users are granted for access to this file. Key Definition Used to specify key definitions for indexed Attr. Ext. Msg. files. Allocation Used when creating or explicitly extending a Attr. Ext. Msg. file to specify the character of the allocation. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 11 Summary Used to return summary information about Attr. Ext. Msg. file. Date Time Used to specify time related information Attr. Ext. Msg. about the file. Protection Used to specify the file protection code. Attr. Ext. Msg. Name Message Used to send name information when renaming a file or obtaining a directory listing. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 12 User Node Message Remote Node Message Description Messages Description Configuration Information Configuration Message (e.g. Buffer Size, OS, File ---------------------------> System, and DAP Version No.) Configuration Message <-------------------------- Configuration Information Attributes Message File Characteristics -------------------------> (e.g., Type, Blk Size and Record Size) Access Message Access Request -------------------------> Attributes Message <------------------------- Actual File Characteristics Returned Acknowledge Message <------------------------- File Opened Control Message Set up Data Stream -------------------------> Acknowledge Message <------------------------- Data Stream Established Request Start of Data Transfer and Mode of Control (Get) Message Transfer -------------------------> Record 1 <------------------------- Data Sent in Records . . . Record N <------------------------- Status Message <------------------------- End-of-File Indicated Access Complete Message Request to Terminate --------------------------> Access Complete Response <------------------------- Request Completed Successfully Figure 2-1. Typical DAP Message Exchange (Sequential File Retrieval) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 13 2.4 References 1. VAX-11 Record Management Services Reference Manual, Order No. AA-D031A-TE. 2. IAS/RSX-11M RMS-11 MACRO Programmer's Reference Manual, Order No. AA-0002A-TC. 3. RMS-11 Functional Specification, 15 March 1976, Doc. No. 130-958-028-01. 4. RMS-20 Functional Specification, 1 Sept. 1976, Doc. No. 200-835-002-00. 5. RMS-32 Functional Specification, 21 Sept. 1976, Doc No. 130-958-049-00. 6. MACY11 Record Format on TOPS-20 and TOPS-10, Doc. No. SGR-78-003-00-S. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 14 3.0 MESSAGE FORMATS 3.1 Notation The following notation is used to describe the DAP messages: field (length) : coding = description of field. where: field = the name of the field being described. length = the length of the field, which can be indicated in one of four ways: 1. A number meaning number of 8-bit bytes (octet). 2. A number followed by a "B" meaning number of bits. 3. The letters "EX" meaning extensible field. Extensible fields are of variable length consisting of 8-bit bytes in which the high-order bit of each byte denotes whether the next byte is part of the same field. A 1 means the next byte is part of this field and a 0 denotes the last byte. Extensible fields are for bit maps only. Seven bits from each octet are used as information bits. The notation EX-n means an extensible field where the maximum length of the field is n bytes. Note: The bit definitions define the information bits after removing the extension bits and compressing the remaining bits. 4. The letters "I-n" means this is an image field, with n being a number that specifies the maximum length of the field in 8-bit bytes. The image is preceded by a 1-byte count of the length of the remainder of the field. Image fields are variable in length and may be null (count=0). All 8-bits of each byte are used as information bits. The meaning and interpretation of each image field is as defined with that specific field. coding = the representation type used, where: DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 15 A = 7-bit ASCII B = binary BM = bit map (in which each bit has a specific meaning) The following rules apply to the notation: 1. If length and coding are omitted, field represents a number of subfields specified in the description. 2. Any bit or field described as "reserved" shall be zero unless otherwise specified. 3. All fields are presented to the Network Services Protocol with the least-significant byte first. In an ASCII field, the left-most character is contained in the low-order byte. 4. All numbers are in decimal unless otherwise specified. 5. When default values are defined for fields in DAP messages, the values will be used only if that field is absent from the message. There are two ways in which fields within DAP messages can be omitted so the default can be used: a. A field that appears under a MENU may be omitted by setting the corresponding MENU bit to zero. b. Trailing fields in DAP messages may be omitted if they are not needed or if the default value can be used. If a MENU field is truncated in this way, its value is zero (which means all the fields controlled by the MENU are absent, too). If a field is present with a zero value, the default value is not used. The value zero is used. 3.2 General Message Format All DAP messages have the following form: OPERATOR OPERAND where: OPERATOR = This field describes the characteristics and type of message. It is divided into seven subfields, TYPE, FLAGS, STREAMID, LENGTH, LEN256, BITCNT, and SYSPEC. TYPE(1) : B = The type of DAP message. These numbers are given DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 16 with each DAP message description. Types 128-191 are reserved for DIGITAL applications based on DAP. Types 192-255 are reserved for user extensions to DAP. FLAGS(EX-5) : BM = The DAP message flags. Bits in this extensible field are currently defined as follows: Bit(s) Meaning (when set) 0 Stream identification field present. 1 Length field present. 2 If bit 1 (length field present) is set, field LEN256 is present and the length field is in effect 2 bytes long. Illegal if bit 1 not set. 3 The BITCNT field is present. 4 Reserved (0) 5 SYSPEC field present. 6 If set, this is a segmented message and this is not the last segment of the message. The next message will contain the next segment of the full message. The next message must be of the same type as this message. Refer to the SYSCAP field of the Configuration Message to see if DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 17 this facility is supported. NOTE DAP messages can be truncated up to the point of leaving only the TYPE field provided the fields truncated are not needed or can be defaulted. This is particularly useful with the Acknowledge Message which reduces the ACK to a one byte message. STREAMID(1) : B = The stream identification field. This field is included only if bit 0 of the FLAGS field is set. This field is used to allow a single user to have multiple data streams in use for a single open file. All data streams use the same logical link (they multiplex on the STREAMID number). If the STREAMID number is omitted, it is assumed to be zero. Not all file systems are capable of supporting multiple data streams from a single file. LENGTH(1) : B = Denotes the length of the OPERAND field (number of 8-bit bytes). This field is optional. It is included only if bit 1 of the FLAGS field is set. Two or more DAP messages may be blocked together into one NSP message (usually for reasons of efficiency). If DAP messages are blocked, the LENGTH field must be present so the end of one message and start of the next can be found. Messages between 0 and 255 bytes long may be blocked using only the LENGTH field. DAP messages whose operand length is between 256 and 64K bytes may be DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 18 blocked only if both bits 1 and 2 of FLAGS are set. Lengths greater than 64K bytes are sent unblocked or as the last part of a blocked message. LEN256(1) : B = Contains the most significant byte of a two byte OPERAND length if bit 2 of FLAGS is set. LENGTH contains the least significant byte. If LEN256 is present, LENGTH must also be present. BITCNT(1) : B = This field is valid only with the Data Message. If present, it contains a number in the range 0-7 which is the number of unused bits in the final 8-bit byte of the message. It is required only when transmitting data which does not completely fill the final 8-bit frame of a Data Message. This is useful when accessing files whose byte size is not a multiple of eight. See section 4.4.3. SYSPEC(I-255) : B = This optional field is the system specific field which means that it can only be used for file access between two homogeneous systems. This field is included only if bit 5 of the FLAGS field is set. If it is used between hetrogeneous systems, it will produce a hard error and the access will be aborted. Between homogeneous systems, this field can be used for passing system specific information as defined by the system. The SYSPEC field can not be used with the Configuration Message. This field must not be used for passing information DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 19 common to more than one system. IF THIS FIELD IS USED, ALL SYSTEM SPECIFIC FUNCTIONS MUST BE REGISTERED WITH THE ARCHITECTURE GROUP WITHIN DECnet IN ADVANCE OF CERTIFICATION. OPERAND = The information field for DAP messages. It is dependent on the TYPE field. NOTE Typically, one DAP speaking process sends one or more DAP messages to a cooperating process which then responds with one or more messages, see section 5 for examples of message sequences. This pattern is repeated until the access is complete. DAP messages can be blocked in one of two ways: 1. The first process blocks and sends DAP messages up to the point where it expects a response from the cooperating process. It then waits for the response. 2. The first process blocks and sends DAP messages without regard for response from the cooperating process -- it may be way ahead of the cooperating process. This means the cooperating process must be able to receive a buffer full of DAP messages, process some of them, send a response and then continue processing DAP messages from the same buffer from where it left off before sending the response. If the response was an error, the unprocessed messages in the buffer may no longer be valid and must be discarded. The first method of blocking is the more commonly used. The type of blocking a system supports is specified in the Configuration Message. Some small systems may not support blocking at all. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 20 3.3 Configuration Message The Configuration Message is used to pass system configuration information between the cooperating processes involved in DAP remote file access. This message is sent immediately following link establishment. The accessed process may wait to receive a Configuration Message from the accessing process before it sends a Configuration Message itself, however, this is not necessary. The Configuration Message should not be sent blocked with any other DAP message (so buffers of the appropriate size can be allocated for receiving subsequent DAP messages). The Configuration Message format is: CONFIG BUFSIZ OSTYPE FILESYS VERSION SYSCAP where: CONFIG : = The OPERATOR field with TYPE=1. BUFSIZ(2) : B = The maximum buffer size (in bytes) of the sending system for message exchange. The two cooperating DAP speaking processes will use the lesser of the two buffer sizes as the maximum size. If one of the two systems has an unlimited buffer size, it sends a 0 and the two systems will use the nonzero buffer size as the maximum. If both systems send 0, there is no limit on the length of messages which may be sent. OSTYPE(1) : B = Operating system type (the sending system). Values in the range 1-191 are reserved for DIGITAL use; 192-255 are reserved for user-specified operating systems. Value OS Type 0 Illegal 1 RT-11 2 RSTS/E 3 RSX-11S 4 RSX-11M 5 RSX-11D 6 IAS 7 VAX/VMS 8 TOPS-20 9 TOPS-10 10 RTS-8 11 OS-8 12 RSX-11M+ 13 COPOS/11 (TOPS-20 front-end) FILESYS(1) : B = File system type (of the file system being used by the process sending this message). Values in the range 1-191 are reserved for DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 21 DIGITAL use; 192-255 are reserved for user-specified file systems. Value System 0 Illegal 1 RMS-11 2 RMS-20 3 RMS-32 4 FCS-11 5 RT-11 6 No file system supported 7 TOPS-20 8 TOPS-10 9 OS-8 VERSION : = A field identifying the protocol and software version numbers. This field is subdivided as follows: VERNUM ECONUM USRNUM SOFTVER USRSOFT where: VERNUM(1) : B = DAP version number. This is the same as the first digit of the protocol version number. ECONUM(1) : B = DAP ECO (Modification) number. This is the same as the second digit of the protocol version number. USRNUM(1) : B = Customer modification level of DAP. Set to 0 by DIGITAL. SOFTVER(1) : B = DAP software version number in binary. This is the DIGITAL release number. If the software is completely user written, this field should be 0. USRSOFT(1) : B = User software version number in binary. If the user modifies DIGITAL software, he should increment this byte to reflect his modification number. Set to 0 by DIGITAL. SYSCAP(EX-12) : BM = Generic system capabilities. These are DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 22 defined as follows: Bit Meaning (When Set) 0 Supports file preallocation. 1 Supports sequential file organization. 2 Supports relative file organization. 3 Reserved - intended to support direct file organization. 4 Supports single keyed indexed file organization (reserved). 5 Supports sequential file transfer. 6 Supports random access by record number. 7 Supports random access by Virtual Block Number. 8 Supports random access by key. 9 Reserved - intended to support random access by user generated hash code. 10 Supports random access by Record File Address (RFA). 11 Supports multi-keyed indexed file organization. 12 Supports switching access mode (see RAC field in section 3.6). 13 Supports append to file access. 14 Supports command file submission and/or execution as specified in the Access Message. 15 Supports data compression (reserved). 16 Supports multiple data streams. 17 Supports status return (reserved). 18 Supports blocking of DAP messages up to response. (See note section 3.2.) 19 Supports unrestricted blocking of DAP messages. (See note section 3.2.) 20 Supports the use of two byte operand length in the DAP message header, i.e., LENGTH and LEN256. 21 Supports the file checksum option (See ACCOPT field in the Access Message and also section 5.5.2). 22 Supports the Key Definition Extended Attributes Message. 23 Supports the Allocation Extended Attributes Message. 24 Supports the Summary Extended Attributes Message. 25 Supports directory list. 26 Supports the Date and Time Extended DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 23 Attributes Message. 27 Supports the File Protection Extended Attributes Message. 28 Supports the Access Control List Extended Attributes Message (Reserved). 29 Supports spooling as specified by bit 20 of the FOP field (see Attributes and Access Complete Messages). 30 Supports command file submission as specified by bit 21 of the FOP field. 31 Supports file deletion as specified by bit 22 of the FOP field. 32 Supports the default file specification (see section 3.17) (reserved). 33 Supports sequential record access. 34 Supports the recovery option for file transfer (Reserved). 35 Supports the use of the BITCNT field in the Data Message. 36 Supports the warning Status Message (MACCODE = 6). 37 Supports the file rename operation. 38 Supports wildcard operations (see section 5.2.19). 39 Supports the Go/No-Go option (see section 3.5, ACCOPT field) (reserved). 40 Supports the Name Message. 41 Supports segmented DAP messages (see bit 6 of FLAGS field) (reserved). NOTE Bits 5 and 33 differentiate between the use of file transfer (see sections 5.2.1 and 5.2.2) and record access on sequential files (see section 5.2.3 and 5.2.4) where file transfer reduces overhead by eliminating the need for Control Messages. 3.4 Attributes Message The Attributes Message is used to describe how data is being represented in a file that is being accessed. The Attributes Message DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 24 is sent as a part of the initial set up. The Attributes Message format is as follows: ATTRIB ATTMENU DATATYPE ORG RFM RAT BLS MRS ALQ BKS FSZ MRN RUNSYS DEQ FOP BSZ DEV SDC LRL HBK EBK FFB SBN NOTES 1. Symbolic names, where supplied, refer to the corresponding RMS names. They are included here for ease of reference only; they have no meaning for DAP. 2. Values passed to the accessed system's file system may not be used literally in some cases. For example if a value of 0 is passed in the DEQ field, RMS systems will ignore the 0 and use the local default rather than return an error as might be expected. The application of defaults, as in this example, is a function of individual file systems and is in no way related to defaults as specified in DAP. If a field is present in a DAP message, no DAP specified default will be substituted in place of the value it contains. 3. Sometimes fields will be ignored if they are not applicable to the particular operation or are not supported and their omission will not affect the operation. For example, MRS is ignored by RMS as input to the OPEN operation. Also, with bit map fields, sometimes bits will be ignored where they are not applicable to the operation or not supported by that particular file system. where: ATTRIB : = The OPERATOR field with TYPE=2. ATTMENU(EX-6) : BM = The following bit map specifies which of the attributes fields will be present in the main attributes message when the corresponding bit is set. These fields and only these fields may appear in the message and they must be in the order specified. Bit Meaning (when set) 0 DATATYPE 1 ORG 2 RFM 3 RAT 4 BLS 5 MRS DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 25 6 ALQ 7 BKS 8 FSZ 9 MRN 10 RUNSYS 11 DEQ 12 FOP 13 BSZ 14 DEV 15 SDC (Reserved) 16 LRL 17 HBK 18 EBK 19 FFB 20 SBN DATATYPE(EX-2) : BM = The type of data being transferred. The default is Image. Unless a file has attributes specifying whether the file contains ASCII or Image data, the value (ASCII or Image) sent by the accessing process when opening a file, is returned by the accessed process. Bit Meaning (When Set) 0 ASCII (see Note 1). 1 IMAGE (default) (see Note 2 below). 2 EBCDIC (Reserved). 3 Compressed format. 4 Executable code. 5 Privileged code. 6 Reserved (set 0 when sending ATTRIBUTES message; ignore when receiving ATTRIBUTES message). 7 Sensitive data -- zero on delete. Data in file is to be set zero when the file is deleted for data security. NOTES 1. This is the 7-bit ASCII code set as defined in the 1968 ANSI Standard. When transmitting or receiving 7-bit ASCII in 8-bit frames, the high order bit is ignored except when using 7-bit compression. 2. Image is the mode where no code-set is specified. It is a format for sending 8-bit quantities in DAP without specifying any code representation. The DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 26 actual data may be ASCII, binary or anything else. It is up to the user process to determine how to use the data. See section 4.4.3. ORG(1) : B = Attributes of the file being accessed. These attributes are as follows: Value (octal) Meaning 0 FB$SEQ; Sequential (default). 20 FB$REL; Relative. 40 FB$IDX; Indexed. 60 FB$HSH; Hashed (Reserved). RFM(1) : B = Format of the records being transferred. These formats are as follows: Value Meaning 0 FB$UDF; Undefined record format. 1 FB$FIX; Fixed-length records (default). 2 FB$VAR; Variable-length records. 3 FB$VFC; Variable with fixed control format. 4 FB$STM; ASCII Stream Format. RAT(EX-3) : BM = Information about the attributes of individual records. The default is all bits set 0. Bit Meaning (When Set) 0 FB$FTN; Records contain FORTRAN carriage control (see Note 1). 1 FB$CR; Records have an implied LF/CR envelope. 2 FB$PRN; Print file carriage control where pre- and post-fix carriage control information is stored in the fixed header field of files in variable with fixed control (VFC) format. 3 FB$BLK; Records that do not span blocks (see Note 2). 4 Records have embedded format control (see Note 3). 5 Reserved (0) - Intended for COBOL carriage control. 6 FB$LSA; Line-sequenced ASCII Format. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 27 7 MACY11 format (see note 4) NOTES 1. FORTRAN Carriage Control. For line printers and some terminals, the first character of each record is to be treated as a carriage control character. 2. This bit when set informs the system that the record length should not exceed the physical device blocking size. With some systems and on some I/O devices (e.g., disk and magnetic tape) this may be a factor in determining the actual format used on the device. 3. This bit, when set, informs the system that format control characters (LF, VT, etc.) may be contained in records in the file. 4. MACY11 format is a standard used on 10's and 20's to store files destined for PDP-11's. These files usually contain 8-bit data such as object code output by a cross compiler. For details of MACY11, see MACY11 Record Format on TOPS-20 and TOPS-10, document retrieval no. SGR-78-003-00-S. BLS(2) : B = Physical block size in bytes on media. The default value is 512. The actual byte size is as specified by field BSZ. MRS(2) : B = The length of each file record in number of bytes. For variable-length records, this field specifies the maximum record size. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 28 When the accessed process receives the MRS (maximum record size), it must check it against the length of its buffer. If the buffer will not accommodate this size record, the accessed process should return an error. A zero value means no checking is performed on record size. MRS is used by the various file systems in a system dependent manner. The default is 0. ALQ(I-5) : B = This field specifies the allocation quantity in blocks. For file creation, it specifies the initial size of the new file. The actual size of the new file is returned in this field. The default is 0. NOTE On opening existing files, this value is ignored and this field is used only to return the file size. BKS(1) : B = Bucket size in blocks. Used for access to relative (not RMS-20), hashed and indexed files with RMS. The default is 0 (see Note 2 at the top of Section 3.4.) FSZ(1) : B = Size in bytes of fixed part of variable length record with fixed control format. The default is 0 (see Note 2 at the top of Section 3.4). MRN(I-5) : B = Maximum record number for file (for relative files only). If set to 0, checking is suppressed. The default is 0. RUNSYS(I-40) : A = Name of the Run-Time System environment required to execute the code contained in the file. This field is useful to operating systems that can emulate other operating system environments. The default value is accessed operating system dependent. DEQ(2) : B = File extension quantum size in virtual blocks, which is the amount of space, in blocks, added to the file each time the file is implicitly extended. The default is 0 (see Note 2 at the top of Section 3.4). FOP(EX-6) : BM = The file access options a user requires. The default is all bits set to 0. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 29 Bit Meaning (when set) 0 FB$RWO; rewind on open. 1 FB$RWC; rewind on close. 2 Reserved (0). 3 FB$POS; position magnetic tape just past the most recently created file. 4 FB$DLK; do not lock file if not properly closed. 5 Reserved (0). 6 File Locked. 7 FB$CTG; a contiguous file creation or extension required. 8 FB$SUP; supersede existing file on create. 9 FB$NEF; do not position to EOF on opening magnetic tape file for PUT. 10 FB$TMP; create temporary file. 11 FB$MKD; create temporary file and mark for delete on close. 12 Reserved (0). 13 FB$DMO; rewind and dismount magnetic tape on close. 14 FB$WCK; Enable Write checking. 15 FB$RCK; Enable Read checking. 16 FB$CIF; create new file if one by the same name does not exist. If one does exist, open the highest version of the file. 17 FB$LKO; Override file lock on open (reserved). 18 FB$SQO; Sequential access only. 19 FB$MXV; Maximize version number. 20 FB$SPL; Spool file to line printer (one copy only) on close. 21 FB$SCF; Submit as command file on close. 22 FB$DLT; Delete file on close. May be used as a sub-option with submit or spool. 23 FB$CBT; Contiguous best try. The file will be created, but it will be contiguous only when it it possible. 24 FB$WAT; Wait for file if it is locked by another process (reserved). 25 FB$DFW; Deferred write (REL and IDX files) 26 FB$TEF; Truncate at EOF on close (write accessed SEQ files). 27 FB$OFP; Output file parse (only name type sticky) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 30 BSZ(1) : B = Number of bits per byte for data stored in the file on the accessed node. Data is always transmitted in 8-bit frames (see Section 4.4). When a DAP Attributes Message is sent from the accessing to the accessed system, BSZ is required only when dealing with systems capable of supporting a variable byte size, e.g., TOPS-20. The default value for BSZ is the normal default for the accessed system's file system, e.g., 8 bits per byte for RSX. When the Attributes Message is returned from the accessed to the accessing system, BSZ should always be sent unless the default applies. The default for BSZ in a returned Attributes Message is 8 bits. DEV(EX-6) : BM = For attributes sent to the accessing node, this field contains the generic characteristics of the device on which a file resides. The default is all bits set to 0. Bit Meaning (When Set) 0 FB$REC ; record oriented. 1 FB$CCL ; carriage control device. 2 FB$TRM ; terminal. 3 FB$MDI ; directory structured. 4 FB$SDI ; single directory only. 5 FB$SQD ; sequential, block oriented (e.g. magnetic tape). 6 ; Null device. 7 FB$FOD ; a file-oriented device (e.g. a disk or magnetic tape). 8 ; device can be shared. 9 FB$SPL ; device is being spooled. 10 FB$MNT ; device is currently mounted. 11 FB$DMT ; device is marked for dismount. 12 FB$ALL ; device is allocated. 13 FB$IDV ; device is capable of providing input. 14 FB$ODV ; device is capable of providing output. 15 FB$SWL ; device is software write-locked. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 31 16 FB$AVL ; device is available for use. 17 FB$ELG ; device has error logging enabled. 18 FB$MBX ; device is a mailbox. 19 FB$RTM ; device is realtime in nature, not suitable for RMS use. 20 FB$RAD ; a random access device. 21 ; device has read checking enabled. 22 ; device has write checking enabled. 23 ; device is foreign, 24 ; network device. 25 ; generic device. SDC(EX-6) : BM = Spooling device characteristics. SDC uses (Reserved for the same bit definitions as in the DEV future use) field. If the file is spooled, SDC contains the characteristics of the spooling device. The characteristics of the ultimate device are contained in DEV. The default is all bits set to 0. LRL(2) : B = Longest record length. Length of the longest record in the file. HBK(I-5) : B = Highest virtual block allocated to the file. EBK(I-5) : B = End of file virtual block number. FFB(2) : B = First free byte in end of file block -- byte size as defined in BSZ. SBN(I-5) : B = Starting logical block number for file if contiguous; else 0. 3.5 Access Message The Access Message specifies the file name and type of access requested. The format for the access message is as follows: ACCESS ACCFUNC ACCOPT FILESPEC FAC SHR DISPLAY PASSWORD NOTE Symbolic names, where supplied, refer to the corresponding RMS names. They are included here for ease of reference only. They have no meaning for DAP. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 32 where: ACCESS : = The OPERATOR field with TYPE=3. ACCFUNC(1) : B = The request code specifying the operation to be performed is as follows: 1 - $OPEN; Open existing file. 2 - $CREATE; Open new file. 3 - $RENAME; Rename a file. 4 - $ERASE; Delete a file. 5 - Reserved. 6 - Directory List. 7 - Submit as a command (batch) file. 8 - Execute command (batch) file. If $RENAME is specified, the FILESPEC field below contains the old file specification and the new file specification is contained in the Name Message which follows the Access Message. If $CREATE is specified, but a file of that name already exists, the rules of the accessed node for file creation will be followed. For example, the file system may create a new file whose version number is one greater than the current highest version number. NOTE The Data Access Protocol (DAP) is not concerned with functions beyond remote data access. DAP should not be extended to attempt to cover RJE, Spooling, or other similar functions which, while they involve file transfer, are also concerned with command processing, parameter passing, and job queueing. The two command file submission commands are here for historical reasons, i.e. they have already been implemented in the first release of DAP-based software. However, their functionality will not be extended. two blank lines here ACCOPT(EX-5) : BM = The access options are as follows: Bit Meaning (When Set) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 33 0 I/O errors are non-fatal. A record may be skipped or repeated as specified by the Continue Transfer Message. If not set, I/O errors are fatal and terminate the access. 1 A status message will be returned following each record sent to the accessed process in the record access mode. (Reserved.) 2 A status message is returned with each record retrieved from an accessed system. The status message should precede the Data Message so that it is always possible to block the two into one NSP message. When a user requires a Record File Address (RFA) to be returned, this option is used. (Reserved.) 3 A 16 bit file checksum will be generated by both the transmitting and receiving nodes. When closing the file, the accessing process sends the checksum it generated to the accessed process in the Access Complete (Close) Message. The accessed process closes the file if the checksums agree. If they do not agree, it returns a status message. See section 5.5.2. 4 The Go/No-Go option is to be used with this operation. Go/No-Go is valid only for the Delete, Rename and Execute Command File functions and wildcard operations using these functions. Go/No-Go operation causes the accessed process to return the name of the file to the accessing process before executing the operation. The accessing process can then choose whether or not to perform the operation on the file by sending either a CONTR(Resume) or CONTR(Skip) (see section 5.2.19.2 for state operation). FILESPEC = The file specification in the format required (I-255) : A by the remote node. A null file specification assumes the meaning of a null file specification on the target node. FAC(EX-3) : BM = The file access operations a user requires: DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 34 Bit Meaning (When Set) 0 FB$PUT; Put access. 1 FB$GET; Get access (default). 2 FB$DEL; Delete access. 3 FB$UPD; Update access. 4 FB$TRN; Truncate access. 5 FB$BIO; Block I/O acess (see Note). 6 FB$BRO; Support switching between block and record I/O. NOTE FB$REA = FB$BIO!FB$GET; Block I/O Read access. FB$WRT = FB$BIO!FB$PUT; Block I/O write access. SHR(EX-3) : BM = Operations shared with other users: Bit Meaning (When Set) 0 FB$PUT; Put access. 1 FB$GET; Get access (default). 2 FB$DEL; Delete access. 3 FB$UPD; Update access. 4 FB$MSE; Enable multi-stream access. 5 FB$UPI; User provided interlocking (allows multiple writers to SEQ files). 6 FB$NIL; No access by other users. DISPLAY(EX-4): BM = Attributes and Extended Attributes Messages which are to be returned in response to this Access Message. See note 2 section 3.6. Bit Meaning (When Set) 0 Main Attributes Message (see Note 1, Section 5.1.2) 1 Key definition Attributes Message 2 Allocation Attributes Message 3 Summary Attributes Message 4 Date and Time Attributes Message 5 File Protection Attributes Message 6 reserved (0) 7 Access Control List Attributes Message (reserved) 8 Name Message containing resultant file specification. If the file was opened using logical name(s), this will return the file specification of file opened without logical names. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 35 NOTE When opening a file and DISPLAY requests key definition and allocation attributes for that file, the Attributes Message must be followed by Key Definition and Allocation Attributes Extension Messages specifiying for which keys and which areas this information is to be returned. If no keys or areas are specified, no key or area information will be returned. See Section 5.1.2 for the message sequence. PASSWORD(I-40): B = Password required to obtain access to file. 3.6 Control Message The Control Message is used to send control type information to a file system. The Control Message format is as follows: CONTROL CTLFUNC CTLMENU RAC KEY KRF ROP HSH DISPLAY where: CONTROL : = The OPERATOR field with TYPE=4. CTLFUNC(1) : B = Specific control information: Value Meaning 1 - $GET (or $READ for block I/O); get record (or block). If random access to a relative file is made, the KEY field contains the record number. If a random access to an indexed file is made, KEY contains the key. If sequential access is employed, get the next record. (Default). 2 - $CONNECT; initiate data stream. If multiple data streams are used, they are multiplexed on the STREAMID number. The STREAMID number in the Control Message is used to initiate a data stream. If DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 36 the STREAMID number is omitted, a default of zero is assumed. 3 - $UPDATE; update current record. Indicates to the accessed system the intent of the accessing system to update the currently positioned record with the next data transmission. 4 - $PUT (or $WRITE for block I/O); indicates to the accessed system, that the information to follow should be written into the file. one blank line here 5 - $DELETE; delete current record. 6 - $REWIND; rewind file. 7 - $TRUNCATE; truncate file. Writes end-of-file at current position. Used with sequential files only. 8 - $MODIFY; change file attributes (Reserved). 9 - $RELEASE; unlock record specified by Record File Address in KEY field. (Reserved). 10 - $FREE; unlock all locked records for this data stream. 11 - Reserved 12 - $FLUSH; write out all modified I/O buffers and attributes for this data stream. 13 - $NXTVOL; perform end-of-volume and start-of-next-volume processing. (Reserved). 14 - $FIND; find record. Same as 1, but the data is not transferred. 15 - $EXTEND; extend this file by the amount specified in the following Allocation Attributes Extension Message. (Reserved). 16 - $DISPLAY; retrieve this file's attributes as defined by the field DISPLAY. (Reserved). DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 37 17 - SPACE FORWARD; forward space the file by the number of blocks specified by KEY below. Block I/O only. 18 - SPACE BACKWARD; backward space the file by the number of blocks specified by KEY below. Block I/O only. 19 - CHECKPOINT; checkpoint the output file at the accessed node. An ACK response is returned when the checkpoint is completed. (Reserved). 20 - RECOVERY GET; restart file retrieval data transfer from the last checkpoint. The KEY field contains the input file checkpoint locater needed to restart data access from the remote input file. (Reserved). 21 - RECOVERY PUT; restart store file data transfer from last checkpoint. If the file is sequential, position remote output file to EOF before writing the data records which follow to disk. (Reserved). CTLMENU(EX-4):BM = The following bits when set, indicate the following optional fields are present. These fields and only these fields may appear in the message and they must be in the order specified. Bit Field 0 RAC 1 KEY 2 KRF 3 ROP 4 HSH (Reserved) 5 DISPLAY (Reserved) RAC(1) : B = Sets the access mode. If this field is not present, the option in force for the last access is retained. The default is 0 if not set previously. Value Meaning 0 - RB$SEQ; sequential record access. 1 - RB$KEY; keyed access. 2 - RB$RFA; Access by Record File Address (RFA -- an RMS specific access mode). 3 - sequential file access (the remainder of the file is transferred sequentially DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 38 from the current file position). 4 - block mode; access by Virtual Block Number. For retrieval, each block must be requested by a Control Message as in the record access mode. 5 - block mode file transfer. Blocks are transferred sequentially to end-of-file without need for a Control Message preceding each block transferred. An explicit Control (Get) or (Put) is required to start data moving. KEY(I-255) : B = File or Mode Key Relative Files Record Number Indexed Files Record Key Hashed Files Record Key Record File Address Access Mode Record File Address Block Mode Access Virtual Block Number (binary, range 1 to n) Recovery Input File Checkpoint Locater Non 8-bit quantities in the KEY field are right justified with the high order, unused bits set zero. If the key consists of 7-bit ASCII characters, each 7-bit character is right justified in an 8-bit frame as is usual for the transmission of ASCII characters. KRF(1) : B = Key of reference. If this field is not present, the key of reference is not changed. Default is primary if never set. 0 - primary key 1-254 - secondary key indicator ROP(EX-6) : BM = Optional record processing features. If this field is not present, the options in force for the last access are retained. Bit Meaning (When Set) 0 RB$EOF; position to EOF. 1 RB$FDL; fast delete -- mark record deleted but do not remove pointers from index. 2 RB$UIF; $PUT's update existing records in relative files. 3 RB$HSH; use hash code in HSH (Reserved). 4 RB$LOA; follow fill quantities. 5 RB$ULK; manual locking/unlocking. 6 RB$TPT; Truncate Put -- writes EOF DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 39 at current position. SEQ files only (Put also occurs). 7 RB$RAH; read ahead. 8 RB$WBH; write behind. 9 RB$KGE; key is >=. 10 RB$KGT; key is >. 11 RB$NLK; do not lock record. 12 RB$RLK; read a locked record (read only). 13 RB$BIOp block I/O. 14 RB$LIM; compare for key limit reached (reserved). 15 RB$NXR; non-existant record processing (reserved). HSH(I-5) : B = Hash code if keyed access on direct file is (Reserved for employed and the user is doing hashing. future use) DISPLAY(EX-4) : BM= Attributes Messages which are to be returned (Reserved for in response to a request to retrieve the future use) file's attributes are: Bit Meaning (When Set) 0 Main Attributes Message. 1 Key definition attributes. 2 Allocation attributes. 3 Summary Attributes Message. 4 Date and Time Attributes Message. 5 File Protection Attributes Message. 6 reserved (0) 7 Access Control List Attributes Message (reserved) 8 Name message containing resultant file specification -- if file opened using logical name(s), this will return the file specifcation of the file opened without logical names. NOTE 1. When a file's attributes and Key definition and/or allocation attributes have been requested in the DISPLAY field of a Control Message, the Control Message must have been preceded by Key Definition and/or Allocation Attributes Extension Messages specifying for which Keys and/or areas this information is to be returned. If no keys or areas are specified, no Key or area information will be returned. See section 5.2.10 for the message sequence. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 40 2. An accessing process seeing the accessed process does not support a particular message type (as indicated in the CONFIG from the accessed process) does not request that message type in the DISPLAY field of either the ACCESS or CONTROL messages. If an unsupported message type is requested, an error is returned. 3. FAL's written to versions of DAP prior to 5.6 will not return a Status Message for successful completion with GET, PUT, FIND and DELETE operations. FAL's written to DAP version 5.6 and later will return successful status for these operations. See sections 5.2.3, 5.2.4, 5.2.20 and 5.2.21 for the operation of these functions. 3.7 Continue Transfer Message The Continue Transfer Message is used when an error is detected in the I/O transfer and the user process wishes to continue DAP transfer. The normal use of this message would be to receive an error message, take appropriate action, and then send a Continue Transfer Message to allow the DAP link to resume operation. This message is also used when the accessed process suspends to await an operator decision as with Go/No-Go operation. The format of the Continue Transfer Message is: CONTRAN CONFUNC where: CONTRAN : = The OPERATOR field with TYPE=5. CONFUNC(1) : B = This field is used to specify the recovery action to be taken: Value Meaning 1 - Try again. 2 - Skip and continue. 3 - Abort transfer (i.e., discard all records in the pipeline until an Access Complete Message is found indicating the pipeline is clear). 4 - Resume processing (used to restart accessed process processing data for this data stream if the accessed process is DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 41 suspended). 3.8 Acknowledge Message The Acknowledge Message is used to acknowledge access commands, control connects and a checkpoint having been taken. Its format is as follows: ACKNOWLEDGE where: ACKNOWLEDGE: = THE OPERATOR field with TYPE=6. 3.9 Access Complete Message The Access Complete Message is used either to terminate access or to acknowledge a request to terminate access. The Access Complete Message format is as follows: ACCOMP CMPFUNC FOP CHECK where: ACCOMP : = The OPERATOR field with TYPE=7. CMPFUNC(1) : B = The access completion functions are: Value Meaning 1 Close. Terminate access. Close a file that is currently open. When multiple data streams are in use, they are all closed ($CLOSE). 2 Response. Sent by the accessed process in response to all Access Complete messages from the accessing process unless an error occurs. 3 Purge. A file is to be purged. That is, closed and deleted ($CLOSE + $ERASE). 4 End-of-stream. Terminate the data stream associated with this STREAMID number but do not close the file ($DISCONNECT). 5 Skip. For use with a series of wildcard transfers. Close the file currently associated with this link (forcefully, if necessary -- ignore any errors that may occur in closing the file) and go on to DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 42 process the next file. NOTE FAL's written to DAP version 4.1 will not return an ACCOMP (Response) to an ACCOMP(EOS). FAL's written to later versions of DAP will return an ACCOMP (Response). The Access Complete (EOS) does not close the file. The accessed process should be in a state wherein it can accept another Control (Connect) to open another stream. two blank lines here FOP(EX-6) : BM = The file access options a user requires. Refer to Section 3.4 for option values. If any portion of the FOP field in the ACCOMP is present, the whole FOP from the ATTRIBUTES is superceded with unspecified bits being set 0. CHECK(2) : B = The 16 bit file checksum if requested in the ACCOPT field of the Access Message. See Section 5.5.2. The checksum is sent only in the Access Complete (Close) Message. A Status Message is returned if the checksum is incorrect. When this field is present, the checksums are compared by the accessed process. If this field is absent, no checksum comparision is made and the file is closed even if it is known to contain errors. 3.10 Data Message The Data Message is used to transfer the file data over a DAP link. The Data Message format is as follows: DATA RECNUM FILEDATA where: DATA : = The OPERATOR field with TYPE=8 RECNUM(I-8) : B = This field is used to send the record number when accessing relative files (or sequential files in a relative manner, i.e., by record number). For random store, this field will contain the record number (for relative files) or hash code (if the user is generating his own hash codes with hashed DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 43 files). When RECNUM is not used, the byte count is zero. When in block mode, this field will contain the VBN instead of the record number. For file retrieval with recovery, this field contains the input file checkpoint locater. FILEDATA = The file data being transferred. This field is totally transparent and uses all 8-bits of each byte. 3.11 Status Message The status message is used to return information on the status of DAP messages or data transfers. It is sent synchronously in response to another DAP message or an error during data transfer. The format is: STATUS STSCODE RFA RECNUM STV where: STATUS = The OPERATOR field with TYPE=9 STSCODE = A 2-byte status field (16 bits) subdivided as: 15 12 11 0 ------------------------ !MACCODE! MICCODE ! ------------------------ where: MACCODE(4B):B = The macro or functional group reason for the Status Message. Values for this field are specified in Table 3-1. MICCODE(12B):B= The specific type of status (by MACCODE type). Values for this field are specified in Tables 3-2, 3-3 and 3-4. one blank line here RFA(I-8) : B = Used to return the Record File Adddress of the record to which this Status Message applies. If the Access Message field ACCOPT indicates a return of status after each record is stored, then this field contains the record file address of the record in the accessed system's file. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 44 RECNUM(I-8) : B = Used to return the record number for relative files when a status message is returned after each record is transferred (as specified in the ACCOPT field of the Access Message). Null for non-relative files. STV(I-8) : B = Secondary status. Used to return secondary status information where required (e.g., RMS uses it for device error codes). DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 45 Table 3-1. MACCODE Field Values Value (Octal) Name Meaning 0 Pending Operation in progress. 1 Successful Returns information that indicates success. 2 Unsupported This implementation of DAP does not support the specified request. For example, this is used when an unsupported bit/field or a field/value is encountered which a particular implementation does not support. 3 Reserved. 4 File Open Errors that occur before a file is successfully opened. 5 Transfer Errors that occur after opening a file Error and before closing that file. 6 Transfer For operations on open files, indicates Warning the operation completed but not with complete success. 7 Access Termination Errors associated with terminating access to a file. 10 Format Error in parsing a message. Format is not correct. 11 Invalid Field of message is invalid (e.g., bits that are meant to be mutually exclusive are set, an undefined bit is set, a field value is out of range or an illegal string is in a field). 12 Sync DAP message received out of synchronization. 13-15 Reserved. 16-17 User defined STATUS MACCODES DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 46 Table 3-2. MICCODE Field Values for Use with MACCODE Values of 2, 10, and 11 Octal Type of Error Code Reason (Octal) NOTE MICCODE Format: Bits 0-5 specify the DAP message field number. Bits 6-11 specify the DAP message type number. Miscellaneous 00 00 Unspecified DAP message error. 00 10 DAP message type field (TYPE) error. Configuration 01 00 Unknown field. Message errors by field 01 10 DAP message flags field (FLAGS). 01 11 Data stream identification field (STREAMID). 01 12 Length field (LENGTH). 01 13 Length extension field (LEN256) 01 14 BITCNT field (BITCNT) 01 20 Buffer size field (BUFSIZ). 01 21 Operating system type field (OSTYPE). 01 22 File system type field (FILESYS). 01 23 DAP version number field (VERNUM). 01 24 ECO version number field (ECONUM). 01 25 USER protocol version number field (USRNUM). 01 26 DEC software release number field (SOFTVER). 01 27 User software release number field (USRSOFT). 01 30 System capabilities field (SYSCAP). Attributes 02 00 Unknown field. Message errors by field 02 10 DAP message flags field (FLAGS). 02 11 Data stream identification field (STREAMID). 02 12 Length field (LENGTH). 02 13 Length extension field (LEN 256) 02 14 Bit count field (BITCNT) 02 15 System specific field (SYSPEC). 02 20 Attributes menu field (ATTMENU). 02 21 Data type field (DATATYPE). 02 22 File organization field (ORG). 02 23 Record format field (RFM). 02 24 Record attributes field (RAT). 02 25 Block size field (BLS). DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 47 02 26 Maximum record size field (MRS). 02 27 Allocation quantity field (ALQ). 02 30 Bucket size field (BKS). 02 31 Fixed control area size field (FSZ). 02 32 Maximum record number field (MRN). 02 33 Run-time system field (RUNSYS). 02 34 Default extension quantity field (DEQ). 02 35 File options field (FOP). 02 36 Byte size field (BSZ). 02 37 Device characteristics field (DEV). 02 40 Spooling device characteristics field (SDC); Reserved. 02 41 Longest record length field (LRL). 02 42 Highest virtual block allocated field (HBK). 02 43 End of file block field (EBK). 02 44 First free byte field (FFB). 02 45 Starting LBN for contiguous file (SBN). Access 03 00 Unknown field. Message errors by field 03 10 DAP message flags field (FLAGS). 03 11 Data stream identification field (STREAMID). 03 12 Length field (LENGTH). 03 13 Length extension field (LEN256) 03 14 Bit count field (BITCNT) 03 15 System specific field (SYSPEC). 03 20 Access function field (ACCFUNC). 03 21 Access options field (ACCOPT). 03 22 File specification field (FILESPEC). 03 23 File access field (FAC). 03 24 File sharing field (SHR). 03 25 Display attributes request field (DISPLAY). 03 26 File password field (PASSWORD). Control 04 00 Unknown field. Message errors by field 04 10 DAP message flags field (FLAGS). 04 11 Data stream identification field (STREAMID). 04 12 Length field (LENGTH). 04 13 Length extension field (LEN256) 04 14 Bit count field (BITCNT) 04 15 System specific field (SYSPEC). 04 20 Control function field (CTLFUNC). 04 21 Control menu field (CTLMENU). 04 22 Record access field (RAC). 04 23 Key field (KEY). 04 24 Key of reference field (KRF). 04 25 Record options field (ROP). 04 26 Hash code field (HSH); Reserved for DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 48 future use. 04 27 Display attributes request field (DISPLAY). Continue 05 00 Unknown field. Message errors by field 05 10 DAP message flags field (FLAGS). 05 11 Data stream identification field (STREAMID). 05 12 Length field (LENGTH). 05 13 Length extension field (LEN256) 05 14 Bit count field (BITCNT) 05 15 System specific field (SYSPEC). 05 20 Continue transfer function field (CONFUNC). Acknowledge 06 00 Unknown field. Message errors by field 06 10 DAP message flags field (FLAGS). 06 11 Data stream identification field (STREAMID). 06 12 Length field (LENGTH). 06 13 Length extension field (LEN256) 06 14 Bit count field (BITCNT) 06 15 System specific field (SYSPEC). Access Complete 07 00 Unknown field. Message errors by field 07 10 DAP message flags field (FLAGS). 07 11 Data stream identification field (STREAMID). 07 12 Length field (LENGTH). 07 13 Length extension field (LEN256) 07 14 Bit count field (BITCNT) 07 15 System specific field (SYSPEC). 07 20 Access complete function field (CMPFUNC). 07 21 File options field (FOP). 07 22 Checksum field (CHECK). Data Message 10 00 Unknown field. errors by field 10 10 DAP message flags field (FLAGS). 10 11 Data stream identification field (STREAMID). 10 12 Length field (LENGTH). 10 13 Length extension field (LEN256) 10 14 Bit count field (BITCNT) 10 15 System specific field (SYSPEC). 10 20 Record number field (RECNUM). 10 21 File data field (FILEDATA). DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 49 Status Message 11 00 Unknown field. errors by field 11 10 DAP message flags field (FLAGS). 11 11 Data stream identification field (STREAMID). 11 12 Length field (LENGTH). 11 13 Length extension field (LEN256) 11 14 Bit count field (BITCNT) 11 15 System specific field (SYSPEC). 11 20 Macro status code field (MACCODE). 11 21 Micro status code field (MICCODE). 11 22 Record file address field (RFA). 11 23 Record number field (RECNUM). 11 24 Secondary status field (STV). Key Definition 12 00 Unknown field Message errors by field: 12 10 DAP message flags field (FLAGS) 12 11 Data stream identification field (STREAMID) 12 12 Length field (LENGTH) 12 13 Length extension field (LEN256) 12 14 Bit count field (BITCNT) 12 15 System specific field (SYSPEC). 12 20 Key definition menu field (KEYMENU) 12 21 Key option flags field (FLG) 12 22 Data bucket fill quantity field (DFL) 12 23 Index bucket fill quantity field (IFL) 12 24 Key segment repeat count field (SEGCNT) 12 25 Key segment position field (POS) 12 26 Key segment size field (SIZ) 12 27 Key of reference field (REF) 12 30 Key name field (KNM) 12 31 Null key character field (NUL) 12 32 Index area number field (IAN) 12 33 Lowest level area number field (LAN) 12 34 Data level area number field (DAN) 12 35 Key data type field (DTP) 12 36 Root VBN for this key field (RVB) 12 37 Hash algorithm value field (HAL) 12 40 First data bucket VBN field (DVB). 12 41 Data bucket size field (DBS). 12 42 Index bucket size field (IBS). 12 43 Level of root bucket field (LVL). 12 44 Total key size field (TKS). 12 45 Minimum record size field (MRL). Allocation 13 00 Unknown field message errors by field: 13 10 DAP message flags field (FLAGS) 13 11 Data stream identification field (STREAMID) 13 12 Length field (LENGTH) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 50 13 13 Length extension field (LEN256) 13 14 Bit count field (BITCNT) 13 15 System specific field (SYSPEC). 13 20 Allocation menu field (ALLMENU) 13 21 Relative volume number field (VOL) 13 22 Alignment options field (ALN) 13 23 Allocation options field (AOP) 13 24 Starting location field (LOC) 13 25 Related file identification field (RFI) 13 26 Allocation quantity field (ALQ) 13 27 Area identification field (AID) 13 30 Bucket size field (BKZ) 13 31 Default extension quantity field (DEQ) Summary 14 00 Unknown field. Message errors by field 14 10 DAP message flags field (FLAGS). 14 11 Data stream identification field (STREAMID). 14 12 Length field (LENGTH) 14 13 Length extension field (LEN256) 14 14 Bit count field (BITCNT) 14 15 System specific field (SYSPEC). 14 20 Summary menu field (SUMENU) 14 21 Number of keys field (NOK) 14 22 Number of areas field (NOA) 14 23 Number of record descriptors field (NOR) 14 24 Prologue version number (PVN) Date and Time 15 00 Unknown field Message 15 10 DAP message flags field (FLAGS) errors by field 15 11 Data stream identification field (STREAMID) 15 12 Length field (LENGTH) 15 13 Length extension field (LEN256) 15 14 Bit count field (BITCNT) 15 15 System specific field (SYSPEC). 15 20 Date and time menu field (DATMENU) 15 21 Creation date and time field (CDT) 15 22 Last update date and time field (RDT) 15 23 Deletion date and time field (EDT) 15 24 Revision number field (RVN). Protection 16 00 Unknown field Message 16 10 DAP message flags field (FLAGS) errors by field 16 11 Data stream identification field (STREAMID) 16 12 Length field (LENGTH) 16 13 Length extension field (LEN256) 16 14 Bit count field (BITCNT) 16 15 System specific field (SYSPEC). DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 51 16 20 Protection menu field (PROTMENU) 16 21 File owner field (OWNER) 16 22 System protection field (PROTSYS) 16 23 Owner protection field (PROTOWN) 16 24 Group protection field (PROTGRP) 16 25 World protection field (PROTWLD) Name Message 17 00 Unknown field errors by field 17 10 DAP message flags field (FLAGS) 17 11 Data stream identification field (STREAMID) 17 12 Length field (LENGTH) 17 13 Length extension field (LEN256) 17 14 Bit count field (BITCNT) 17 15 System specific field (SYSPEC). 17 20 Name type field (NAMETYPE) 17 21 Name field (NAMESPEC) Access Control 20 00 Unknown field List Message errors by field: 20 10 DAP message flags field (FLAGS) (Reserved for 20 11 Data stream identification field future use) (STREAMID). 20 12 Length field (LENGTH) 20 13 Length extension field (LEN256) 20 14 Bit count field (BITCNT) 20 15 System specific field (SYSPEC). 20 20 Access control list repeat count field (ACLCNT) 20 21 Access control list entry field (ACL) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 52 Table 3-3. MICCODE Field Values for Use with MACCODE Values of 0, 1, 4, 5, 6, and 7 Octal Value Error/Reason (Octal) NOTE MICCODE Format: Bits 0-11 contain the error code number. Symbolic status codes, where supplied, refer to the corresponding RMS status codes. They are included here for ease of reference only -- they have no meaning for DAP. 0 Unspecified error. 1 ER$ABO; operation aborted. 2 ER$ACC; F11-ACP could not access file. 3 ER$ACT; "FILE" activity precludes operation. 4 ER$AID; bad area ID. 5 ER$ALN; alignment options error. 6 ER$ALQ; allocation quantity too large or 0 value. 7 ER$ANI; not ANSI "D" format. 10 ER$AOP; allocation options error. 11 ER$AST; invalid (i.e., synch) operation at AST level. 12 ER$ATR; attribute read error. 13 ER$ATW; attribute write error. 14 ER$BKS; bucket size too large. 15 ER$BKZ; bucket size too large. 16 ER$BLN; "BLN" length error. 17 ER$BOF; beginning of file detected. 20 ER$BPA; private pool address. 21 ER$BPS; private pool size. 22 ER$BUG; internal RMS error condition detected. 23 ER$CCR; cannot connect RAB. 24 ER$CHG; $UPDATE changed a key without having attribute of XB$CHG set. 25 ER$CHK; bucket format check-byte failure. 26 ER$CLS; RSTS/E close function failed. 27 ER$COD; invalid or unsupported "COD" field. 30 ER$CRE; F11-ACP could not create file (STV=sys err code). 31 ER$CUR; no current record (operation not preceded by GET/FIND). 32 ER$DAC; F11-ACP deaccess error during "CLOSE". 33 ER$DAN; data "AREA" number invalid. 34 ER$DEL; RFA-Accessed record was deleted. 35 ER$DEV; bad device, or inappropriate device type. 36 ER$DIR; error in directory name. 37 ER$DME; dynamic memory exhausted. 40 ER$DNF; directory not found. 41 ER$DNR; device not ready. 42 ER$DPE; device has positioning error. 43 ER$DTP; "DTP" field invalid. 44 ER$DUP; duplicate key detected, XB$DUP not set. 45 ER$ENT; RSX-F11ACP enter function failed. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 53 46 ER$ENV; operation not selected in "ORG$" macro. 47 ER$EOF; end-of-file. 50 ER$ESS; expanded string area too short. 51 ER$EXP; file expiration date not yet reached. 52 ER$EXT; file extend failure. 53 ER$FAB; not a valid FAB ("BID" NOT = FB$BID). 54 ER$FAC; illegal FAC for REC-OP,0, or FB$PUT not set for "CREATE". 55 ER$FEX; file already exists. 56 ER$FID; invalid file I.D. 57 ER$FLG; invalid flag-bits combination. 60 ER$FLK; file is locked by other user. 61 ER$FND; RSX-F11ACP "FIND" function failed. 62 ER$FNF; file not found. 63 ER$FNM; error in file name. 64 ER$FOP; invalid file options. 65 ER$FUL; DEVICE/FILE full. 66 ER$IAN; index "AREA" number invalid. 67 ER$IFI; invalid IFI value or unopened file. 70 ER$IMX; maximum NUM(254) areas/key XABS exceeded. 71 ER$INI; $INIT macro never issued. 72 ER$IOP; operation illegal or invalid for file organization. 73 ER$IRC; illegal record encountered (with sequential files only). 74 ER$ISI; invalid ISI value, on unconnected RAB. 75 ER$KBF; bad KEY buffer address (KBF=0). 76 ER$KEY; invalid KEY field (KEY=0/neg). 77 ER$KRF; invalid key-of-reference ($GET/$FIND). 100 ER$KSZ; KEY size too large. 101 ER$LAN; lowest-level-index "AREA" number invalid. 102 ER$LBL; not ANSI labeled tape. 103 ER$LBY; logical channel busy. 104 ER$LCH; logical channel number too large. 105 ER$LEX; logical extend error, prior extend still valid. 106 ER$LOC; "LOC" field invalid. 107 ER$MAP; buffer mapping error. 110 ER$MKD; F11-ACP could not mark file for deletion. 111 ER$MRN; MRN value=neg or relative key>MRN. 112 ER$MRS; MRS value=0 for fixed length records. Also 0 for relative files. 113 ER$NAM; "NAM" block address invalid (NAM=0, or not accessible). 114 ER$NEF; not positioned to EOF (sequential files only). 115 ER$NID; cannot allocate internal index descriptor. 116 ER$NPK; indexed file; no primary key defined. 117 ER$OPN; RSTS/E open function failed. 120 ER$ORD; XAB'S not in correct order. 121 ER$ORG; invalid file organization value. 122 ER$PLG; error in file's prologue (reconstruct file). 123 ER$POS; "POS" field invalid (POS>MRS,STV=XAB indicator). 124 ER$PRM; bad file date field retrieved. 125 ER$PRV; privilege violation (OS denies access). 126 ER$RAB; not a valid RAB ("BID" NOT=RB$BID). 127 ER$RAC; illegal RAC value. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 54 130 ER$RAT; illegal record attributes. 131 ER$RBF; invalid record buffer address ("ODD", or not word-aligned if BLK-IO). 132 ER$RER; file read error. 133 ER$REX; record already exists. 134 ER$RFA; bad RFA value (RFA=0). 135 ER$RFM; invalid record format. 136 ER$RLK; target bucket locked by another stream. 137 ER$RMV; RSX-F11 ACP remove function failed. 140 ER$RNF; record not found. 141 ER$RNL; record not locked. 142 ER$ROP; invalid record options. 143 ER$RPL; error while reading prologue. 144 ER$RRV; invalid RRV record encountered. 145 ER$RSA; RAB stream currently active. 146 ER$RSZ; bad record size (RSZ>MRS, or NOT=MRS if fixed length records). 147 ER$RTB; record too big for user's buffer. 150 ER$SEQ; primary key out of sequence (RAC=RB$SEQ for $PUT). 151 ER$SHR; "SHR" field invalid for file (cannot share sequential files). 152 ER$SIZ; "SIZ field invalid. 153 ER$STK; stack too big for save area. 154 ER$SYS; system directive error. 155 ER$TRE; index tree error. 156 ER$TYP; error in file type extension on FNS too big. 157 ER$UBF; invalid user buffer addr (0, odd, or if BLK-IO not word aligned). 160 ER$USZ; invalid user buffer size (USZ=0). 161 ER$VER; error in version number. 162 ER$VOL; invalid volume number. 163 ER$WER; file write error (STV=sys err code). 164 ER$WLK; device is write locked. 165 ER$WPL; error while writing prologue. 166 ER$XAB; not a valid XAB (@XAB=ODD,STV=XAB indicator). 167 BUGDDI; default directory invalid. 170 CAA ; cannot access argument list. 171 CCF ; cannot close file. 172 CDA ; cannot deliver AST. 173 CHN ; channel assignment failure (STV=sys err code). 174 CNTRLO; terminal output ignored due to (CNTRL) O. 175 CNTRLY; terminal input aborted due to (CNTRL) Y. 176 DNA ; default filename string address error. 177 DVI ; invalid device I.D. field. 200 ESA ; expanded string address error. 201 FNA ; filename string address error. 202 FSZ ; FSZ field invalid. 203 IAL ; invalid argument list. 204 KFF ; known file found. 205 LNE ; logical name error. 206 NOD ; node name error. 207 NORMAL; operation successful. 210 OK_DUP; record inserted had duplicate key. 211 OK_IDX; index update error occurred-record inserted. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 55 212 OK_RLK; record locked but read anyway. 213 OK_RRV; record inserted in primary o.k.; may not be accessible by secondary keys or RFA. 214 CREATE; file was created, but not opened. 215 PBF ; bad prompt buffer address. 216 PNDING; async. operation pending completion. 217 QUO ; quoted string error. 220 RHB ; record header buffer invalid. 221 RLF ; invalid related file. 222 RSS ; invalid resultant string size. 223 RST ; invalid resultant string address. 224 SQO ; operation not sequential. 225 SUC ; operation successful. 226 SPRSED; created file superseded existing version. 227 SYN ; filename syntax error. 230 TMO ; time-out period expired. 231 ER$BLK; FB$BLK record attribute not supported. 232 ER$BSZ; bad byte size. 233 ER$CDR; cannot disconnect RAB. 234 ER$CGJ; cannot get JFN for file. 235 ER$COF; cannot open file. 236 ER$JFN; bad JFN value. 237 ER$PEF; cannot position to end-of-file. 240 ER$TRU; cannot truncate file. 241 ER$UDF; file is currently in an undefined state; access is denied. 242 ER$XCL; file must be opened for exclusive access. 243 ; directory full. 244 ; handler not in system. 245 ; fatal hardware error. 246 ; attempt to write beyond EOF. 247 ; hardware option not present. 250 ; device not attached. 251 ; device already attached. 252 ; device not attachable. 253 ; sharable resource in use. 254 ; illegal overlay request. 255 ; block check or CRC error. 256 ; caller's nodes exhausted. 257 ; index file full. 260 ; file header full. 261 ; accessed for write. 262 ; file header checksum failure. 263 ; attribute control list error. 264 ; file already accessed on LUN. 265 ; bad tape format. 266 ; illegal operation on file descriptor block. 267 ; rename; 2 different devices. 270 ; rename; new filename already in use. 271 ; cannot rename old file system. 272 ; file already open. 273 ; parity error on device. 274 ; end of volume detected. 275 ; data over-run. 276 ; bad block on device. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 56 277 ; end of tape detected. 300 ; no buffer space for file. 301 ; file exceeds allocated space -- no blks. 302 ; specified task not installed. 303 ; unlock error. 304 ; no file accessed on LUN. 305 ; send/receive failure. 306 SPL ; spool or submit command file failure. 307 NMF ; no more files. 310 CRC ; DAP file transfer Checksum error. 311 ; Quota exceeded 312 BUGDAP; internal network error condition detected. 313 CNTRLC; terminal input aborted due to (CNTRL) C. 314 DFL ; data bucket fill size > bucket size in XAB. 315 ESL ; invalid expanded string length. 316 IBF ; illegal bucket format. 317 IBK ; bucket size of LAN NOT = IAN in XAB. 320 IDX ; index not initialized. 321 IFA ; illegal file attributes (corrupt file header). 322 IFL ; index bucket fill size > bucket size in XAB. 323 KNM ; key name buffer not readable or writeable in XAB. 324 KSI ; index bucket will not hold two keys for key of reference. 325 MBC ; multi-buffer count invalid (negative value). 326 NET ; network operation failed at remote node. 327 OK_ALK; record is already locked. 330 OK_DEL; deleted record successfully accessed. 331 OK_LIM; retrieved record exceeds specified key value. 332 OK_NOP; key XAB not filled in. 333 OK_RNF; nonexistent record successfully accessed. 334 PLV ; unsupported prologue version. 335 REF ; illegal key-of-reference in XAB. 336 RSL ; invalid resultant string length. 337 RVU ; error updating rrv's, some paths to data may be lost. 340 SEG ; data types other than string limited to one segment in XAB. 341 ; reserved 342 SUP ; operation not supported over network. 343 WBE ; error on write behind. 344 WLD ; invalid wildcard operation. 345 WSF ; working set full (can not lock buffers in working set.) 346 ; directory listing -- error in reading volume-set name, directory name, of file name. 347 ; directory listing -- error in reading file attributes. 350 ; directory listing -- protection violation in trying to read the volume-set, directory or file name. 351 ; directory listing -- protection violation in trying to read file attributes. 352 ; directory listing -- file attributes do not exist. 353 ; directory listing -- unable to recover directory DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 57 list after Continue Transfer (Skip). 354 SNE ; sharing not enabled. 355 SPE ; sharing page count exceeded. 356 UPI ; UPI bit not set when sharing with BRO set. 357 ACS ; error in access control string (poor man's route through error). 360 TNS ; terminator not seen. 361 BES ; bad escape sequence. 362 PES ; partial escape sequence. 363 WCC ; invalid wildcard context value. 364 IDR ; invalid directory rename operation. 365 STR ; user structure (FAB/RAB) became invalid during operation. 366 FTM ; network file transfer made precludes operation. 6000 ; user defined errors to 7777 DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 58 Table 3-4. MICCODE Field Values (with MACCODE Value of 12 Octal) Value Error/Reason (Octal) NOTE MICCODE Format: Bits 0-11 contain the message type number. 0 Unknown Message Type 1 Configuration Message 2 Attributes Message 3 Access Message 4 Control Message 5 Continue Transfer Message 6 Acknowledge Message 7 Access Complete Message 10 Data Message 11 Status Message 12 Key Definition Attributes Extension Message 13 Allocation Attributes Extension Message 14 Summary Attributes Extension Message 15 Date and Time Attributes Extension Message 16 Protection Attributes Extension Message 17 Name message 20 Access Control List Extended Attributes Message DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 59 3.12 Key Definition Attributes Extension Message Each key is defined by a group of 19 fields. The form of the key definition message is: KEYDEF,KEYMENU,FLG,DFL,IFL,NSG,POS,SIZ[,POS,SIZ...],REF,KNM, NUL,IAN,LAN,DAN,DTP,RVB,HAL,DVB,DBS,IBS,LVL,TKS,MRL KEYDEF : = The operator field with TYPE=10. KEYMENU(EX-6) : BM = The following bit map specifies which of the following fields are present in this message. These fields and only these fields may appear in the message and they must be in the order specified. Bit Meaning (When Set) 0 FLG 1 DFL 2 IFL 3 NSG, POS and SIZ 4 REF 5 KNM 6 NUL 7 IAN 8 LAN 9 DAN 10 DTP 11 RVB 12 HAL (Reserved) 13 DVB 14 DBS 15 IBS 16 LVL 17 TKS 18 MRL FLG(EX-3) : BM = Key option flag bit 0 = XB$DUP - duplicates allowed bit 1 = XB$CHG - allow keys to change bit 2 = XB$NUL - null key character defined DFL(2) : B = Data bucket fill IFL(2) : B = Index bucket fill NSG(1) : B = Number of segments (max. 8) needed to define the key in the record. For each segment, there will be a POS, SIZ pair. For example, if NSG contains 3, the following sequence of fields would appear: DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 60 NSG,POS,SIZ,POS,SIZ,POS,SIZ POS(2) : B = Position of key in record by byte number. The first byte in the record is byte 0. SIZ(1) : B = Size of key in record in bytes. REF(1) : B = Key of reference indicator KNM(I-40):A= Key name correspoding to key of reference (REF) above. NUL(1) : B = Value of null key character IAN(1) : B = Index area number LAN(1) : B = Lowest level index area number DAN(1) : B = Data level area number DTP(1) : B = Data type RVB(I-8) : B = Root VBN for key HAL(I-5) : B = Hash algorithm value (Reserved) DVB(I-8) : B = First data bucket start virtual block number. DBS(1) : B = Data bucket size field. IBS(1) : B = Index bucket size field. LVL(1) : B = Level of root bucket. TKS(1) : B = Total key size. MRL(2) : B = Minimum record length; the minimum record length in bytes which will totally contain the key field for the key described by this message. 3.13 Allocation Attributes Extension Message The Allocation Message is used when creating or explicitly extending a file to specify the character of the allocation. The form of the allocation message is: ALLOC,ALLMENU,VOL,ALN,AOP,LOC,RFI,ALQ,AID,BKZ,DEQ ALLOC : = The operator field with TYPE=11 ALLMENU(EX-6): BM = The following bit map specifies which of the following fields are present in this message. These fields and only these fields may appear in DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 61 the message and they must be in the order specified. Bit Meaning (When Set) 0 VOL 1 ALN 2 AOP 3 LOC 4 RFI (reserved) 5 ALQ 6 AID 7 BKZ 8 DEQ VOL(2) : B = Relative volume number of a volume set on which this area or file will be allocated. ALN(1) : BM = Alignment options Value Meaning 0 = XB$ANY - No specified allocation placement 1 = XB$CYL - Align on cylinder boundry 2 = XB$LBN - Align to specified logical block 3 = XB$VBN - Allocate as near as possible to specified virtual block 4 = XB$RFI - Allocate as near as possible to specified related file AOP(EX-4) : BM = Allocation options bit 0 = XB$HRD - If the requested alignment can not be done, return an error. bit 1 = XB$CTG - Contiguous allocation required bit 2 = XB$CBT - Contiguous best try. The file will be created, but it will be contiguous only when it is possible. bit 3 = XB$ONC - Allocate space on any cylinder boundry. LOC(I-8) : B = Allocation starting point. Value is as follows: If ALN = XB$CYL, LOC is the cylinder number where allocation is to start. If ALN = XB$LBN, LOC is the logical block where allocation is to start. If ALN = XB$VBN, LOC is the virtual block near which allocation should start; 0 (default) means as near as possible to current EOF. If ALN = XB$RFI, LOC is a VBN but a VBN in the related file. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 62 RFI(I-16) : B = Related file I.D. (Reserved) ALQ(I-5) : B = The amount of space in virtual blocks to be allocated. Returns actual size of allocation. For DISPLAY, returns size of area. AID(1) : B = Area I.D. The area number used to identify an area for reference by a key definition. BKZ(1) : B = Bucket size for this area. DEQ(2) : B = The default extension quantity in virtual blocks. Specifies the amount of space to be added to the area whenever it is extended automatically. It overrides the DEQ in the main Attributes Message. 3.14 Summary Attributes Extension Message The Summary Attributes Extension Message is composed of the fields described below. This message is optionally returned to the accessing process by the accessed process on a file open, file create, display of a file's attributes or directory list. The form of the Summary Attributes Extension Message is: SUMMARY, SUMENU, NOK, NOA, NOR, PVN where: SUMMARY : = The operator field with TYPE =12. SUMENU(EX-6) : BM = The following bit map specifies which of the following fields are present in this message. These fields and only these fields may appear in the message and they must appear in the order specified. Bit Meaning (when set) 0 NOK 1 NOA 2 NOR 3 PVN NOK(1) : B = Number of keys defined in file. NOA(1) : B = Number of areas defined in file. NOR(1) : B = Number of record descriptors in file. PVN(2) : B = Prologue version number. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 63 3.15 Date and Time Attributes Extension Message The Date and Time Attributes Extension Message is composed of the fields described below. This message is optionally returned to the accessing process by the accessed process on a file open, file create, display of a file's attributes or directory list. The form of the message is: DATIME, DATMENU, CDT, RDT, EDT, RVN where: DATIME : = The operator field with TYPE = 13. DATMENU(EX-6) : BM = The following bit map specifies which of the following fields are present in this message. These fields and only these fields may appear in the message and they must appear in the order specified. Bit Meaning (When set) 0 CDT 1 RDT 2 EDT 3 RVN CDT(18) : A = Date and time file created in Network Standard Time (NST). RDT(18) : A = Date and time file last updated in NST. EDT(18) : A = Date and time file may be deleted in NST. The preceding three fields should be in the following format: dd-mon-yybhh:mm:ss where: dd is the day mon is a three letter abbreviation for the month as follows: JAN FEB MAR APR MAY JUN JUL AUG SEP OCT DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 64 NOV DEC yy is the year b is blank (space) hh is the hour mm is the minutes ss is the seconds RVN(2) : B = Revision number -- the number of times the file has been modified. Network standard time (NST) is one convenient time standard chosen for each network to effect synchronization of remote file access operations and their results. For example, if a user in London creates a file in New York with a deletion time of 2 a.m., does he mean 2 a.m. in London or New York? NST resolves this problem. NST may be local time (e.g. for networks wholly contained in one time zone), GMT or some other agreed on time. 3.16 Protection Attributes Extension Message The Protection Attributes Extension Message is composed of the fields described below. When creating a file, it is used to specify the protection for that file. If not present when creating a new file, the file will be created with the default protection of the accessed node. It may also be used to return a file's protection code to the accessing process on a file open, display of the file's attributes or directory list. The form of the Protection Attributes Extension Message is: PROTECT, PROTMENU, OWNER, PROTSYS, PROTOWN, PROTGRP, PROTWLD where: PROTECT : = The OPERATOR field with TYPE=14. PROTMENU(EX-6) : BM = The following bit map specifies which of the following fields are present in this message. If the field is not present, the default, if any, should be used. These fields and only these fields may appear in the message and they must appear in the order specified. Bit Meaning (When set) 0 OWNER 1 PROTSYS 2 PROTOWN 3 PROTGRD 4 PROTWLD DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 65 OWNER(I-40) : A = The name or user code (e.g., UIC such as 240, 220) of the file owner. When creating a file and the file system allows the owner to be user specified, this field, if present, specifies the owner of the file. If this field is not present, the file owner information is taken from the user identification information which comes with the connect. (Alternatively, if the User Identification Message is being used, see Appendix B, owner information may be taken from there.) PROTSYS(EX-3) : BM = File protection for system access rights. Bit Meaning (When Set) --- ------------------ bit 0 = deny read access. bit 1 = deny write access. bit 2 = deny execute access. bit 3 = deny delete access. bit 4 = deny append access. bit 5 = deny directory list access. bit 6 = deny update access. bit 7 = deny change access protection attribute. bit 8 = deny extend access. PROTOWN(EX-3) : BM = File protection for file owner access rights. Refer to the bit map used for PROTSYS above. PROTGRP(EX-3) : BM = File protection for group access rights. Refer to the bit map used for PROTSYS above. PROTWLD(EX-3) : BM = File protection for general (world) access. Refer to the bit map used for PROTSYS above. 3.17 Name Message The Name Message is composed of two fields as described below. It is used when renaming a file to contain the new name the file will have after the operation is complete. It is also used with the directory listing to return the name of each file for which attributes are returned. It may also be used when opening or creating a file to contain the default or related file specification. The form of the name message is: NAME NAMETYPE NAMESPEC where: NAME: = The operator field with TYPE=15. NAMETYPE(EX-3) : BM = Type of name contained in NAMESPEC field. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 66 Bit Meaning --- ------- 0 File specification 1 File name 2 Directory name 3 Volume or structure name 4 Default file specification (reserved) 5 Related file specification (reserved) NOTE Here the file specification means the full file specification including the volume, directory and file name. NAMESPEC(I-200) : A = The file specification in the format of the remote node. This ASCII field is not interpreted by DAP software. 3.18 Access Control List Attributes Extension Message (Reserved for future use) The Access Control List (ACL) Message specifies a list of users and the access rights they have to this file. Each ACL entry is in the format of the system where the file resides. The list is potentially very long and therefore this message has a facility for specifying if this is the last of a sequence of ACL Messages. The form of the ACL Message is: ACLTYPE,ACLCNT,ACL[,ACL,...] ACLTYPE : = The operator field with TYPE=16. ACLCNT(1) : B = The absolute value of this field is the number of repetitions of the ACL field in this message. If this field contains a negative value, this is the last in a sequence of ACL messages. ACL(I-80) : A = Access control list entry. There is one entry for each user having access to the file. This field is treated as a literal string (not parsed by accessing system) and is in the format of the accessed system. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 67 4.0 FILE ORGANIZATION 4.1 Types of Files The following types of files are addressed by this specification: 1. Sequential - Each record's position depends on the position of the previous record. 2. Relative - Each record in the file has a unique identifying number, its record number. Records may be accessed randomly by specifying their record number in a Control Message. 3. Hashed/Indexed - These files have records organized according to some classification method, usually an access key. Within a particular key for indexed files, the records are assumed to be logically sequential. 4.2 Record Formats and Attributes There are two ways in which ASCII records are stored in DIGITAL file systems: 1. Byte Count. A byte count associated with the record in the file indicates how long the record is and is used to determine record boundaries. 2. Stream. The ASCII record is stored exactly as is. The record is assumed to be terminated with one of the following delimiters: a) (FF) -- Form feed b) (DLE) -- Data link escape c) (DC1) d) (DC2) e) (DC3) f) (DC4) g) (VT) -- Vertical tab h) (LF) -- Line feed i) (ESC) -- Escape j) (^Z) -- Control Z Files using ASCII stream often do not have record attributes stored with the file. DAP supports four ASCII record formats: 1. Fixed length records, DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 68 2. Variable length records, 3. Variable with fixed control, 4. ASCII stream In addition, DAP supports the following attributes: 1. FORTRAN carriage control, 2. COBOL carriage control, 3. Print file carriage control, 4. Implied LF/CR envelope for printing, 5. Embedded carriage control, 6. Line sequential ASCII 7. MACY11 8. None of the above. 4.2.1 Handling stream ASCII -- Stream ASCII files consist of a string of ASCII characters with no explicit record structure imposed upon the data within the file. "Records" in a Stream ASCII file are defined by a set of delimiters (see section 4.2) where each "record" is terminated by one of the delimiters. DAP processes transferring Stream ASCII data "records" perform no transformations upon the "records". All characters in the "records", up to and including the delimiter, are sent as a single record in a DAP Data Message. No characters, including NULL's, are stripped or replaced. Stream ASCII files may have other attributes as well as Stream ASCII, e.g. Fortran carriage control. 4.2.2 Conversions -- It is not a part of DAP to specify data or format conversions which may be necessary when sending data from one type of system to another. It is the responsibility of the user process (accessing process) to make any necessary conversions when transferring data between unlike systems. The accessed process (server) is non-intelligent and does only what it is told. The accessed process will execute a protocol function only if it supports that type of operation or attribute. If an accessed process does not support an operation or attribute, it will return an appropriate Status Message. Thus, if a conversion must be made, e.g. sending a Stream ASCII file to a remote system supporting variable length byte count records but not Stream ASCII, the accessing process (user) must perform the conversion before sending each record of the file. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 69 NOTE While this is not a part of the DAP specification, the following algorithm has been used effectively in several DAP speaking user processes to determine what (if any) conversions must be made when trying to store a file on a remote file system: 1. Open file using file's attributes on local system. 2. If no error on ATTRIBUTES message, send file and terminate, else go to step 3. 3. Send new ATTR/ACC messages using the next most likely attributes to be supported by the remote system. 4. If no error on ATTRIBUTES message, send file and terminate, else go to step 3. This should almost never require more than two repetitions of step 3 as most ASCII files are either Stream or Variable with implied CR/LF. 4.3 Data Formats 4.3.1 Fixed-Length Records - All records are of the fixed length specified in the MRS field. They are delimited by physical message blocks (that is, the last byte in a Data Message is the end of the record). 4.3.2 Variable-Length Records - These records are like the fixed-length records except the record length is variable with the maximum length being specified in the MRS field. 4.3.3 Variable with Fixed-Control Format Records - These records are normal variable-length records with an associated fixed-length field used for control purposes. In DAP Data Messages, this fixed-length control field immediately precedes and is contiguous with the variable DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 70 part of the record. The length of the fixed field is found in the FSZ field in the Attributes Message. MRS contains the maximum length of the variable portion only. FSZ + MRS = total maximum record length. Regardless of the type of the data in the variable portion of the record, the data in the fixed portion is always sent as a binary field contained in an integral number of 8-bit bytes. 4.3.4 ASCII Stream - Here a file contains just a stream of ASCII characters with no real concept of records. However, delimiters are used to terminate "records" for purposes of reading and writing the file. 4.4 Supported Data Types The DATATYPE field of the Attributes Message defines the code representation used to transfer data. These are: ASCII Image EBCDIC (Reserved) In addition, there is a COMPRESSION option mode, which can be used with any of the above. This compressed mode reduces the amount of data sent by encoding blanks and duplicates. 4.4.1 ASCII - This is the 7-bit ASCII code-set as defined in the 1968 ANSI standard. To transmit this within 8-bit frames, the high order bit is ignored except when using 7-bit compression. On card readers, this refers to the ASCII encoding of the punches into the 128 character codes. 4.4.2 EBCDIC - this is an IBM 8-bit EBCDIC code set. (Reserved) 4.4.3 Image - This is a mode for transmitting data in DAP where no code set is specified and data records (or blocks) are simply regarded as ordered strings of bits. The number of bits in a bit string (image mode record) need not necessarily be a multiple of 8 although the bit strings are in fact transmitted in 8-bit frames (a requirement of lower level protocols). When transmitting Image data and the number of data bits in the message is not a multiple of 8 (the number of actual data bits in a DAP Data Message must be a multiple of the byte size as specified by BSZ in the Attributes Message), the field BITCNT in the header of the Data Message must be used. It specifies the number of bits in the DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 71 final 8-bit frame of the Data Message which are not actual data bits (i.e. padding bits required to fill out the 8-bit frame). When transferring bit strings where the bit count is a multiple of 8, it is not necessary to use BITCNT. The order in the bit strings is low order bit of low order byte first, second bit of low byte, etc., followed by the same sequence for successively higher order bytes. For example, consider retrieving the 3 byte record with 6-bit bytes shown below. The order of the string is as shown below with the first bit on the right and the last bit in the string on the left (the top row of single digit numbers inside the boxes is byte numbers and the bottom row is bit numbers. Thus for any bit position in the string, the top digit gives the byte and the bottom digit the bit within that byte). byte 2 byte 1 byte 0 --------------------------------------------- ! 2 2 2 2 2 2 !! 1 1 1 1 1 1 !! 0 0 0 0 0 0 ! ! 5 4 3 2 1 0 !! 5 4 3 2 1 0 !! 5 4 3 2 1 0 ! --------------------------------------------- In image record mode, this string would be transmitted in 3 8-bit frames in a DAP Data Message as follows: frame 2 frame 1 frame 0 ------------------------------------------------------- ! x x x x x x 2 2 ! 2 2 2 2 1 1 1 1 ! 1 1 0 0 0 0 0 0 ! ! 5 4 ! 3 2 1 0 5 4 3 2 ! 1 0 5 4 3 2 1 0 ! ------------------------------------------------------- with frame 0 being transmitted first, low order bit first. The x's are padding. BITCNT would be 6 for this DAP Data Message. If this image record is being sent to a system which stores data in 7-bit bytes, this record would be stored as follows: byte 2 byte 1 byte 0 ------------------------------------------------- ! x x x 2 2 2 2 ! 2 2 1 1 1 1 1 ! 1 0 0 0 0 0 0 ! ! 5 4 3 2 ! 1 0 5 4 3 2 1 ! 0 5 4 3 2 1 0 ! ------------------------------------------------- 4.4.4 Compression - any of the encodings, even the IMAGE mode, may be compressed on transmission to eliminate the sending of duplicates and multiple blanks. The compression technique is slightly different with 7-bit and 8-bit character encodings. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 72 7-bit compression: 1. Non-compressed characters are sent with high order bit = 0 and low 7-bits = character: (0) (7-bit char). 2. Blanks are sent as high bits = 10 followed by number of blanks in 6-bit binary: (10) (number blanks). 3. Repetitions are sent as high bits = 110 followed by number of repetitions in 5-bit binary: (110) (number reps) followed by the repeated character. 4. An escape scheme allows sending of 12-bit card images when they do not encode into the ASCII code set by sending high bits = 1111 followed by columns 12-1 and another character of columns 2-9, i.e., (1111) (12,11,0,1) in the first character and (2,3,4,5,6,7,8,9) in the second character. 5. The high bit sequence 1110 has been reserved for future expansion. 6. In the case of repetitions the repeated "character" may be a 12-bit image which is sent as 2-characters. 7. Summary 7-bit compression: 0xxxxxxx 7-bit non-compressed characters 10xxxxxx number of blanks (the character octal 40) 110xxxxx number of repeated characters 1111xxxx 12-bit card image xxxxxxxx 12-bit card image (continued) 1110xxxx reserved 8-bit compression: With 8-bit codes the blanks, repetitions and 12-bit card image are the same as the 7-bit case. 8-bit non-compressed strings are preceded by a count of the string length with high bit = 0 followed by 7-bit count: (0) (count). This is followed by "count" 8-bit characters. Following this may be another string, blanks or repetitions. Summary: 0xxxxxxx number of non-compressed characters 10xxxxxx number of nulls (all zero bytes) 110xxxxx number of repetitions 1110xxxx reserved 1111xxxx 12-bit card image xxxxxxxx 12-bit card image (continued) The receiver of compressed data must be able to expand it according to the rules just given. Data compression should not be used unless the Configuration Messages from both systems indicate they both support file compression (bit 15). The use of file compression is indicated by the compressed format bit of the DATATYPE field in the Attributes DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 73 Message. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 74 5.0 OPERATION The Data Access Protocol (DAP) is a user level protocol that resides within the Application Layer of the DIGITAL Network Architecture (DNA). Its purpose is to transfer data to and from I/O devices and mass storage files independent of the I/O structure of the system being accessed. This transfer is accomplished by communication with a DAP process that accepts DAP requests on the network side and translates them into equivalent requests to the local I/O system. From the network it appears as if DECnet systems support DAP messages directly within their file systems. DAP provides the mechanism for setting up the conversation path for remote file access, transferring data over the link, and terminating the logical link. 5.1 Setting up the Link Processes that implement the DAP protocol operate at the application level within a DECnet system. They use the lower level interprocess communication facilities of the network for the creation and flow control of the data path (logical link) between the processes exchanging messages within the DAP environment. Once the link is established, the processes may exchange DAP messages over the link. A separate logical link is used for each remote file access in progress. This means a single user cannot access more than one file at a time over a single logical link. It also means that several users cannot access the same file over a single logical link. However, a single logical link can be used to access more than one file provided access to the files is sequential and does not overlap. Access control information (i.e., user identification, password, and account identification,) is passed from the accessing (user) DAP process to the accessed (server) DAP process by a lower level interprocess communication protocol. Following link establishment, the DAP-speaking processes exchange Configuration Messages. The purpose of this exchange is: 1. To establish the maximum buffer size for exchanging lower level protocol messages. 2. To identify system type to each other; 3. To enable one DAP process to know which version of the protocol the other DAP process speaks; and 4. To inform the opposite process of the generic capabilities of the system sending the message. The system type is used when it is necessary to know the type of both the operating system and the file system on the other end of the link. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 75 This is helpful, for example, when deciding if block mode file transfer can be used when transferring files between like systems or if multiple data streams can be initiated as is possible between RMS-based systems. The capabilities field of the Configuration Message indicates to each of the DAP processes the generic capabilities of the other DAP process with which it is communicating. It is used to determine the type of file support offered by a remote system without resorting to trial and error techniques. The node where the file or device resides is the accessed node while the node where the user process is located is the accessing node. The accessing process is the one that initiates the connection. For each DAP message sent over the link, a transmit request and corresponding receive request must be issued to NSP. This discussion is concerned with the DAP messages only and assumes that the necessary receives and transmits are issued by the processes involved. After link creation and the exchange of Configuration Messages, the accessing process sends an Attributes Message, optionally followed by one or more Extended Attributes Messages, specifying the mode and format of the data and the structure of the file. This is then followed by an Access Message specifying the desired operation. The Access Message may optionally be preceded by a Name Message if the default filename option is required. The Attributes, Extended Attributes, Name and Access Messages may be blocked and sent together in one transmission if buffer space is available (the LENGTH field must be used) and blocking is supported as indicated by the Configuration Message. Alternately, if a DAP message is too long to be sent as a single entity due to limitations of the underlying transport mechanism, the DAP message may be segmented and sent in two or more pieces (see FLAGS field in message header) if segmentation is supported. Systems not retaining the file attributes use the Attributes Message to set the attributes for the transfer. When creating a new file, the Attributes Message sent by the accessing process specifies the attributes the new file should have. If the accessed system does not support these attributes, it returns a Status Message to that effect. When storing records with systems retaining attributes, the accessing system uses the Attributes Message returned by the accessed system to indicate the attributes the records being sent should have. For record retrieval with systems retaining attributes, records are transferred with the attributes of the Attributes Messages returned by the accessed process. After the initial set up messages are sent, the accessing system receives a response from the accessed process. If the access specified opens a file, an Attributes Message and Extended Attributes Messages followed by an Acknowledge Message is sent from the accessed system containing the actual attributes of the accessed file. If the operation specified in the Access Message deletes, renames or executes a file, no Attributes Messages or Acknowledge Message are returned and the response is an Access Complete Message. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 76 To minimize the tying up of network resources (e.g., logical links and buffers), the Configuration, Attributes, Extended Attributes, Name and Access Messages should be sent in a "timely" manner. A timer may be set for each message and if it does not arrive in a reasonable time the link may be disconnected by the accessed process. After the Acknowledge Message has been received, the file is open and the accessing process sets the pace for access of the file. If there are errors in the setup procedure, a Status Message will be returned. NOTE A receive must always be outstanding in order to accept both expected and unexpected DAP Status Messages. Status Messages are always sent as ordinary (not Interrupt) messages. If an error is detected in a Status Message, either during or after setup, a protocol error has occurred and there is nothing that can be done to recover so the link should be disconnected. Errors in exchanging Configuration Messages should be very rare since the information in Configuration Messages will generally be "canned" and of an informative nature. If the accessed system detects an error in the Configuration Message, it returns a Status Message and the accessing system can either retry or disconnect. If the accessing system detects an error, it disconnects. NOTE If, however, a Configuration Message appears to be in error because the SYSCAP field is too long and the DAP version number is greater than that to which the current software is written, it should be assumed that the SYSCAP field has been extended in the later version of DAP. This error should be ignored. This is the only time when an error is ignored. The assumption is that the more sophisticated DAP process will use only a subset of the protocol and thus both sets of software will be able to work together. 5.1.1 Errors in the Setup Sequence - Errors detected by the accessed DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 77 process in the Configuration Message, Attributes Messages, Name Messages and Access Message all return a Status Message. On receiving an error in response to one of these messages, there are three possibilities open to the accessing DAP process: 1. Disconnect the link. 2. Send the corrected message responsible for the error. There is no point in sending the original message unless there is sufficient doubt that the message was delivered properly or that the error indicated was of a temporary nature (e.g., an attempt to open a file already open by another process). 3. Start a different access. A new access will usually start with an Attributes Message, but it could start with an Access Message (where the type of access does not require attributes such as ERASE) or even a Configuration Message. If the user process tries to recover by sending a corrected message or starting a new access, the accessed DAP process should be capable of accepting any of the setup messages in response to a Status Message. Table 5-1 provides a list of responses to setup message errors. For purposes of this table, Extended Attributes Messages are considered as being Attributes Messages and Name Messages part of the Access Message. When recovering from an error in an Attributes Extension message, the accessing process should back up to the Attributes Message. Table 5-1. Responses to Setup Message Errors Responses !Configuration!Attributes! Access ! Error ! Message ! Message !Message ! ---------------------------------------------------------------- Configuration Message ! 1 ! 0 ! 0 ! ---------------------------------------------------------------- Attributes Message ! 1 ! 1 ! 2 ! ---------------------------------------------------------------- Access Message ! 1 ! 1 ! 1 ! ---------------------------------------------------------------- where: 0 = invalid response. 1 = valid response. 2 = valid response only for accesses requiring no attributes message. Errors detected by the accessing process in Attributes, Extended Attributes, Name and Acknowledge Messages cause the accessing process to disconnect the logical link thus terminating the access. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 78 5.1.2 Setup Sequence - If a timer is used between setup messages, this same timer should be set by the accessed process after an error during setup. If the timer expires, a disconnect should be initiated. NOTE In the DAP message sequence diagrams in this section, [] are used to denote optional messages. The message sequence diagrams in this and subsequent subsections are not totally definitive as they do not cover every situation which can arise with DAP remote file access. However, they should be complete enough to give a feeling for what should be done in those situatuions not explicitly addressed. After a logical link is established, the setup sequence is as follows: Accessing Process Accessed Process 1. Configuration information exchange: CONFIGURATION<------>CONFIGURATION NOTE Both accessing and accessed processes can send Configuration Messages immediately on link establishment. The accessing process must send its Configuration Message immediately. 2. Setup for access: ATTRIBUTES------> [EXTENDED ATTRIBUTES]----> [NAME-----------> (DEFAULT)] ACCESS----------> <------ATTRIBUTES DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 79 [EXTENDED <------ATTRIBUTES] <------[NAME (EXPANDED FILESPEC)] <------ACKNOWLEDGE NOTES 1. An Attributes Message is not required when the Access Message specifies ERASE, RENAME, DIRECTORY LIST or EXECUTE command file. For these types of access, neither the Attributes Message nor the Acknowledge Message is returned by the accessed process unless specifically requested by the DISPLAY field. If the DISPLAY field is omitted from the Access Message and the function is OPEN, CREATE or SUBMIT, the accessed process always returns a Main Attributes Message. When a DISPLAY field is present in an Access Message, the accessed process will return only the messages requested by the DISPLAY field. When RENAME is specified, the Access Message is followed by a Name Message containing the new name for the file (see Section 5.2.8). 2. The optional Name Message returned by the accessed process after opening the file is requested by a bit setting in the DISPLAY field of the Access Message. It contains the file specification of the file opened or created after all the logical names have been resolved and defaults applied. 3. Error in Configuration Messages: a) Disconnect after error detected: CONFIGURATION------>(error detected) <------STATUS DISCONNECT or DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 80 (b) Correcting erroneous message: CONFIGURATION------>(error detected) <------STATUS CONFIGURATION------> or (c) If the error is in the returned message: CONFIGURATION------> (in error) <------CONFIGURATION DISCONNECT 4. Error in Attributes Message: (a) Disconnect after erroneous message ATTRIBUTES------>(error detected) <------STATUS DISCONNECT or (b) Correcting erroneous message ATTRIBUTES------>(error detected) <------STATUS ATTRIBUTES------> or (c) Starting a new remote file access on the same link -- note the new access shown is of a type not requiring the Attributes Message (see Note 1, section 5.1.2), e.g. ERASE, as no valid attributes are currently in effect. It could equally well have been an access requiring a new Attributes Message. ATTRIBUTES------>(error detected) <------STATUS ACCESS ------> 5. Error in Optional Extended Attributes Message: DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 81 (a) Disconnect after erroneous message ATTRIBUTES------> EXTENDED ATTRIBUTES 1-----> . . . . . . EXTENDED ATTRIBUTES n----->(error detected) <------STATUS DISCONNECT or (b) Correcting erroneous message -- note that restart backs up to the Attributes Message. ATTRIBUTES------> EXTENDED ATTRIBUTES 1-----> . . . . . . EXTENDED ATTRIBUTES n----->(error detected) <------STATUS ATTRIBUTES-----> EXTENDED ATTRIBUTES 1-----> . . . EXTENDED ATTRIBUTES n-----> . . . etc. (c) Starting new access on same link: ATTRIBUTES--------> EXTENDED DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 82 ATTRIBUTES 1------> . . . EXTENDED ATTRIBUTES n------>(error detected) <------STATUS ACCESS ------> 6. Error in Name Message for Default File Specification: (a) Disconnect after erroneous message: NAME ------> (error detected) <------STATUS DISCONNECT (b) Correcting erroneous message: NAME ------>(error detected) <------STATUS NAME ------> (c) Starting new access on same link: NAME ------>(error detected) <------STATUS ATTRIBUTES ------> [NAME ------>] ACCESS ------> 7. Error in Access message: (a) Disconnect after erroneous message: ATTRIBUTES------> ACCESS ------>(error detected) <------STATUS DISCONNECT------> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 83 or (b) Correcting erroneous message: ATTRIBUTES------> ACCESS ------>(error detected) <------STATUS ACCESS ------> or (c) Starting new access on same link with new Attributes and Access Messages: ATTRIBUTES------> ACCESS ------>(error detected) <------STATUS ATTRIBUTES------> ACCESS ------> Figure 5-1. Set-up Sequence 5.2 Transferring Data over the Link The message exchange sequence for transferring data over the link depends on the direction of data flow with respect to the accessing and accessed systems. Data may be sent to the accessing node as in a retrieve operation or from it as in a store operation. Before data transfer can start, however, a data stream must be initiated by sending a Control Message ($CONNECT) after the file is open. With file systems that support multiple data streams, additional data streams can be initiated with more Control Messages. Multiple data streams are differentiated by using the STREAMID number. Data Messages for a particular data stream must have the same STREAMID number as the Control Message that initiated the data stream. If the STREAMID number is omitted, a default of 0 is used. The sequence for initiating a data stream is as follows: Accessing Process Accessed Process CONTROL(CONNECT)----> <----ACKNOWLEDGE DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 84 If an error occurs, a Status Message will be returned instead of an ACK. A new data stream can be initiated any time the file is open by using the above message sequence. NOTE Multiple data streams cannot be used if file transfer mode is specified in the RAC field of the Control Message. The file transfer mode implies a single data stream with only data (no control messages) flowing over the link. By eliminating Control Messages, efficiency is gained. There are three classes of Status Message which can be sent by the accessed process during data transfer: 1. Successful -- when transferring data in record mode (not file transfer mode), a successful Status Message is returned by the accessed process after successful completion of the requested operation. The successful Status Messages provide synchronization for the DAP processes as well as returning status and other information to the user. When transferring data in file transfer mode, data messages are pipelined and successful Status Messages omitted in order to improve efficiency. 2. Warning -- this class of Status Message is sent to the accessing process when an operation completes but not with complete success, e.g. a record was inserted in an indexed file but it had a duplicate key. Warning Status Messages are always sent to the accessing process (provided the Configuration Message states the accessing process supports them). After sending a warning Status Message, the accessed process suspends processing on that that data stream until it receives a Continue Transfer Message (or the next Control Message for Record Retrieval) instructing it to resume processing or an Access Complete Message terminating the access. On receivinga warning Status Message, the accessing process either sends a Continue Transfer (Resume) to continue data transfer, a Control Message or an Access Complete if it wants to terminate the access. 3. Error -- this class of Status Message is sent when an operation was unable to complete at all, e.g. a read error. When an event in this class occurs, a Status Message is always sent to the accessing process. After sending the Status Message, the accessed process suspends processing on that data stream until it receives a Continue Transfer DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 85 Message telling it what to do or an Access Complete Message terminating the access. On receiving an error Status Message, the accessing process either sends an Access Complete to terminate the access or a Continue Transfer if it wants to attempt recovery. These three classes of Status Message are differentiated by the MACCODE field of the Status Message (see section 3.11 and table 3-1). Status codes returned by the file system will often assist in deterBmining which class of Status Message (if any) should be sent on the completion of each operation. However, ultimate responsibility for the classification and mapping of file system status codes into DAP Status Messages resides with the implementers of DAP Server (accessed) processes. Examples of the handling of both warning and error Status Messages are shown in the following subsections. 5.2.1 Sequential File Retrieval - For sequential file retrieval, data records are sent from the accessed system. Once the initial startup sequence is completed and the data stream initiated, a single Control Message (GET) is sent to start data records flowing. Thereafter, the file records are transmitted without waiting for any further DAP messages to control sending messages. All flow control is performed implicitly by the lower level protocols. To specify sequential file retrieval, the accessing process specifies sequential file access (or virtual block number file transfer) in the Control (GET) Message. The accessed process will then send file records (or blocks) without waiting for any further DAP Control Messages. In contrast to sequential file retrieval, if sequential record access is specified, the accessing process must send a Control Message for each record retrieved. Data messages will continue to arrive until: a) the end-of-file is reached on the accessed system; b) an error occurs in accessing the file; or c) the accessing system decides it has completed its access. In the first case, the last record sent in a data message is followed by a Status Message with end-of-file detected set. In the second case, a Status Message is sent when an error occurs in accessing the original file. If the accessing system receives a Status Message with end-of-file, it sends an Access Complete Command (ACCOMP) and waits for an Access Complete (Response). It then either disconnects or initiates another access by sending a setup sequence. If the accessing process receives a Status Message with either an error or warning, it may either send an Access Complete Command and wait for an Access Complete Response or try to recover with a Continue Transfer. If the accessing system decides to terminate access prior to end-of-file, it sends an Access Complete (Close) and waits for an DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 86 Access Complete (Response) in return. In such cases, an accessing system issuing an Access Complete (Close) may still receive one or more records for the file, an end-of-file indication or even a Status Message due to the pipelining delay in the system. It should pass over these records until an Access Complete Response is received. It may then disconnect or access another file. Accessing Process Accessed Process 1. Retrieval until End-of-File (EOF): CONTROL (GET)------> <------ RECORD 1 . . . <------ RECORD n NOTE Transfer continues until End-of-File or error <------STATUS (End-of-File) ACCOMP (CLOSE)------> <------ACCOMP (RESPONSE) The accessing process may now issue another access or disconnect the link. 2. Retrieval until error or warning status: Accessing Process Accessed Process <------RECORD n <------STATUS NOTE The STATUS Message occurs while trying to read record n+1. When an error is received, the accessing process can do one of the following: (a) Request link termination. ACCOMP (CLOSE)--------> <------ACCOMP (RESPONSE) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 87 or (b) Request the information be sent again CONTINUE (TRY AGAIN)------> <------RECORD n+1 or (c) Skip that record and continue CONTINUE (SKIP)------> <------RECORD n+2 or (d) When a warning is received, the accessing process can request link termination as in (a) above or resume processing by sending a resume CONTINUE(RESUME)-----> <------RECORD n+1 3. Retrieval with access termination: <----RECORD m ACCOMP (CLOSE)----> <----ACCOMP (RESPONSE) The accessed process may set a timer following sending ACCOMP (Response) and if neither a Disconnect or another message is received within the time interval, it may disconnect the link. 4. Retrieval with checksum error on close: <----RECORD n <----STATUS (EOF) ACCOMP(CLOSE)----> <----STATUS(checksum error) ACCOMP(CLOSE)----> <----ACCOMP(RESPONSE) Do not send a ACCOMP (Purge) to the accessed process as it will purge the input file. Sending the ACCOMP Message with the CHECK Field causes the checksums to be compared. If the CHECK field is omitted, checking is by-passed. See section 5.5.2. Figure 5-2. File Retrieval Sequence DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 88 5.2.2 Sequential File Storage/Append - In the store case, data is sent to the accessed system. Following the initialization of the data stream, the accessing system sends a Control Message (PUT) to tell the accessed process what to do. The Control Message is followed by file records using the Data Message. These messages will be accepted by the accessed system and will continue until the accessing system sends an Access Complete (Close). This will cause a corresponding Access Complete (Response) to be returned following successful file closure, or a Status Message to be sent if an error occurs in closing the file or a checksum failure is detected. For other than a checksum failure, the access is concluded and another access may start or the link may be disconnected. If a checksum failure is detected, another Access Complete (without the CHECK field) is sent, either close or purge, to terminate the access the way the user desires. To specify sequential file storage, the accessing process specifies sequential file access in the Control Message together with PUT. To specify sequential file append, the operations are the same except "position to EOF" is specified in the Control Message in addition to PUT and sequential file access. As with sequential file retrieval, sequential file storage implies the use of only one data stream and no Control Messages after the initial Control (PUT) Message. The optional (in brackets) ACCOMP (End-of-stream) message shown in (1) below serves to flush the pipeline before closing the file. This re-synchronizes the accessing and accessed processes thus making error handling easier for the case where an error occurs in writing the final records to the file when the user issues a close command (after the error is returned to the user, this gives him the option of purging the file as the ACCOMP (Close) is not yet in the pipe). If an error occurs during record transfer, the accessed system returns a Status Message. This must always be replied to with a Continue Message sent as an Interrupt Message (because of possible pipelining). In addition, to terminate the access, an Access Complete Message should be sent. Accessing Process Accessed Process 1. Store with no errors: CONTROL (PUT) ------> RECORD 1 ------> NOTE . Transfer continues . until access is . complete or error . RECORD n ------> [ACCOMP (EOS) ------>] [<------ ACCOMP (RESPONSE)] ACCOMP (CLOSE) ------> <------ACCOMP (RESPONSE) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 89 2. Error during transfer: (a) Purge the new file and terminate: RECORD n ------> <------STATUS CONTINUE (ABORT) ------>(INTERRUPT) ACCOMP (PURGE) ------> NOTE On receiving the Continue Transfer interrupt message, the accessed system discards records until ACCOMP (PURGE) is received. It then purges the incomplete output file and returns an ACCOMP. Transmission order of the Continue Transfer (interrupt message) and the ACCOMP (normal message) is not important for DAP as they are sent on separate subchannels (a logical link can be regarded as having two subchannels, one for ordinary messages and one for interrupt messages). However, if the send function is a SEND with WAIT, the interrupt message should be sent first as the SEND for the ACCOMP will not complete until the accessed process receives the interrupt message. <------ACCOMP (RESPONSE) or (b) Close the new file and terminate: ACCOMP (CLOSE) ------> CONTINUE (ABORT) ------>(INTERRUPT) NOTE The accessed system discards records until the ACCOMP (CLOSE) is received and then closes the incomplete output file. <------ACCOMP (RESPONSE) or (c) Retry - the accessed system still has the record which DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 90 caused the error in its buffer: CONTINUE (TRY AGAIN)------>(INTERRUPT) RECORD n+1 ------> or (d) Skip the record and continue: CONTINUE (SKIP)------>(INTERRUPT) RECORD n+1 ------> NOTE On an error, the accessed process does not issue any more receives after sending the Status Message and before receiving the Continue Message, which tells it what to do. If the accessing process responds to the error by sending an interrupt Continue Transfer (Retry) Message and the retry is successful, the accessed process will post a receive and carry on with the data transfer. If the retry fails, another Status Message is sent. A Continue Message with skip always posts a receive and tries to carry on having skipped the record which caused the original error. For file transfer store and append, Continue Messages must be sent in interrupt mode as there may be data in the pipeline. 3. Warning during transfer: (a) Resume after receiving warning status: RECORD n ------> <------STATUS (WARNING) CONTINUE(RESUME) ------> (INTERRUPT) RECORD n+1 ------> or (b) To terminate the access after a warning, follow sequence 2(a) above to purge the output file or 2(b) to keep the output file. NOTE After sending the warning Status Message, the accessed process issures no more receives until it receives an interrupt Continue Transfer DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 91 Message instructing it what to do. 4. If the accessing system wants to stop a sequential file storage operation before it is complete and purge the incomplete file on the accessed system, the sequence is as follows: Accessing Process Accessed Process RECORD n---------------> ACCOMP (PURGE) -------> Purge the incomplete file <----ACCOMP (RESPONSE) To save an incomplete file on the accessed system, the operations are as in Step 1. 5. Checksum error on close: Record N----> ACCOMP (CLOSE)----> <----STATUS (Checksum error) ACCOMP(CLOSE/PURGE)----> <----ACCOMP(RESPONSE) The user can either keep or purge the erroneous output file by sending either a close or purge Access Complete Message without the CHECK field. Figure 5-3 Sequential File Storage 5.2.3 Record Retrieval - Record retrieval requires a Control Message (with a record key for random retrieval) be sent by the accessing process for each record accessed. Record retrieval is specified by the accessing process setting sequential record access, Keyed access or Record File Address (RFA) access in the Control Message. Block mode transfer is similar to record retrieval and is specified by setting Virtual Block Number (VBN) access. For keyed, VBN or RFA access, the sequence is as follows: CONTROL (get record with Key n)----> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 92 <---- RECORD n, STATUS CONTROL (get record with Key m)----> <---- RECORD m, STATUS For sequential record access, the state operation is as follows: CONTROL (get sequential)---------> <---- RECORD k, STATUS CONTROL (get sequential)--------> <---- RECORD k+1, STATUS Once the location of a particular record in a file is found using random access, the user frequently wants to get subsequent records sequentially. This can be done by switching the access mode from keyed or RFA to sequential in the Control Message and issuing a Get. (With RMS systems, the user is free to switch access modes according to the RMS rules.) CONTROL (get record with Key r)----> <---- RECORD r, STATUS CONTROL (get sequential) --------> <---- RECORD r+1, STATUS Once a particular record in a file is found, it is possible to transfer the remainder of the file in sequential file access mode. CONTROL (get record with key t)----> <---- RECORD t, STATUS CONTROL (sequential file access, get)-----> <---- RECORD t+1, STATUS <---- RECORD t+2, STATUS . . . to end-of-file Error handling for sequential record retrieval is similar to error handling for sequential file retrieval. The handling of warnings is easier, however. In order to continue processing, the accessing process sends a Control (GET) -- a Contine Transfer (RESUME) is not necessary (but should be ignored if received). Error handling for random record retrieval is similar to that for sequential file retrieval. However, the continue (skip) recovery option which is valid for sequential retrieval is not valid for random retrieval. When a control request specifies a nonexistent record while doing random record retrieval, the accessed process will return an appropriate error message (e.g., record number out of range or record not found). DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 93 5.2.4 Record Store - This is similar to sequential file store in messages exchanged. The access message specifies whether to open an existing file or create and open a new file. PUT access must be specified in the Control Message. For record storage, the accessing process may specify sequential record access, or keyed access. Optionally, VBN access may also be used. For relative files, the data messages must include the relative record number field specifying the number of the record (RECNUM). For hashed files where the user is supplying his own hash code (RB$HSH set in the ROP field of a Control Message), RECNUM contains the hash code. In all other cases, the contents of RECNUM are ignored and will probably be set null to minimize data transmission overhead. For sequential files, records are written starting at the current position within the file. The sequence of records to be stored may be preceded by a Control (PUT) Message if it is necessary to change record options or access mode from the current value. Optionally, each record to be stored may be preceded by a Control (Put) Message. This is inefficient, however, since it doubles the number of DAP messages transmitted. When storing a record, if the Data Message is preceded by a Control Message that contains a record number in the KEY field and the Data Message also contains a record number in the RECNUM Field, then the record number in the RECNUM Field will be used. The sequence for record storage with return of status is as follows: RECORD n --------> <-------- STATUS RECORD n+1 ------> <-------- STATUS Errors are handled as indicated in Section 5.2.2. Note that a warning Status Message requires an interrupt Continue Transfer (Resume) (or Abort) to restart processing (as in section 5.2.2) because of possible pipelining problems. Continue skip causes the accessed process to ignore the record which caused the error and go on to process the next DAP message. 5.2.5 Append to Existing File - The append operation is identical to sequential store and applies only to sequential files. The records are placed at the logical end of the file by the accessed system (position to EOF is set in the Control Message): RECORD 1 -------> <------- STATUS RECORD 2 -------> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 94 <------- STATUS 5.2.6 Deleting a File - The delete operation (ERASE) does not cause any file data to be transferred, but does manipulate file structures. Deleting a file does not require an Attributes Message in the setup sequence. The message sequence for the delete operation is as follows: [ATTRIBUTES---------->] [NAME(DEFAULT)]------> ACCESS (ERASE) -----> <-----ACCOMP (RESPONSE) or <-----STATUS 5.2.7 Command/Batch Execution Files - The Data Access Protocol includes commands for the transfer and submission of files to a batch processing facility or command interpreter. The "submit as command file" request in the Access Message requests that the data that follows be stored in a temporary file and that this file be submitted to a batch-type facility upon access completion (closing of the file). The file will be deleted following execution by the batch facility. DAP does nothing with regard to any feedback from the batch facility and does not guarantee that the file actually executes in the batch monitor. The file is transferred using sequential file storage, see section 5.2.2. The "execute-as-command-file" requests that the specified file be only submitted to the batch facility. No data follows this command (the specified file having been previously established on the accessed system). The file is not deleted following execution by the batch facility, so that the sequence "store, and execute command file" will transfer a file, submit it and retain the file for later use. The message sequence for "submit-as-command-file" is identical to "store", while the "execute command file" is identical to ERASE. NOTE Since errors are not returned to the originating node automatically, a test for errors might be included in indirect command files. Upon error or completion, a suitable message can be returned to the originating node. 5.2.8 Renaming a File DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 95 The rename operation does not cause any file data to be transferred, but does require the transmission of two file specifications. The old name of the file is in the Access Message; the new name for the file is in the Name Message following the Access Message. Rename does not require an Attributes Message in the set up sequence. The message sequence for the rename operation is as follows: [ATTRIBUTES]---------> [NAME(DEFAULT)]------> ACCESS(RENAME)------> [NAME(DEFAULT)]------> NAME(FILESPEC)------> <----------ACCOMP(RESPONSE) or <----------STATUS 5.2.9 Extending Files A file may be extended by specifying pre-allocation when the file is opened and then using any automatic extension facility provided by the particular file system as needed. A file may also be extended using the explicit $EXTEND code of the Control Message where a file system supports user directed extension. User directed file extension can generally be initiated at any time after the file is open. The DAP state operations are: Accessing Process Accessed Process data traffic on link . . . ALLOC 1 ------> . . . . . . ALLOC n ------> CONTROL(EXTEND)------> <-------ALLOC 1 . . . . DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 96 . . <-------ALLOC n <-------STATUS . . . continue data traffic on link The CONTROL (Extend) is preceded by one or more ALLOC (Allocation Attributes Extension) messages specifying the type of extension desired. A corresponding number of ALLOC messages are returned specifying the extensions performed. A Status Message is returned terminating the string of returned ALLOC Messages. If an error occurs, a Status Message will be returned. 5.2.10 Display Attributes This command, where available, provides a means of obtaining attribute information about a file. It is included specifically for use with RMS file systems. If this command is used, the accessing node must specify which groups of attributes it wants. It does this by setting the appropriate bits in the DISPLAY field of the Control Message sent to the remote node. In the case of the allocation and key definition groups of attributes, the appropriate Key Definition and Allocation Extended Attributes Messages precede the Control Message to indicate for which Keys of reference or which areas attributes are required. The state operations for display are: Accessing Process Accessed Process [ATTRIBUTES EXTENSION-------------> MESSAGES] CONTROL(Display)------> <---------[ATTRIBUTES and ATTRIBUTES EXTENSION MESSAGES AS REQUIRED] <--------- STATUS 5.2.11 Directory List A directory or multiple directory listing request causes the accessed process to return the file attributes of the files specified in the FILESPEC field of the Access Message requesting the directory list. Attributes are returned by the accessed process using the Attributes and Attributes Extension Messages. The accessing process can specify which Attributes Messages it wants by setting the appropriate bit(s) in the DISPLAY field of the Access message. If the DISPLAY field DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 97 requests the Name Message (bit 8), this causes the resultant file name to be returned with the Attributes Messages in a Name Message. This resultant file name Name Message is in addition to the Name Messages shown in the state operations below. The file specification in the Access Message may contain such "wild cards" as are recognized by the accessed process. As can be seen from the state operations for directory list below, each group of Attributes Messages is preceded by a Name Message for the file the Attributes Messages describe. If no bits in the DISPLAY field of the requesting Access Message are set, only the Name Messages are sent (no Attributes Messages). All the files in a given directory are preceded by a Name Message for the directory. Optionally, if all the directories for which a listing is requested do not reside on the same volume-set (or structure), the directories for each volume-set are preceded by a Name Message indicating which volume-set the following directories are on. The state operations for directory listing are: Accessing Process Accessed Process ACCESS(DIRECTORY)------------> [<----------NAME (VOLUME-SET)] <----------NAME (DIRECTORY) <----------NAME (FILE) [<----------ATTRIBUTES] [<----------ATTRIBUTES EXTENSION] . . . [<----------ATTRIBUTES EXTENSION] <-----------NAME (FILE) [<----------ATTRIBUTES] [<----------ATTRIBUTES EXTENSION] . . . [<----------ATTRIBUTES EXTENSION] . . . <-----------NAME (FILE) [<----------ATTRIBUTES] DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 98 [<----------ATTRIBUTES EXTENSION] . . . [<----------ATTRIBUTES EXTENSION] <-----------NAME (DIRECTORY) . . . <-----------ACCOMP (RESPONSE) The accessing process may terminate a directory listing at anytime by sending a ACCOMP(Close). This will cause the accessed process to send no more Name or Attributes Messages, finish its operation (e.g. close any files it may have open) and finally return an ACCOMP(Response). Note that due to pipelining, the accessing process may receive several Attributes and/or Name messages before receiving an ACCOMP(Response) after it sends an ACCOMP(Close). Errors occurring during a directory listing are associated with trying to obtain information to generate either a Name Message or an Attributes or Attributes Extension Message, i.e. when reading a directory or the attributes of a file. On a gross level, errors will be either read errors, access protection violations, or non-existent attributes (for some reason, the attributes for a file can not be found or do not exist). Read errors are handled by using the Continue Transfer (Try again or Skip) or Access Complete (Close). Protection violations and non-existent attributes errors are handled using the Continue Transfer (Skip) or Access Complete (Close) (Continue Transfer (Try again) will usually just return the same error). Access Complete (Close) will always terminate the directory listing, close any open files and leave the link in a state where another DAP access may be started. Continue Transfer (Try again) will repeat the operation which failed. Continue Transfer (Skip) will cause the accessed process to skip over the operation causing the error and attempt to recover the listing having lost some information, e.g. it will try to read subsequent blocks in the directory trying to get the next file name or it may attempt to read the next block containing attributes for the current file. In some cases, it may not be possible to recover using Continue Transfer (Skip). The following are examples showing error handling for directory listing: Accessing Process Accessed Process 1. Using ACCOMP(Close) to terminate listing: . . . <---------- NAME(File) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 99 <---------- ATTRIBUTES <---------- STATUS ACCOMP(Close) ----------> <---------- ACCOMP(Response) 2. Using CONTR(Skip) to skip over error (some information will always be lost and in some cases it may not be possible to recover): a) Error on reading file name: . . . <---------- NAME (File) <---------- ATTRIBUTES <---------- STATUS CONTR(Skip) ----------> <---------- NAME(of next file) . . . b) Protection violation on reading file attributes . . . <---------- NAME(File) <---------- STATUS CONTR(Skip) ----------> <---------- NAME(of next file) . . . c) Unable to recover after error: . . . <---------- NAME(File) <---------- ATTRIBUTES <---------- STATUS CONTR(Skip) ----------> <---------- STATUS (can not recover) ACCOMP(Close) ----------> <---------- ACCOMP(Response) 5.2.12 Rewind Data Stream DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 100 $REWIND sets the current context of the stream identified by the STREAMID field of the Control Message to beginning of file (BOF). The state operations for rewind are: . . . CONTROL(REWIND)------> <------ STATUS . . . 5.2.13 Truncate File $TRUNCATE truncates sequential files and is not a valid operation on other file types. It causes all records from the current record on to be deleted and EOF to be declared where the current record used to be. . . . CONTROL(TRUNCATE)------> <------ STATUS . . . 5.2.14 Free Buckets $FREE unlocks all locked records in the stream identified by the STREAMID field of the Control Message. . . . CONTROL(FREE)------> <------ STATUS . . DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 101 . 5.2.15 Space Forward or Backward $SPACE forward or backward spaces the file the number of blocks specified in the KEY field. . . . CONTROL (Forward/Backward)------> <------STATUS . . . The RECNUM field of the Status Message contains the number of blocks actually spaced. This may not be the same as the number of blocks specified in the Control Message. For example, if the current position is VBN 7, a backspace of 10 will not actually backspace beyond the beginning of file. 5.2.16 Flush I/O Buffers $FLUSH writes out all modified I/O buffers associated with the record access stream identified by the STREAMID of the Control Message. . . . CONTROL(FLUSH)------> <------ STATUS . . . 5.2.17 Next Volume $NXTVOL performs end-of-volume and start-of-volume processing. . . . CONTROL(NXTVOL)------> <------ STATUS DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 102 . . . 5.2.18 Recovery with DAP File Transfer (Reserved for Future Use) DAP file transfer recovery is an optional feature which can be used to enable a file transfer to be restarted from a convenient checkpoint in the event of either (1) a network failure, or (2) a failure or crash at either the accessing or accessed node. Since it recovers from checkpoints, it is probably most useful when transferring medium to large sized files. There would be little point in using recovery with small files as it is just as economical to repeat the whole transfer as to use recovery, which does entail a certain amount of overhead and risk. For purposes of recovery, information on the disk is considered safe. A file is said to be checkpointed when sufficient information is on the disk that the system can crash and be re-started and when the data written to the file up to the time of the checkpoint is accessible. For example, with many file systems, this could be accomplished by closing and then re-opening the file. Only output files are checkpointed. After a checkpoint (e.g., close and re-open), file transfer would continue as usual. The method a given system uses to checkpoint a file is system dependent and not specified in DAP. During file transfer, control of checkpointing resides with the accessing process. It determines how often checkpoints should be taken. When the output file is checkpointed, the accessing process saves the pair (Li, Lo) where 1. Li is the input file current position locater (the location of the last record read). 2. Lo is the output file current position Locater (the location of the last record written). The pair (Lo,Li) should be saved on the disk as it is assumed to be secure. Both Li and Lo are eight bytes or less and can be any entity which, on its home system, can be used to uniquely and conveniently locate a record within a file, e.g., a record number or an RFA. Li and Lo need have no meaning other than on their home system. Note that Li and Lo are the positions on their respective systems of the same record. Thus, by writing (Li,Lo) to the disk simultaneously, there is no window where Li is out of step with Lo. Each time the accessing system writes a new (Li,Lo) to the disk, it supercedes the previous (Li,Lo). When checkpointing is used and a failure occurs, the checkpointed output file is incomplete and should not be used by other processes. There is a risk that unless it can be marked as incomplete or locked, it may inadvertently be used by another process before recovery can be DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 103 instituted and the file transfer completed. As some systems do not have such a capability, this is a risk they will have to live with. For those systems which have a locking capability, when recovering a file transfer, the Open should be with FB$LKO in the FOP field of the Access Message. 5.2.18.1 Recovery for File Store The state operations for file store with recovery is as in Section 5.2.2 except for the Control (Checkpoint) and Status Messages sent periodically to cause checkpoints to be taken. The set-up sequence is as for a normal file store except the ACCOPT field in the Access Message must set bit 4 indicating the recovery option is to be used. Also both Configuration Messages must show both systems support recovery. Following set-up, the data flow from accessing to accessed process is broken periodically by Control (Checkpoint) Messages which cause checkpoints to be taken. After the accessed process has checkpointed the output file, it responds with a Status Message indicating success with Lo in the RECNUM field. The accessing process writes (Li,Lo) to disk and continues transferring data. Accessing Process Accessed Process . . . RECORD n ----------> RECORD n+1 ----------> CONTROL ----------> (Take checkpoint) (CHECKPOINT) Save pair (Lo,Li) on disk <---------- STATUS (Success) <---------- ACK RECORD n+2 ----------> . . . Should the system fail during file transfer, after the system is up again, the output file (whose context will be that of the last checkpoint taken) is opened and recovery goes as follows: Accessing Process Accessed Process ATTRIBUTES ----------> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 104 ACCESS (OPEN) ----------> <---------- ATTRIBUTES <---------- ACK CONTROL(CONNECT) ----------> <---------- ACK CONTROL (RECOVERY ----------> (If sequential output STORE) file, position to record after Lo) (Open input file and position to record after Li) Record n+2 ----------> . . . The checkpointed output file is opened. The FOP field in the Access Message should have FB$LKO set in case the output file was locked at the time of the failure. The Control Message causes the output file to be positioned to the record after that specified by Lo -- Lo is in the KEY field. The accessing process opens the input file and positions it to the record following that specified by Li. Data transfer resumes and continues as for normal file storage. 5.2.18.2 Recovery for File Retrieval The state operations for file retrieval with recovery is as in Section 5.2.1 except for Control (Checkpoint) and Status Messages sent periodically to enable checkpoints to be taken. The set-up sequence is as for a normal file retrieval except both Configuration messages must show both systems support recovery and the ACCOPT field of the Access Message must have bit 4 set indicating the recovery option is to be used. When a checkpoint is to be taken, the accessing process sends a Control (Checkpoint) Message and the accessed process responds with a Status Message containing the Li of the last record sent in the RECNUM field. When the accessing process receives the Status Message, it checkpoints the output file and saves (Li,Lo) on disk. Accessing Process Accessed Process . . . <---------- RECORD n DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 105 <---------- RECORD n+1 CONTROL ----------> (CHECKPOINT) (Checkpoint output <---------- STATUS(Success with Li) file and then save (Li,Lo) on disk) <---------- RECORD n+2 . . . Should the system fail during file transfer, after the system is up again, the output file is opened and recovery goes as follows: Accessing Process Accessed Process ATTRIBUTES ----------> ACCESS (OPEN) ----------> <---------- ATTRIBUTES <---------- ACK CONTROL (CONNECT) ----------> <---------- ACK CONTROL (RECOVERY ----------> (Position input file GET with Li) to record following Li) (Position to record following Lo) <---------- RECORD n+2 . . . The accessing process opens the checkpointed output file and positions it to just after Lo. When the accessed process receives the Control Message (Recovery Get), it positions the input file to the record following Li from the KEY field. Data transfer resumes and continues as for normal file retrieval. 5.2.19 Wildcard Operations Wildcard operation for Sequential File Retrieval, File Deletion, File Renaming and Command File Execution is supported through the DAP message sequences defined in the following subsections. The wildcard DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 106 file specification contained in the Access Message is in the format used on the accessed system. NOTE It is not necessary to specify wildcard support in the CONFIG message in order to use wildcards with the Directory List function. Directory List support implies wildcard support for Directory List file specifications. However, wildcard support must be specified in order to use wildcards with any function other than Directory List. 5.2.19.1 Wildcard Sequential File Retrieval Wildcard sequential file retrieval operation is similar to sequential file retrieval as described in section 5.2.1 except that each file transferred is preceded by Name Messages as well as the file's attributes. The state operations for wildcard sequential file retrieval are (optional Attributes Extension Messages are not shown): Accessing Process Accessed Process ATTRIBUTES --------------> ACCESS (Wildcard) --------------> [<------------- NAME (Volume-set)] [<------------- NAME (Directory)] <------------- NAME (File) <------------- ATTRIBUTES <------------- ACK CONTROL (Connect) --------------> <------------- ACK CONTROL (Get) --------------> <------------- DATA <------------- DATA . . . <------------- DATA <------------- STATUS (EOF) ACCOMP (Close) --------------> <------------- NAME (File) <------------- ATTRIBUTES <------------- ACK CONTROL (Connect) --------------> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 107 <------------- ACK CONTROL (Get) --------------> <------------- DATA . . . <------------- STATUS (EOF) ACCOMP (Close) --------------> . . . <------------- NAME (File) <------------- ATTRIBUTES <------------- ACK CONTROL (Connect) --------------> <------------- ACK CONTROL (Get) --------------> <------------- DATA . . . <------------- DATA <------------- STATUS (EOF) ACCOMP (Close) --------------> <------------- ACCOMP (Response) A new Name Message for the Volume-set or Directory is only sent when either the volume-set or directory change. If the accessing process does not want one of the files specified by the wildcard file specification, it closes the file instead of establishing a data stream thus skipping the file. . . . <------------- NAME (File) <------------- ATTRIBUTES <------------- ACK ACCOMP (Close) -------------> <------------- NAME (of next file) . . . If during a file transfer, the accessing process decides it does not require the remainder of the file but wants to go on to the next file, it terminates the access to the current file with an ACCOMP(Close). The accessed process will close the current file and initiate the transfer of the next file in the wildcard series. Note that due to pipelining, the accessing process may receive several Data Messages or a Status Message before the Name Message. . DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 108 . . <------------- NAME (File) <------------- ATTRIBUTES <------------- ACK CONTROL (Connect) --------------> <------------- ACK CONTROL (Get) --------------> <------------- DATA <------------- DATA . . . <------------- DATA ACCOMP (Close) --------------> <------------- NAME (File) <------------- ATTRIBUTES <------------- ACK . . . The accessing process may abort a wildcard file retrieval at anytime by disconnecting the link. When the accessed process detects link termination, it will close any currently open files. . . . <------------- NAME (File) <------------- ATTRIBUTES <------------- ACK CONTROL (Connect) --------------> <------------- ACK CONTROL (Get) --------------> <------------- DATA . . . disconnect link Errors for wildcard sequential file retrieval are handled as with normal file retrieval except for errors in closing the file (excluding checksum errors) where ACCOMP (Skip) is used to force file closure and clear the link so the accessed process can proceed to the next file to be transferred. . . . ACCOMP (Close) -------------> <------------- STATUS ACCOMP (Skip) -------------> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 109 <------------- NAME (next file) <------------- ATTRIBUTES . . . or ACCOMP (Close) -------------> <------------- STATUS disconnect link 5.2.19.2 Wildcard File Deletion Wildcard file deletion has two modes of operation: 1. normal where all files specified by the wildcard specification are deleted before any response (except error) is returned to the accessing process. 2. Go/No-Go where the name of each file meeting the wildcard file specification is returned to the accessing process before the file is deleted. The accessing process can then cause the file to be deleted by sending a CONTR (Resume) Message or the file to be left in the file system by sending a CONTR (Skip) Message. The Go/No-Go mode of operation is specified by setting bit 4 in the ACCOPT field of the Access Message. The operation of normal wildcard file deletion is: Accessing Process Accessed Process ACCESS (Wildcard) ---------------> <-------------- ACCOMP (Response) Operation of Go/No-Go wildcard file deletion is: ACCESS (Wildcard) --------------> [<-------------- NAME (Volume)] [<-------------- NAME (Directory)] <-------------- NAME (File) CONTR (Resume) --------------> (delete file) <-------------- NAME (File) CONTR (Skip) --------------> (do not delete) <-------------- NAME (File) CONTR (Resume) --------------> (delete file) . . DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 110 . <-------------- NAME (File) CONTR (Resume) --------------> (delete file) <-------------- ACCOMP (Response) Go/No-Go wildcard file deletion can be aborted by disconnecting the link. ACCESS (Wildcard) -------------> [<------------- NAME (Volume)] [<------------- NAME (Directory)] <------------- NAME (File) CONTR (Resume) -------------> <------------- NAME (File) disconnect link Errors for wildcard file deletion are handled using the Continue Transfer Message to retry the deletion of the file causing the error or skip the file causing the error or the operation may be aborted by disconnecting the link. The operation of error handling (with Go/No-Go) is: ACCESS (Wildcard) -------------> [<------------- NAME (Volume)] [<------------- NAME (Directory)] <------------- NAME (File) <------------- STATUS CONTR (Try again) -------------> (Repeat operation) or <------------- NAME (File) <------------- STATUS CONTR (Skip) -------------> (Skip file) <------------- NAME (of next file) CONTR (Resume) -------------> (delete next file) or <------------- NAME (File) <------------- STATUS disconnect link The operation of error handling without the Go/No-Go option is identical to that with Go/No-Go except that once the error has been dealt with, the CONTR (Resume) is not required as in the above sequence. The operation without Go/No-Go is as follows: ACCESS (Wildcard) -------------> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 111 [<------------- NAME (Volume)] [<------------- NAME (Directory)] <------------- NAME (File) <------------- STATUS CONTR (Try again) -------------> (Repeat operation) or <------------- NAME (File) <------------- STATUS CONTR (Skip) -------------> (Skip file) or <------------- NAME (File) <------------- STATUS disconnect link NOTE Go/No-Go operation can also be used with single file delete. Setting bit 4 of ACCOPT will request this option. 5.2.19.3 Wildcard File Rename Wildcard file rename operation is identical to wildcard file deletion except that a second file specification must be supplied as for normal rename (see section 5.2.8) which affects only the set-up as shown below (using Go/No-Go operation): Accessing Process Accessed Process [NAME (default] ---------------> ACCESS (wildcard)---------------> [NAME (default)] ---------------> NAME (wildcard) ---------------> [<-------------- NAME (old volume)] [<-------------- NAME (old directory)] <-------------- NAME (old file) CONTR (Resume) ---------------> (rename file) . . . <-------------- ACCOMP (Response) In other respects, wildcard rename operation is identical to wildcard delete. 5.2.19.4 Wildcard Command File Execution DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 112 Wildcard command file execution operation is identical to wildcard file deletion operation. 5.2.20 Deleting a Record $DELETE deletes the current record for those files where record deletion is possible, e.g. relative or indexed files usually support record deletion. . . . CONTROL(DELETE) -----> <----- STATUS . . . 5.2.21 Find $FIND operation is essentially identical to $GET except that it does not transfer any data; the specified record becomes the current record. . . . CONTROL(FIND) -----> <----- STATUS . . . 5.2.22 Update $UPDATE causes the current record to be updated with the record in the following Data Message on this stream. The Control(Update) and Data Messages together form a transaction and must not have any intervening messages on that stream. For convenience and efficiency, they can be blocked together. The operation is . . . CONTROL(UPDATE)-----> DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 113 DATA -----> <----- STATUS . . . Because of the transaction nature of update, if an error occurs at any point in the operation, the whole transaction fails. If the accessed process detects an error in the Control Message, it will send the appropriate Status Message and it will also discard the next Data Message on that stream as it was a part of the transaction that failed. The accessing process recovers by starting the transaction over (having corrected the error) with new Control and Data Messages as below: . . . CONTROL(UPDATE)-----> (error detected) DATA -----> (discard) <----- STATUS (with error code) Corrected CONTROL(UPDATE)-----> DATA -----> <----- STATUS (successful) . . . If an error is detected in the Data Message, the accessed process returns the appropriate Status Message and considers the whole transaction to have failed (current position may be lost depending on the nature of the error -- it may be necessary to re-establish the current position in the file). After correcting the error in the Data Message, the accessing process must repeat the entire transaction: . . . CONTROL(UPDATE)-----> DATA -----> (error detected) <----- STATUS (with error code) DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 114 CONTROL(UPDATE)-----> Corrected DATA -----> <----- STATUS . . . 5.3 Closing a File and Terminating Data Streams The ACCOMP End of Stream (EOS) command is used to terminate a data stream. When the accessing process wishes to terminate a data stream, it may do so by sending an ACCOMP(EOS) containing the STREAMID it wishes to terminate. This will not close the file even if it terminates the last active data stream. An ACCOMP (Close) is used to close the file and terminate the access, which includes closing out all remaining active data streams. 5.4 Terminating a Logical Link The logical link is terminated by issuing a Disconnect Request. During the setup of the link, this may be done by the accessed process if optional timers indicate delay by the accessing process in supplying the required information. Once setup is complete, the accessing process controls the rate of access of the file. Disconnection at this point usually follows access completion. The accessing process may disconnect at any time; however, different systems may handle file closing and disposition differently if disconnection occurs during transfers. The accessing process is not required to disconnect and reconnect following each access. However, if a new access is to be started, it must be initiated in a timely manner. If a timer is being used between setup messages, it should also be set by the accessed process following an Access Complete Message. 5.5 File Security, Integrity and Protection 5.5.1 Access Control DAP attempts to provide approximately the same degree of file security and protection over the network as is available locally. To do this, a DAP user must be a registered user of each system holding files he DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 115 wishes to access. Embedded in the connect message sent by the accessing process is sufficient information for the user to be logged onto the system that has files he wishes to access. User access is first verified (not necessarily actually logged-on) and then file access is allowed to proceed under the normal rules for file access applicable to a local user. If the accessing process wants to change the account under which the accessed process is running at the remote node, it must disconnect the logical link and reconnect specifying the new account in the connect. 5.5.2 Data Integrity Optionally, a checksum on all data transferred (in both directions) during a file access can be generated by both the transmitting and receiving node to ensure data integrity. If this optional checksum is required, a bit in the ACCOPT field of the Access Message is set. The accessing and accessed DAP processes compute the checksum on the data in the DAP Data Message whenever a Data Message is sent or received. When the access is complete and the remote file is being closed, the checksum generated by the accessing process is sent to the accessed process in the CHECK field of the Access Complete (Close) Message. The accessed process compares the checksum it received with the checksum it generated and closes the file if they agree. If they do not agree, a Status Message is returned to the accessing process instead of an Access Complete (Response). If a checksum error occurs, the accessing process can either purge the output file or, if errors can be tolerated, keep and close the output file (see sections 5.2.1 and 5.2.2) by sending the appropriate Access Complete Message without the CHECK field. Checksum errors should be logged by the accessing process (and optionally by the accessed process) as they can not caused by users. The checksum is a CRC and is computed only on the data in DAP Data Messages, i.e. Data Message headers are not included. The CRC polynomial is X**16 + X**15 + X**13 + X**7 + X**4 + X**2 + X + 1 Before starting data transfer, the 16-bit CRC should be initialized to -1, i.e. all bits set. 5.6 DAP Based Applications Written by DIGITAL DAP message types 128 through 191 have been reserved for DEC written applications based on DAP but requiring further application specific messages in the protocol. FTS is an example of such an application. It requires the USERID message defined in Appendix B to supply accounting and access control information to the remote FTS server process. 5.6.1 Access Control and Accounting for DAP Based Applications DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 116 The USERID Message is designed for use by applications using cooperating, DAP-speaking control processes to offer a file transfer based service to network users. One of the control processes is a queueing process, which handles the user's requests for file transfer and the other is a server process which handles the remote end of executing the users' transfers. These control processes will characteristically establish a link and sequentially transfer several users' files over the same link. The server control process runs as a privileged process so it has access to all files within the system. This scheme places the responsibility for access control (a user should be allowed to access only those files he has explicit permission to access) and accounting (charge each user for the resources he uses) on the cooperating control processes. (The control processes are charged for the resources they use as they are "logged-on" the systems they are running on. They need to pass the charges on to the users of the services). In order to perform access control and accounting functions, the server process needs the user's identification and optional account number. The DAP Application Message, USERID, (see Appendix B) supplies this information. Note that security is not an issue here. The server process "trusts" the queueuing process and assumes that the contents of the USERID messages are correct and any necessary validation has been done by the queueing process. Therefore a password is not necessary or even desirable in the USERID message. The server process can "trust" the queueing process as long as it is talking to a valid queueing process. This is ensured by the NSP access control procedure which validates a password supplied by the queueing process before it allows a logical link to be established. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 117 APPENDIX A GLOSSARY BUCKET A grouping of a file's virtual blocks used for I/O transfer or structural format storage. ISAM Indexed Sequential Access Method. This access method is a combination of random and sequential access. Random access is used to locate a sequence of records and then access is switched to sequential to read the remaining records in the series. JFN Job File Number. The JFN is the job's global handle on a file. Key A data item used to locate a record in a random access file system. Key field For direct and indexed files, the position of the key within the record. Key of The particular key field of the record for which the reference key applies. Octets Octets in this document are bytes of 8 bits, with bit 0 the rightmost (low-order, least-significant) bit and bit 7 the leftmost (high-order, most-significant) bit. Fields and bytes of other lengths are numbered similarly. Object Type Numeric value that may be used for process addressing by DECnet processes instead of a process name. See the NSP specification for further details. DAP server processes are object type number 21 (octal). RFA Record File Address. The unique address of a record within a file. This method of addressing can be used explicitly with RMS. RMS Record Management Services. This file system will be used on all major DIGITAL systems except where space is limited (e.g., RT-11). In addition to access modes provided by previous file systems, RMS provides random access for direct and indexed files and ISAM. URD Unit Record Device. VBN Virtual Block Number. This number is in the range 1 to n where n is the highest numbered block allocated to the file. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 118 APPENDIX B User Identification Message The User Identification Message is an application message designed for use by DIGITAL's File Transfer System (FTS) and other DAP based applications using the same queueing model. This queueing model consists of two controlling processes which speak DAP across the network. One of the processes accepts and queues requests from users to transfer files. The other is a server process which executes the user's requests at the remote node in response to DAP messages from the first process. A single logical link may be used to sequentially process any number of user requests. It is not necessary to disconnect the link after processing each user's file transfer request. In order that appropriate access control and accounting measures can be taken by the server process, the queueing control process sends a USERID message each time it initiates a file access for a new user. The USERID contains the identity (e.g. PPN) under which the access at the remote node takes place plus the optional user account number. The USERID is sent immediately before the Attributes Message when initiating a new file access. The form of the USERID message is: USERID IDMENU IDENT ACCOUNT OPTIONS where: USERID : = The operator field with TYPE=128. IDMENU(EX-6) : BM = The following bit map specifies which of the following fields are present in this message. If the field is not present, the default, if any, should be used. These fields and only these fields may appear in the message and they must appear in the order specified. Bit Meaning (when set) 0 IDENT 1 ACCOUNT 2 OPTIONS DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 119 IDENT(I-40) : A = The user identification (e.g., UIC) under which the server process will be executing the following remote file accesses. This establishes the user's identity for both resource usage accounting at the remote node and file access rights. If this field is defaulted, the previous identity in effect will remain in effect. When a link is first established, the user identity from the NSP connect message is the user identity in effect. ACCOUNT(I-40) : A = For systems requiring additional information for accounting, e.g., discrete project number, this field contains this accounting information. OPTIONS(I-132) : A = Options field for additional information which may be required by the server control process. It may be used for supplimental accounting information, page headers, or perhaps non-network routing information for mail. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 120 APPENDIX C Revision History C1. Version 1.0 to Version 4.1. A number of significant changes have been made to the Data Access Protocol since its first release. The major differences between DAP Version 4.1 and Version 1.0 are: a. DAP Version 1.0 could not adequately support indexed and ISAM file access; b. The format of the operator field has been expanded; c. The USERID Message has been eliminated; d. The Status and Error Messages have been combined; e. The Access Complete Message has been added; f. The Configuration Message has been added; and g. The two types of Data Messages employed in Version 1.0 have been merged into one Data Message in Version 4.1. While a definite incompatibility exists between Versions 1.0 and 4.1, numerous steps have been taken to build a more flexible architecture. DAP Version 4.1 is flexible enough to allow new file access functions to be added to the protocol framework. C2. Version 4.1 to Version 5.6. A number of significant changes have been made to DAP since the Version 4.1 release. The major differences are as follows: a. the Key Definition, Allocation, Summary, Date and Time, Protection and Name Messages have been added -- previously some of these were present but marked reserved. b. The format of the operator field has been expanded again to allow blocking of DAP messages greater than 256 bytes long and to allow an optional field in the Data Message. c. A File Transfer checksum on the complete file has been added for better file integrity. d. Indexed file access is now fully supported. Only record number random access was supported in 4.1. e. The Configuration Message has been expanded to include more capabilities. f. PRINT File Carriage Control has been added. g. The IMAGE Data Type definition has been clarified, especially for files containing non 8-bit bytes. h. The MACY11 Data Type has been added. i. Explanation of how to use the Extended Attributes Messages has been added. j. Rename has been added. k. Display and Directory List have been added. l. Several new Control Message options have been added. m. Wildcard support has been added. DAP SPECIFICATION, Version 5.6, 28-March-1980 Page 121 The 5.6 version of DAP is upwardly compatible with the 4.1 version. The new facilities in 5.6 have been put into the protocol using extensibility built into DAP Version 4.1. **** End of Specification ****