HELP IO                                   Andrew Law, April, 1987

    This help file describes files relating to POPLOG's input/output
behaviour.

CONTENTS - (Use <ENTER> g to access required sections)

 -- General
 -- Input
 -- (From the terminal)
 -- (From storage devices)
 -- (From VED)
 -- Output
 -- (To VED)
 -- (To a terminal)
 -- (To storage devices)
 -- (Printing)
 -- Information about devices, changing devices
 -- Input from and output to sub-process (via pipes)
 -- Reading input from proglist
 -- Itemisation of text, item repeaters/consumers
 -- Formatting output
 -- Time outs
 -- Error output
 -- Trace output

See also the I/O sections in
HELP *POP, PLOGHELP *HELPFILES, HELP *HELPFILES (from LISP)

-- General ------------------------------------------------------------

HELP *ASCII
    ASCII codes
REF  *CHARIO
    For a description of character stream input/output
REF  *SYSIO
    Information on device input/output procedures
REF *PRINT
    Information on printing
HELP *COMPILE
    Brief summary of COMPILE procedure
HELP *INCHARITEM
    Converts character repeater procedure into item repeater

-- Input --------------------------------------------------------------

General

HELP *INPUT
HELP *OUTPUT
HELP *TERMIN
    Special object used by character and item repeaters to indicate the
    end of a stream.

-- (From the terminal) ------------------------------------------------

HELP *CHARIN, *RAWCHARIN
    Reading in characters from VED
HELP *READLINE, *REQUESTLINE, *GETLINE, *LISTREAD
    Reading in individual lines of text typed at the terminal

See also section on VED

-- (From storage devices) ---------------------------------------------

HELP *DISCIN
    Creating a character repeater for a file or device
HELP *BITS_IN
    Returns an "integer repeater" linked to a file. Successive calls
    read N-bit integers from the file.

-- (From VED) ---------------------------------------------------------

REF *VEDSCR_READ_INPUT, *VEDSCR_READ_ASCII, *VEDSCR_INPUT_WAITING,
    *VEDSCR_CLEAR_INPUT
    Low level VED input procedures
HELP *VEDINASCII *VEDGETINPUT
    Character repeaters used by VED
HELP *VEDINPUT
    Adding characters to VED's input stream
HELP *READLINE, *REQUESTLINE, *GETLINE, *LISTREAD
    Reading in individual lines of text typed at the terminal

-- Output -------------------------------------------------------------

HELP *OUTPUT
HELP *PIPEUTILS
    Describes a collection of utilities for spawning a Unix sub-process
    and reading the output back via a pip.

-- (To VED) -----------------------------------------------------------

REF *VED_CHAR_OUT, *VEDSCR_SUBSTRING_OUT, *VEDSCR_FLUSH_OUTPUT
    Low level VED output procedures.

-- (To a terminal) ----------------------------------------------------

HELP *CHAROUT
    Outputs a character to the terminal
HELP *CUCHAROUT
    The character consumer currently in use
HELP *RAWCHAROUT
    Sending characters to the terminal via a buffer
HELP *RAWOUTFLUSH
    Flushing the RAWCHAROUT buffer
HELP *CHARERR
    Character repeater used by error printing routines (see *PROGRAMMING
    on error handling)
HELP *POPLINEMAX
    Determines the column at which printing through CHAROUT should break
    the line. User assignable, default is 78
HELP *POPLINEWIDTH
    Determines which is the column after which attempting to print a
    space will cause a line break. User assignable, the default is 70

-- (To storage devices) -----------------------------------------------

HELP *DISCOUT
    Creates a character consumer for a file or device
HELP *DISCAPPEND
    Opening files for updating
HELP *DATAFILE
    Recording data structures on disk and read back
HELP *BITS_OUT
    Returns an "integer consumer" linked to file. Successive calls
    write N-bit integers to the file.

-- (Printing) ---------------------------------------------------------

REF *PRINT
    Details of printing in POP-11
HELP *PRINT
    For a list of files on printing procedures
HELP *PRINTARROW
    Printing results from stack
HELP *SYSPR
    The standard procedure which prints its argument
HELP *SYS_SYSPR
    Prints all data classes in standard format
HELP *PR
    Variable for holding a printing procedure (user assignable)
HELP *POPPRINT
    Printing lists containing POP-11 programs to be compiled
HELP *SP
    Printing spaces
HELP *TABS
    Printing tabs
HELP *PRINTF, *SPRINTF
    Formatted printing
HELP *PRINTLENGTH
    Returns the number of characters that would be printed by a call of PR
HELP *SPR, *PPR, *NPR
    Printing an item followed by a space/newline
HELP *PRMISHAP
    Mishap message printer (user-assignable)

Hard copies:

TEACH *PRINTING, HELP *PRINTING
    General tutorial introduction
HELP *VED_PRINT
    Printing a file from VED

-- Information about devices, changing devices ------------------------

REF  *SYSIO
    For information on device input/output procedures
HELP *DEVICE
    On I/O device descriptors in POP-11
HELP *DEVNAME
    Returns the name of the file for which a device was created
HELP *DISCOUT
    Creates a character consumer for a file or device
HELP *DISCIN
    Creates a character repeater  for a file or device
HELP *ISCLOSED
    Returns TRUE if specified device is closed
HELP *ISDEVICE
    Finding out whether an object is a device record
HELP *POPDEVRAW
    Returns the device for 'raw' input or output from the terminal.
    (read from by *RAWCHARIN, and written to by *RAWCHAROUT)
HELP *POPDEVIN
    Returns the device for the standard input channel (has an updater)
HELP *POPDEVOUT
    Returns the device for the standard output channel (has an updater)
HELP *SYSTRMDEV
    Test whether a device record refers to a terminal
HELP *SYSREAD
    Reading from a specified device
HELP *SYS_INPUT_WAITING
    Returns an integer count of the number of input characters
    currently available to be read on a given device.
HELP *DEVICE_OPEN_NAME
    Returns the name of a file for which device was created
HELP *POPDEVERR
    Returns the device for the standard error channel (written to by
    *CHARERR).

-- Input from and output to sub-process (via pipes) -------------------

The following are available only on Unix versions of Poplog

HELP * PIPEUTILS
    Reading in output from a sub-process, including various utilities
    based on this.

See also REF * SYSIO, * SYSUTIL

-- Reading input from proglist ----------------------------------------

HELP *COMPILE
    Brief summary of COMPILE procedure
HELP *PROGLIST, REF *PROGLIST
    A dynamic list from which the compiler reads
HELP *NEXTITEM, *READITEM, *ITEMREAD
    Reading in items from PROGLIST
HELP *READLINE, *REQUESTLINE, *GETLINE, *LISTREAD
    Reading in items (including lines, lists, providing prompts) from
    PROGLIST
HELP *READTILL
    Reading in items from PROGLIST, leaving them on the stack, until a
    specified item is found. Returns the terminating item.
HELP *POPLASTITEM
    The variable holding  the last item which was read from PROGLIST
HELP *CUCHARIN
    The character repeater currently being used by compile

-- Itemisation of text, item repeaters/consumers ----------------------

This section concerns how to break up a stream of characters into a
stream of text items.

REF *ITEMISE
    Details of itemisation of input in POPLOG
HELP *INCHARITEM
    Conversion of  character repeater procedure into item repeater
HELP *OUTCHARITEM
    Conversion of a character consumer procedure into a item consumer
HELP *ITEMREAD, *READITEM,
    Reading in individual items from the input stream
HELP *READLINE, *REQUESTLINE, *GETLINE, *LISTREAD
    Reading in individual lines of text typed at the terminal
HELP *TERMIN
    Special object used by character and item repeaters to indicate the
    end of a stream.
HELP *POPNEWLINE
    Itemiser flag determining whether newlines read in are not ignored

-- Formatting output --------------------------------------------------

HELP *FORMAT, * FORMAT_PRINT

-- Time outs ----------------------------------------------------------

HELP *POP_TIMEOUT, *CHARIN_TIMEOUT, *SYSSETTIMER

-- Error output -------------------------------------------------------

See also *PROGRAMMING

HELP *CHARERR
    Procedure used by the error-printing routine *SYSPRMISHAP to print
    characters at the terminal.
HELP *PRMISHAP
    Called by *MISHAP to print mishap message. User-assignable, default
    is *SYSPRMISHAP
HELP *CUCHARERR
    The standard error output (character consumer), a variable whose
    default is CHARERR.  Used by -sysprmessage- etc
HELP *POPDEVERR
    Procedure which returns the device for the standard error channel
    (written to by *CHARERR).

-- Trace output -------------------------------------------------------
HELP * TRACE


--- C.all/help/io ------------------------------------------------------
--- Copyright University of Sussex 1987. All rights reserved. ----------
