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.
