07/27/90 iox_ Performs I/O operations and some related functions. The user should be familiar with the contents of "Multics Input/Output System" and "File Input/Output" in the Programmer's Reference Manual (AG91). Each entry point documented here has an argument denoting the particular I/O switch involved in the operation. For an entry point that requires the I/O switch to be in the attached state, the description of the function of the entry point applies only when the switch is attached. For other states, see the description of the particular I/O module. (The standard system I/O modules are described in Section 3 of the Multics Subroutines and I/O Modules manual (AG93).) When an entry point requires the I/O switch to be opened and it is not open, the state of the switch is not changed and the code error_table_$not_open is returned. If the I/O switch is open but the operation is not allowed for that opening mode, the state of the switch is not changed and the code that is returned is error_table_$no_operation. Operations pertaining to files use four position designators for reference: the next byte, the next record, the current record, and the key for insertion. Several operations involve the use of a buffer. A buffer is a block of storage provided by the caller of the operation as the target for input or the source for output. A buffer must be byte aligned; i.e., its bit address and bit length must both be evenly divisible by 9. The code returned by an entry point may be other than a standard status code in cases where the I/O switch is attached via a nonstandard I/O module. All entry points in iox_ are declared in the include file iox_dcls.incl.pl1. Entry points in iox_: (List is generated by the help command) :Entry: attach_loud: 07/27/90 iox_$attach_loud Function: This entry point is the same as iox_$attach_ptr except that a call to this entry turns on the com_err_ switch of the I/O module. This means that the attach routine of the I/O module calls com_err_ when an error is detected. Syntax: declare iox_$attach_loud entry (ptr, char(*), ptr, fixed bin(35)); call iox_$attach_loud (iocb_ptr, atd, ref_ptr, code); Arguments: iocb_ptr points to the switch's control block. (Input) atd is the attach description. (Input) ref_ptr is a pointer to the referencing procedure, used by the search rules to find an I/O module. (Input) (See hcs_$make_ptr for more information about ref_ptr.) code is an I/O system status code. Notes: The code returned by an entry point may be other than a standard status code in cases where the I/O switch is attached via a nonstandard I/O module. :Entry: attach_name: 07/27/90 iox_$attach_name Function: attaches an I/O switch in accordance with a specified attach description. The switch is designated by name and a pointer to its control block is returned. The control block is created if it does not already exist. The form of an attach description is given in the Programmer's Reference Manual. The I/O module is located using the current search rules. Syntax: declare iox_$attach_name entry (char(*), ptr, char(*), ptr, fixed bin(35)); call iox_$attach_name (switch_name, iocb_ptr, atd, ref_ptr, code); Arguments: switch_name is the name of the I/O switch. (Input) iocb_ptr points to the switch's control block. (Output) atd is the attach description. (Input) ref_ptr is a pointer to the referencing procedure, used by the search rules to find an I/O module. (Input) If ref_ptr is null, then the standard search rule specifying the referencing directory is skipped. code is an I/O system status code. (Output) error_table_$not_detached the switch is not in the detached state. Its state is not changed. :Entry: attach_ptr: 01/24/84 iox_$attach_ptr Function: attaches an I/O switch in accordance with a specified attach description. The I/O module is located using the current search rules. Syntax: declare iox_$attach_ptr entry (ptr, char(*), ptr, fixed bin(35)); call iox_$attach_ptr (iocb_ptr, atd, ref_ptr, code); Arguments: iocb_ptr points to the switch's control block. (Input) atd is the attach description. (Input) ref_ptr is a pointer to the referencing procedure, used by the search rules to find an I/O module. (Input) If ref_ptr is null, then the standard search rule specifying the referencing directory is skipped. code is an I/O system status code. (Output) error_table_$not_detached the switch is not in the detached state. Its state is not changed. Notes: The ref_ptr argument can be used to specify a particular I/O module if one by that name is not already initiated, for example: call iox_$attach_ptr (iocb_ptr, "discard_", addr (my_discard_$my_discard_attach), code); :Entry: close: 01/24/84 iox_$close Function: closes an I/O switch. Syntax: declare iox_$close entry (ptr, fixed bin(35)); call iox_$close (iocb_ptr, code); Arguments: iocb_ptr points to the switch's control block. (Input) code is an I/O system status code. (Output) error_table_$not_open is returned if the switch is not open. Its state is not changed. :Entry: close_file: 01/24/84 iox_$close_file Function: This entry point closes an I/O switch. If the switch is not open, its state is not changed and the code error_table_$not_open is returned. This entry point differs from the iox_$close entry point due to the addition of the close description argument. For those I/O modules that support the close_file entry, the close description offers a means of providing file closing parameters such as a closing comment, where to position to upon closing etc. Syntax: declare iox_$close_file entry (ptr, char (*), fixed bin(35)); call iox_$close_file (iocb_ptr, cld, code); Arguments: iocb_ptr points to the switch's control block. (Input) cld is the close description. (Input) code is an I/O system status code. (Output) :Entry: control: 01/24/84 iox_$control Function: performs a specified control order on an I/O switch. The allowed control orders depend on the attachment of the switch. For details on control orders, see the description of the particular I/O module used in the attach operation. Syntax: declare iox_$control entry (ptr, char(*), ptr, fixed bin(35)); call iox_$control (iocb_ptr, order, info_ptr, code); Arguments: iocb_ptr points to the switch's control block. (Input) order is the name of the control order. (Input) info_ptr is null or points to data whose form depends on the attachment. (Input) code is an I/O system status code. (Output) error_table_$no_operation is returned if the switch is open for a control order which is not supported for a particular attachment, or is returned by I/O modules that support orders with the switch closed. error_table_$not_open is returned if the switch is closed. :Entry: delete_record: 01/24/84 iox_$delete_record Function: deletes the current record from the file to which an I/O switch is attached. The switch must be open for sequential_update, keyed_sequential_update, or direct_update. If the file is open for direct_update and the deletion takes place, the current and next record positions are set to null. For keyed_sequential_update, the current and next record positions are set to the record following the deleted record or to end of file (if there is no such record). Syntax: declare iox_$delete_record entry (ptr, fixed bin(35)); call iox_$delete_record (iocb_ptr, code); Arguments: iocb_ptr points to the switch's control block. (Input) code is an I/O system status code. (Output) error_table_$no_record the current record is null. The file's position is not changed. :Entry: destroy_iocb: 01/24/84 iox_$destroy_iocb Function: frees the storage used by the control block for an I/O switch. The switch must be in the detached state. Any existing pointers to the control block become invalid. Syntax: declare iox_$destroy_iocb entry (ptr, fixed bin(35)); call iox_$destroy_iocb (iocb_ptr, code); Arguments: iocb_ptr points to the I/O control block to be freed. (Input) code is an I/O system status code. (Output) :Entry: detach: 07/24/90 iox_$detach Function: detaches an I/O switch. If the switch is already detached, its state is not changed and the code error_table_$not_attached is returned. If the switch is open, its state is not changed and the code error_table_$not_closed is returned. This entry point differs from the iox_$detach_iocb entry point due to the addition of the detach description argument. For those I/O modules that support the detach entry, the detach description offers a means of providing detach time parameters such as a resource disposition comment to be sent to the system operator. Syntax: declare iox_$detach entry (ptr, char (*), fixed bin (35)); call iox_$detach (iocb_ptr, dtd, code); Arguments: iocb_ptr points to the switch's control block. (Input) dtd is the detach description. (Input) code is an I/O system status code. (Output) :Entry: detach_iocb: 01/24/84 iox_$detach_iocb Function: detaches an I/O switch. Syntax: declare iox_$detach_iocb entry (ptr, fixed(35)); call iox_$detach_iocb (iocb_ptr, code); Arguments: iocb_ptr points to the switch's control block. (Input) code is an I/O system status code. (Output) error_table_$not_attached the switch is already detached. Its state is not changed. error_table_$not_closed the switch is open. Its state is not changed. :Entry: err_no_operation: 01/24/84 iox_$err_no_operation Function: accepts any number of arguments, the last of which is fixed bin (35). It sets the last argument to the code error_table_$no_operation. This entry point is assigned to entry variables in the I/O control block in order to return an error code when that entry variable is called. See "Writing an I/O Module" in the Programmer's Reference Manual for instructions on when to assign this entry point to such an entry variable. Syntax: declare iox_$err_no_operation entry options (variable); call iox_$err_no_operation (arg1, ..., argN, code); Arguments: argI are user-supplied arguments. (Input) code is an I/O system status code. (Output) :Entry: err_not_attached: 01/24/84 iox_$err_not_attached Function: accepts any number of arguments, the last of which is fixed bin (35). It sets the last argument to the code error_table_$not_attached. This entry point is assigned to entry variables in the I/O control block in order to return an error code when that entry variable is called. See "Writing an I/O Module" in the Programmer's Reference Manual for instructions on when to assign this entry point to such an entry variable. Syntax: declare iox_$err_not_attached entry options (variable); call iox_$err_not_attached (arg1, ..., argN, code); Arguments: argI are user-supplied arguments. (Input) code is an I/O system status code. (Output) :Entry: err_not_closed: 01/24/84 iox_$err_not_closed Function: accepts any number of arguments, the last of which is fixed bin (35). It sets the last argument to the code error_table_$not_closed. This entry point is assigned to entry variables in the I/O control block in order to return an error code when that entry variable is called. See "Writing an I/O Module" in the Programmer's Reference Manual for instructions on when to assign this entry point to such an entry variable. Syntax: declare iox_$err_not_closed entry options (variable); call iox_$err_not_closed (arg1, ..., argN, code); Arguments: argI are user-supplied arguments. (Input) code is an I/O system status code. (Output) :Entry: err_not_open: 01/24/84 iox_$err_not_open Function: accepts any number of arguments, the last of which is fixed bin (35). It sets the last argument to the code error_table_$not_open. This entry point is assigned to entry variables in the I/O control block in order to return an error code when that entry variable is called. See "Writing an I/O Module" in the Programmer's Reference Manual for instructions on when to assign this entry point to such an entry variable. Syntax: declare iox_$err_not_open entry options (variable); call iox_$err_not_open (arg1, ..., argN, code); Arguments: argI are user-supplied arguments. (Input) code is an I/O system status code. (Output) :Entry: find_iocb: 07/27/90 iox_$find_iocb Function: returns a pointer to the control block for an I/O switch. The control block is created if it does not already exist. Syntax: declare iox_$find_iocb entry (char(*), ptr, fixed bin(35)); call iox_$find_iocb (switch_name, iocb_ptr, code); Arguments: switch_name is the name of the I/O switch. (Input) iocb_ptr points to the switch's control block. (Output) code is an I/O system status code. (Output) Notes: if the IOCB you need is for one of the four standard I/O switches, you do not need iox_$find_iocb, but should use one of the four standard external static pointers, iox_$user_io, iox_$user_input, iox_$user_output, or iox_$error_output. These pointers are declared in iox_dcls.incl.pl1. :Entry: find_iocb_n: 01/24/84 iox_$find_iocb_n Function: may be used to find all existing I/O control blocks, whether attached or detached. It returns a pointer to the n'th control block in the calling ring, the numbering being arbitrary. If there are fewer than n control blocks, a null pointer and the code error_table_$no_iocb are returned. Creating or destroying control blocks during a sequence of calls to this entry point should be avoided, as it causes unpredictable changes to the numbering. Syntax: declare iox_$find_iocb_n entry (fixed bin, ptr, fixed bin(35)); call iox_$find_iocb_n (n, iocb_ptr, code); Arguments: n is the number of the I/O control block. (Input) iocb_ptr is a pointer to the control block. (Output) code is an I/O system status code. (Output) error_table_$no_iocb there are fewer than n control blocks. :Entry: get_chars: 07/27/90 iox_$get_chars Function: reads 9-bit bytes from the unstructured file or device to which an I/O switch is attached. The switch must be open for stream_input or stream_input_output. The desired number of bytes, n, is specified in the call. Some I/O modules may actually read fewer than n bytes into the buffer, even though n bytes are available from the file or device. The contents of the buffer beyond the last byte read are undefined. If the switch is attached to a file, bytes are read beginning with the next byte, and the next byte position designator is advanced by the number of bytes read. It is possible to write a program which takes certain actions if a call to iox_ takes longer than a certain amount of time. See the timed_io_$get_chars entry point. Syntax: declare iox_$get_chars entry (ptr, ptr, fixed bin(21), fixed bin(21), fixed bin(35)); call iox_$get_chars (iocb_ptr, buff_ptr, n, n_read, code); Arguments: iocb_ptr points to the switch's control block. (Input) buff_ptr points to the byte-aligned buffer into which bytes are to be read. (Input) n is the number of bytes to be read where n>=0. (Input) n_read is the number of bytes actually read. (Output) If code is 0, n_read equals n. code is an I/O system status code. (Output) error_table_$short_record fewer than n bytes were read into the buffer. When this code is returned, the caller may again call the iox_$get_chars entry point to get more bytes. If fewer than n bytes remain in the file, this code is returned, and the next byte position is set to end of file. error_table_$end_of_info the next byte position is already at end of the file. :Entry: get_line: 07/27/90 iox_$get_line Function: reads 9-bit bytes from the unstructured file or device to which an I/O switch is attached. The switch must be open for stream_input or stream_input_output. Bytes are read until the input buffer is filled, a newline character is read, or end of file is reached, whichever occurs first. The contents of the buffer beyond the last byte read are undefined. If the switch is attached to a file, bytes are read beginning with the next byte, and the next byte position designator is advanced by the number of bytes read. It is possible to write a program which takes certain actions if a call to iox_ takes longer than a certain amount of time. See the timed_io_$get_line entry point. Syntax: declare iox_$get_line entry (ptr, ptr, fixed bin(21), fixed bin(21), fixed bin(35)); call iox_$get_line (iocb_ptr, buff_ptr, buff_len, n_read, code); Arguments: iocb_ptr points to the switch's control block. (Input) buff_ptr points to a byte-aligned buffer. (Input) buff_len is the length of the buffer in bytes. (Input) n_read is the number of bytes read into the buffer. (Output) code is an I/O system status code. (Output) 0 is returned if and only if a newline character is read into the buffer (it will be the last character read). error_table_$long_record the input buffer was filled without reading a newline character, or the read operation occurred with the input buffer length at zero. error_table_$end_of_info the next byte was initially at end of file. error_table_$short_record the end of file was reached without reading a newline character, and the next byte position designator was set to end of file. :Entry: init_standard_iocbs: 07/27/90 iox_$init_standard_iocbs Function: attaches the standard switches for a user process. These are currently user_input, user_output, and error_output, and they are attached with attach descriptions of: syn_ user_i/o -inhibit close,put_chars syn_ user_i/o -inhibit close,get_line,get_chars syn_ user_i/o -inhibit close,get_line,get_chars The variables iox_$user_input, iox_$user_output, and iox_$error_output are set to the iocb pointers for these switches. Syntax: declare iox_$init_standard_iocbs entry (); call iox_$init_standard_iocbs; Notes: Should the standard attachments change, this program will change to establish whatever they are. It should therefore be used in any direct process overseer that wishes to establish standard attachments. :Entry: look_iocb: 01/24/84 iox_$look_iocb Function: returns a pointer to the control block for a specified I/O switch. If the control block does not exist, it is not created, and a null pointer and the code error_table_$no_iocb are returned. Syntax: declare iox_$look_iocb entry (char(*), ptr, fixed bin(35)); call iox_$look_iocb (switch_name, iocb_ptr, code); Arguments: switch_name is the name of the I/O switch. (Input) iocb_ptr is a pointer to the control block. (Output) code is an I/O system status code. (Output) error_table_$no_iocb the control block does not exist. :Entry: modes: 07/27/90 iox_$modes Function: This entry point is used to obtain or set modes that affect the subsequent behavior of an I/O switch. The switch must be attached via an I/O module that supports modes. Each mode is a sequence of nonblank characters. A mode string is a sequence of modes, separated by commas and containing no blanks. For a list of valid modes, see the particular I/O module involved. Syntax: declare iox_$modes entry (ptr, char(*), char(*), fixed bin(35)); call iox_$modes (iocb_ptr, new_modes, old_modes, code); Arguments: iocb_ptr points to the switch's control block. (Input) new_modes is the mode string containing the modes to be set. (Input) Other modes are not affected. If this argument is the null string, no modes are changed. old_modes is the string of modes in force when the call is made. (Output) If this argument has length zero, this information is not returned. This argument should be declared large enough to accommodate all the modes supported by the I/O module; 512 characters should be large enough for all system-supplied I/O modules. code is an I/O system status code. (Output) It can be: error_table_$not_attached the switch is not attached via an I/O module that supports modes. error_table_$no_operation the switch is attached, but modes are not supported for an open switch. error_table_$not_open the switch is attached, but modes are not supported for a closed switch. error_table_$bad_mode the switch is attached and modes are supported, but an invalid mode is given. :Entry: move_attach: 01/24/84 iox_$move_attach Function: moves an attachment from one I/O switch, s1, to another I/O switch, s2. The s1 I/O switch must be in the attached state and the s2 switch must be in the detached state when the entry point is called. Moving the attachment moves the attach description and open description of the s1 I/O switch to the s2 I/O switch. All pointer values and entry values are copied from the control block of the s1 I/O switch to the control block of the s2 I/O switch. (These values are listed in "I/O Control Block" in the Programmer's Reference Manual.) Attach and open data blocks maintained by the I/O module (if the s1 I/O switch is attached) are not affected. Finally, the s1 I/O switch is set to the detached state and iox_$propagate is called for both I/O switches. Syntax: declare iox_$move_attach entry (ptr, ptr, fixed bin(35)); call iox_$move_attach (iocb_ptr_1, iocb_ptr_2, code); Arguments: iocb_ptr_1 points to the control block for the I/O switch (s1) that is currently attached. (Input) iocb_ptr_2 points to the control block for the I/O switch (s2) that the user intends to attach. (Input) code is an I/O system status code. (Output) error_table_$not_attached the I/O switch s1 was not attached. No change is made to either I/O switch. error_table_$not_detached the I/O switch s2 was not detached. No change is made to either I/O switch. :Entry: open: 07/27/90 iox_$open Function: opens an I/O switch. The switch must be attached via an I/O module that supports the specified opening mode, and it must be in the closed state. If the switch is attached to a file, the appropriate file position designators are established, and an existing file may be replaced by an empty file. This replacement may be avoided by specifying extension of the file in the attach description. See the information on File Input/Output in the Programmer's Reference Manual for details. Syntax: declare iox_$open (ptr, fixed bin, bit (1) aligned, fixed bin(35)); call iox_$open (iocb_ptr, mode, unused, code); Arguments: iocb_ptr is a pointer to the control block. (Input) mode is the number assigned to the mode, e.g., 1 for stream_input, 2 for stream_output. (Input) Numbers associated with all allowed I/O modes are described in the Programmer's Reference Manual as part of the information on Input/Output Facilities. Named constant values for these modes are defined in iox_modes.incl.pl1. unused must be "0"b. (Input) code is an I/O system status code. (Output) error_table_$not_attached the switch is not attached. Its state is not changed. error_table_$not_closed the switch is already open. :Entry: open_file: 01/24/84 iox_$open_file Function: opens an I/O switch. The switch must be attached via an I/O module that supports the specified opening mode, and it must be in the closed state. If the switch is not attached, its state is not changed and the code error_table_$not_attached is returned. If the switch is already open, the code error_table_$not_closed is returned. This entry point differs from the iox_$open entry point due to the addition of the open description argument. For those I/O modules that support the open_file entry, the open description offers a means of providing file opening parameters such as format, block size, record size, etc. The open description also allows the logical separation of attachment of resources, such as tape volumes, with the iox_$attach_name and iox_$attach_ptr entry points, and file specific operations for those I/O modules that deal with multi-file resources. Syntax: declare iox_$open_file (ptr, fixed bin, char(*), bit(1) aligned, fixed bin (35)); call iox_$open_file (iocb_ptr, mode, opd, unused, code); Arguments: iocb_ptr is a pointer to the control block. (Input) mode is the number assigned to the mode as shown in the Programmer's Reference Manual under "Input and Output Facilities". (Input) For example, 1 for stream_input, 2 for stream_output. Named constant values for these modes are defined in iox_modes.incl.pl1. opd is the open description. (Input) unused must be "0"b. (Input) code is an I/O system status code. (Output) :Entry: position: 07/27/90 iox_$position Function: For an I/O switch attached to a file, this entry point positions to the beginning or end of the file, or skips forward or backward over a specified number of lines (unstructured files) or records (structured files). For an I/O switch attached to a device, this operation reads and discards characters until a specified number of newline characters have been skipped. The switch must be opened in one of the following modes: stream_input stream_input_output sequential_input sequential_input_output sequential_update keyed_sequential_input keyed_sequential_update In addition, for keyed openings, the next record position should not be null. If it is null, the code error_table_$no_record is returned. Syntax: declare iox_$position entry (ptr, fixed bin, fixed bin(21), fixed bin(35)); call iox_$position (iocb_ptr, type, n, code); Arguments: iocb_ptr is a pointer to the control block. (Input) type identifies the type of positioning. (Input) -1 goes to the beginning of the file +1 goes to the end of the file 0 skips newline characters or records 2 positions to an absolute character or record 3 skip characters (stream input only) n is the number of lines, records, or characters to be skipped (forward skip) or the negative of that number (backward skip), or the absolute position. (Input) It may be 0. code is an I/O system status code. (Output) error_table_$no_record the next record position is null (for keyed openings). error_table_$end_of_info the file contains too few characters. The next byte position is at the end of file (forward skip) or beginning of file (backwards skip). Notes: Absolute positioning moves the next byte or record position to the location specified by n. Skipping characters moves the next byte position forward or backward over n characters. Positioning to the beginning of a nonempty file sets the next record position at the first record in the file (sequential and keyed_sequential openings) or sets the next byte position at the first byte in the file (stream openings). Positioning to the end of a file, or to the beginning of an empty file, sets the relevant position designator to the end-of-file position. Successively skipping records (sequential and keyed_sequential openings) moves the next record position forward or backward by the specified number of records, n, provided that many records exist in the indicated direction. For example, suppose that when the iox_$position entry point is called, the next record is the mth record in the file, and n records are to be skipped. Then for a successful forward skip, the file must contain at least (m+n-1) records, and the next record will be set to record (m+n) (if there are at least m+n records in the file) or to end of file (if there are m+n-1 or fewer records in the file). For a successfull backward skip, m must be greater than n, and the next record position is set to record (m-n). Successively skipping forward over newline characters (stream openings) advances the next byte position over the specified number, n, of newline characters, leaving it at the byte following the nth newline character or at end of file (if the nth newline character is the last byte in the file). Successively skipping backward over n newline characters moves the next byte position backward to the nth preceding newline character and then moves it further backward as far as is possible without encountering another newline character. The effect is to set the next byte position to the first character in a line. If the relevant part of the file contains too few records or newline characters, the next record position or next byte position is set to the first record or byte (backward skip with nonempty file) or end of file (all other cases), and the code error_table_$end_of_info is returned. When a call to the iox_$position entry point specifies skipping zero lines or records, the skip is successful, and the next record position is undisturbed. In openings for update, the current record position is set to the resulting next record or null if the next record is at end of file. In the case of keyed_sequential_update, the key for insertion is set to null. :Entry: propagate: 01/24/84 iox_$propagate Function: adjusts certain pointers and entry variables in an I/O control block as required when changing between the states detached, attached-closed, and attached-open. It also reflects modifications to a control block to other control blocks that are synonyms (immediate or chained) for it. This entry point must be called at certain points in the code of an I/O module, and it must not be called in any other circumstances. See "Writing an I/O Module" in the Programmer's Reference Manual for instructions on when to call iox_$propagate. Syntax: declare iox_$propagate entry (ptr); call iox_$propagate (iocb_ptr); Arguments: iocb_ptr is a pointer to the control block. (Input) :Entry: put_chars: 07/27/90 iox_$put_chars Function: writes a specified number of 9-bit bytes to the unstructured file or device to which an I/O switch is attached. The switch must be open for stream_output or stream_input_output. In the case of a file, if the opening is for stream_output, the bytes are simply added at the end of the file. However, if the opening is for stream_input_output, and the next byte position is not at end of file, the file is first truncated so that the byte preceding the next byte becomes the last byte in the file. The bytes being written are then added at the end of the file, and the next byte position is set to end of file. Truncation can be suppressed in storage system files by specifying an appropriate attach option. See the description of the vfile_ I/O module for details. It is possible to write a program which takes certain actions if a call to iox_ takes longer than a certain amount of time. See the timed_io_$put_chars entry point. Syntax: declare iox_$put_chars entry (ptr, ptr, fixed bin(21), fixed bin(35)); call iox_$put_chars (iocb_ptr, buff_ptr, n, code); Arguments: iocb_ptr is a pointer to the control block. (Input) buff_ptr points to a byte-aligned buffer containing the bytes to be written. (Input) n is the number of bytes to be written where n>=0. (Input) code is an I/O system status code. (Output) :Entry: read_key: 01/24/84 iox_$read_key Function: returns both the key and length of the next record in an indexed file attached to an I/O switch. The switch must be open for keyed_sequential_input or keyed_sequential_update. The next record position is unchanged and the current record position is set to the next record if the operation is successful; otherwise, the current record position is set to null. Syntax: declare iox_$read_key entry (ptr, char(256) varying, fixed bin(21), fixed bin(35)); call iox_$read_key (iocb_ptr, key, rec_len, code); Arguments: iocb_ptr is a pointer to the control block. (Input) key is the next record's key. (Output) rec_len is the next record's length in bytes. (Output) code is an I/O system status code. (Output) error_table_$end_of_info the next record position is at end of file. error_table_$no_record the next record position is null. :Entry: read_length: 01/24/84 iox_$read_length Function: returns the length of the next record in a structured file attached to an I/O switch. The switch must be opened in one of the following modes: sequential_input sequential_input_output sequential_update keyed_sequential_input keyed_sequential_update direct_input direct_update The next record position is unchanged and the current record position is set to the next record if the operation is successful; otherwise, the current record position is set to null. Syntax: declare iox_$read_length entry (ptr, fixed bin(21), fixed bin(35)); call iox_$read_length (iocb_ptr, rec_len, code); Arguments: iocb_ptr is a pointer to the control block. (Input) rec_len is the next record's length in bytes. (Output) code is an I/O system status code. (Output) error_table_$end_of_info the next record position is at end of file. error_table_$no_record the next record position is null. :Entry: read_record: 01/24/84 iox_$read_record Function: reads the next record in a structured file to which an I/O switch is attached. The switch must be opened in one of the following modes: sequential_input sequential_input_output sequential_update keyed_sequential_input keyed_sequential_update direct_input direct_update The read is successful if the next record position is at a record. In sequential and keyed_sequential openings, a successful read advances the next record position by one record; an unsuccessful read leaves it at the end of file or null. In direct openings, this operation always sets the next record position to null. In openings for update, a successful read sets the current record position to the record just read; an unsuccessful read sets it to null. In openings for keyed_sequential_update and direct_update, the key for insertion is always set to null. Syntax: declare iox_$read_record entry (ptr, ptr, fixed bin(21), fixed bin(21), fixed bin(35)); call iox_$read_record (iocb_ptr, buff_ptr, buff_len, rec_len, code); Arguments: iocb_ptr is a pointer to the control block. (Input) buff_ptr points to a byte-aligned buffer into which the record is to be read. (Input) buff_len is the length of the buffer in bytes. (Input) rec_len is the length of the record in bytes. (Output) code is an I/O system status code. (Output) error_table_$end_of_info the next record position is at end of file. error_table_$no_record the next record position is null. error_table_$long_record the record is too long for the specified buffer. The first part of the record is read into the buffer, and as far as setting position indicators is concerned, this is considered a successful read. In all cases, the contents of the buffer beyond the last byte read are undefined. :Entry: rewrite_record: 01/24/84 iox_$rewrite_record Function: replaces the current record in a structured file to which an I/O switch is attached. The switch must be open for sequential_update, keyed_sequential_update, or direct_update. For keyed_sequential_update and sequential_update, this operation sets the next record position to the record immediately following the current record or to end of file (if no such record exists). (It is possible that the next record position may already be at this point). For direct_update, the next record position is set to null. No other changes are made to the position designators. Syntax: declare iox_$rewrite_record entry (ptr, ptr, fixed bin(21), fixed bin(35)); call iox_$rewrite_record (iocb_ptr, buff_ptr, rec_len, code); Arguments: iocb_ptr is a pointer to the control block. (Input) buff_ptr points to a byte-aligned buffer containing the new record. (Input) rec_len is the length of the new record. (Input) code is an I/O system status code. (Output) error_table_$no_record the current record position is null. :Entry: seek_key: 01/24/84 iox_$seek_key Function: searches for a record with a given key in an indexed file to which an I/O switch is attached. It also serves to define the key for a record to be added by a following write_record operation. The switch must be opened in one of the following modes: keyed_sequential_input keyed_sequential_output keyed_sequential_update direct_input direct_output direct_update Syntax: declare iox_$seek_key entry (ptr, char(256) varying, fixed bin(21), fixed bin(35)); call iox_$seek_key (iocb_ptr, key, rec_len, code); Arguments: iocb_ptr is a pointer to the control block. (Input) key contains the given key. (Input) All trailing blanks are removed from key to obtain the given key, and the result may be the null string. rec_len is the length in bytes of the record with the given key. (Output) code is an I/O system status code. (Output) (See "Notes" below.) Notes: For keyed_sequential_output, the given key should be greater (according to the rules for character-string comparison) than the key of the last record in the file. If it is, the code error_table_$no_record is returned, and the key for insertion is set to the given key. Otherwise, the code error_table_$key_order is returned, and the key for insertion is set to null. For other openings, this entry point performs as follows. 1. If the file contains a record with the given key, a code of 0 is returned, the record's length is returned, the next record position and current record position are set to the record, and the key for insertion is set to null. (Not all of these position designators are applicable in all openings.) 2. If the file does not contain a record with the given key, the code error_table_$no_record is returned, the next record position and current record position are set to null, and the key for insertion is set to the given key. (Not all of these position designators are applicable in all openings.) :Entry: write_record: 01/24/84 iox_$write_record Function: adds a record to a structured file to which an I/O switch is attached. The switch must be opened in one of the following modes: sequential_output sequential_update sequential_input_output keyed_sequential_output keyed_sequential_update direct_output direct_update Syntax: declare iox_$write_record entry (ptr, ptr, fixed bin(21), fixed bin(35)); call iox_$write_record (iocb_ptr, buff_ptr, rec_len, code); Arguments: iocb_ptr is a pointer to the control block. (Input) buff_ptr points to a byte-aligned buffer containing the new record. (Input) rec_len is the length of the new record in bytes. (Input) code is an I/O system status code. (Output) Notes: If the switch is open for sequential_output, the record is added at the end of the file. If the switch is open for sequential_input_output, and the next record position is not at the end of the file, the file is truncated so that the record preceding the next record becomes the last record in the file. The new record is then added at the end of the file. Truncation can be suppressed in sequential_input_output, and write operations can be performed in sequential_update openings of storage system files. See the description of the vfile_ I/O module for details. If the switch is open for keyed_sequential_output, keyed_sequential_update, direct_output, or direct_update, the key for insertion designator should designate a key. If it does not, the code error_table_$no_key is returned and nothing is changed. If there is a key for insertion, the new record is added to the file with that key and the key for insertion is set to null. For keyed_sequential_update, and sequential_update, the next record position is set to the record immediately following the new record or to end of file (if there is no such record). For keyed_sequential_update, sequential_update, and direct_update, the current record position is set to the new record. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved