Contents

1 Introduction

Programming languages designed with a concise defining document as one of the principal design goals usually leave the design and implementation of a collection of procedures for input and output of text and numbers to the user. Occam is such a language. However it is sensible for an implementer to help the users by providing a basis on which they can build.

Accordingly, procedures for input and output have now been included in the software shipped as part of the transputer development system (TDS). The purpose of this note is to introduce these procedures and to explain some of the guiding principles which have gone into their design and implementation. The fact that users will have requirements not exactly met by these procedures is acknowledged and the occam source of the procedures is provided as a basis for enhancement where this is seen to be necessary.

Occam is defined in a reference manual [1]. The TDS is introduced in another technical note in this series [2]. Reference is also made below to INMOS product documentation for readers who have access to the product. Some details in this note apply particularly to the version of the TDS sold as IMS D700D, but as far as possible similar facilities are available in other versions of the TDS.

Many of the procedures would be suitable for use with any implementation of occam. However this note is particularly concerned with procedures designed to be used in programs developed and tested within the TDS itself. Such programs, when written using these procedures, may easily be converted to run on arbitrary transputer hardware configurations.

1.1 Input and output

In occam the terms input and output strictly apply to the low level communications between processes executing in parallel. These communications use occam channels, which may or may not correspond to physical hardware links, and are made up of bit streams organised as sequences of bytes corresponding to values represented in the occam type system.

In general usage the terms input and output apply more loosely to the transmission of values (text and/or binary numbers) between a program and its physical peripherals such as keyboards, screens, printers, or disks and other mass storage systems, usually abstracted by an operating system as a filing system.

Occam permits the abstraction of peripheral devices, possibly with their low level driving software, as processes connected to their environment by channels. This view enables the two levels of input/output to be merged.

Input procedures receive their input data along a channel, whose identity is passed to the procedure as a parameter. The values received are passed to the caller by means of element parameters (parameters whose specification permits their values to be changed).

Output procedures send their output data along a channel, whose identity is passed to the procedure as a parameter. The data are passed to the procedure for output as value parameters.

1.2 Packaging of the procedures

Pre-written procedures can be provided in various ways:

1. Predefined by the compiler and converted directly to in-line code
2. Predefined by the compiler and compiled into calls to the system library
3. Provided in a user library
4. Provided as separately compilable unit(s)
5. Provided as source code possibly including free variable references.

The input and output procedures supplied with the TDS are packaged in a group of user libraries, some of which use other libraries and also the predefined procedures provided by the compiler. The allocation of procedures to libraries is indicated in section 5.

Because of limitations with the library mechanism the names of all procedures used in a program from user and system libraries must be unique.

Alt the procedures in the input/output library are provided both precompiled and as source. If the user’s requirements can be met by calling the recompiled procedures, then that is the preferred way to use them. However it is accepted that some users will have particular requirements which may best be met by adapting the procedures to meet these requirements.

1.3 Structure of this note

This note is structured as five main sections.

Section 1 is this introduction.

Section 2 discusses conventions for the use of channels in occam programs, with particular reference to the channels defined by the TDS itself.

Section 3 discusses the procedures provided with the TDS for calling in sequence in arbitrary occam programs. These procedures include some which are applicable in any occam program, some which assume sequential text-oriented devices, and some which are only meaningful in the presence of a folded file store as provided by the TDS. These procedures are collectively called the user procedures. An example using these procedures is included.

Section 4 discusses the procedures provided with the TDS for calling in parallel with applications using the user procedures. These enable programs to be easily adapted to support different implementations of sequential text files, including those found in conventional host text files and in the TDS folded file store. These procedures are called the interface procedures. An example of the use of these procedures is given.

Section 5, subdivided for the user procedures and the interface procedures, lists all the procedures and gives a brief statement of the function of each. The structure of these lists is related to the packaging of the procedures in library files.

2 Conventions for the use of channels

It is desirable to be able to use the same input procedures for receiving sequences of characters from channels whose other end may be any kind of character source (keyboard, file, process) and to use the same output procedures for sending characters out along channels whose other end may be any kind of character sink (screen, printer, file, process). To achieve this it is necessary to adopt a set of rules and conventions which determine the representation of information sent along the channels.

The simplest communication paths are those where only the sender has control and the receiver must be prepared to receive everything sent, up to and including an agreed terminator. Input from a keyboard and output to a screen or printer can usually be handled satisfactorily in this way, and require a single occam channel from the sender to the receiver.

There are, however, situations where the receiving process needs to be able to control what the sender is sending. The simplest example is when the receiver wishes to tell the sender to stop sending; more complex cases arise when the receiver can influence which alternative the sender selects out of an available set of alternatives. These situations require a pair of occam channels, one in each direction. The sender sends data and control information and receives commands and possibly error indications. The receiver receives data and control information and sends commands and error indications. If a pair of processes is connected by a pair of channels then the identity of the sender and receiver could change from one to the other during the execution of the program.

The channel usage conventions adopted in the input and output procedures provided with the TDS are determined by the TDS itself. They are the conventions used by the keyboard, screen and user.filer channels which are passed by the TDS to an executable program (EXE) running in the TDS. EXEs are discussed further in [2].

They are, however, not restricted to use on these particular channels, and interface procedures are provided to perform such tasks as receiving input from a file as if from a keyboard, sending output to a file as if to a screen, merging screen streams, duplicating screen streams, etc.

2.1 Key stream conventions

A stream of characters deriving from a keyboard must be capable of being received by a receiver who never has any knowledge of what is coming. As arbitrary byte values may be possible the protocol is defined to be INT with non-negative values being valid data values, and negative values indicating control and error conditions. A particular negative value ft.terminated is used as a general terminator on a key stream. The range of possible positive values is determined by the hardware or software generating them, but will normally include at least the full ASCII character set.

A key stream channel may be used for any simple one way communication of a sequence of positive integers.

Some procedures take note of the control characters ’*c’ and ’*n’ (ASCII CR and LF), the normal rule being that the former is the line terminator, and the latter is ignored. The input procedures themselves have no knowledge of the more advanced features of the TDS keyboard interface, such as the encoding of function keys (or key sequences) as integers >= 200.

2.2 Screen stream conventions

The TDS screen interface is based on the requirements of programs such as editors and the problems deriving from the incompatible control features provided by different terminal types. The screen channel protocol is a tagged protocol, but for historical reasons cannot be described as such in the occam language (its invention was before the language was fully defined). Each communication consists of a one byte tag followed, according to the tag, by zero, one or more specific communications of bytes, integers or byte arrays.

For the purpose of the output procedures the significant feature of this protocol is its ability to package strings or lines of text into single communications. In some situations this will give a performance advantage over sending each character individually.

A special tag tt.endstream is defined to act as a stream terminator.

A screen stream channel may be used for any one-way communication of text, with the option to include screen control commands, if the ultimate destination has the ability to process them.

As the TDS screen requires lines of text to be separated by "*c*n" it is the convention that both of these control characters must be sent at the end of each line.

2.3 User filer channel conventions

The uses filer is a process in the TDS which provides an EXE with a means of communicating with a part of the folded file structure identified by the current cursor position at the time the EXE is called. Access to the user filer requires a pair of channels with a versatile tagged protocol permitting fully flexible access to hierarchically structured data in the TDS folded file store.

This protocol is discussed in full in the ’System interfaces’ chapter in [3].

2.4 The other channels between the TDS and an EXE

An EXE has access to a set of implicit parameters provided to it by the TDS when it is called. These include a variety of channels between the TDS and the code of the EXE. These parameters are recognised by the compiler by their names. For further details see [2] and [3].

Channels to the terminal and user filer have been mentioned. The other channels between an EXE and the TDS are provided for special purposes. One pair of these channels needs to be mentioned here. This is the channel pair to and from the TDS server which may be used to perform accesses direct to the host filing system. Some procedures are provided which use these channels and further details are given in [3].

3 User procedures - to be called in sequence

3.1 An introductory example

An example, simplified from [3], shows some of the simple input and output procedures being used to read and write numbers and text. These procedures are called in sequence with the rest of the computation in the same way as the input and output procedures of other programming languages.

The general style of the simple input and output procedures may be observed in the example. The first parameter of the procedure identifies the channel for communication. Subsequent parameters define the value to be communicated or the variable to receive the communication.

3.2 Number conversion procedures

A set of number conversion procedures as defined in [1] is provided. These procedures perform conversions between arrays of bytes (containing ASCII characters) and integer and real numbers in all the occam types. Integer numbers may be represented either in decimal or in hexadecimal notation. Real numbers may be either in fixed point representation or in floating point with a signed decimal exponent.

For completeness, procedures for boolean type are also provided.

The input conversion procedures each have three parameters: a boolean error flag (set if a legal conversion cannot be performed) the result and the string to be converted.

The output conversion procedures each have three or more parameters: an integer returned as the number of characters generated an array into which the characters are stored, the value to be converted and, when necessary, integers to define the format.

These procedures may be considered to be defined as part of the occam language, as they are totally independent of any channels provided by a particular run-time environment.

3.3 Simple input procedures

Two alternative groups of input procedures are provided. The first group reads strings from an input channel with BYTE protocol, using either a space or ’ *c’ as terminator. The second group uses a TDS key stream input channel and is suitable for reading arbitrary text with embedded numbers. This group includes variants of the procedures for use when input is from an interactive keyboard to which the input characters must be echoed and at which simple line editing (character delete) operations can be supported.

The style of coding for which the TDS input procedures has been designed is sequential reading of single characters, switching to an appropriate number input procedure when a digit or other significant character is encountered. All number input procedures have an integer parameter which is the value of this ’read ahead’ character on input, and is the value of the character which terminated the number on exit.

3.4 Simple output procedures

The simple output procedures generate a TDS screen stream on their output channel. This channel can be connected either directly to the screen channel of an EXE or to the input of any process designed to accept such a stream. These processes may provide a route to a screen, a printer, a file or any other process which expects a sequence of textual input.

Two modes of working are supported: the first enables individual values to be converted into a sequence of characters which is immediately sent to the channel; the second allows lines of text to be accumulated in a buffer array before being sent to the output in a single operation.

A program using these procedures may be trivially converted to a different run-time environment, either by use of interface procedures as discussed below, or by recoding the procedure bodies to use the conventions of the new run-time environment.

Procedures for terminal-type dependent operations such as cursor control are also provided but are meaningful only when the receiving software can generate the character sequences appropriate for the type of terminal in use.

3.5 User filer procedures

This and the following sub-section assume knowledge of the TDS, and in particular its concept of a folded file store.

In order to give EXEs running in the TDS flexible access to the folded file structure the TDS includes a process called the user filer, which may be connected to an EXE by one or more pairs of channels obeying a bidirectional protocol. This protocol is defined in terms of command tags and their parameters, and corresponding reply tags and their parameters. Meaningful sequences of these communications are also specified in the TDS reference manual [3].

Procedures are provided which embody most of the frequently used communications across the user filer interface.

In particular, sets of procedures are provided which support sequential access to folded data streams, both for input and for output. These treat such streams as sequences of items, each item corresponding to a line on the screen in the editor’s representation of the stream. There are therefore procedures corresponding to the input and output of top and bottom creases (filed and ordinary), record items and number items.

There are two groups of folded input procedures. The first group is designed for an exhaustive sequential pass through a folded input stream and returns the data of the current item and the tag defining the type of the following item. The second group splits these two components and so gives the user the option to decide to skip folds, or to repeat or prematurely exit from a fold.

3.6 Other procedures

The other procedures provided include:

1. string handling procedures and functions
2. procedures supporting the channels in an EXE which provide direct access to host files,
3. procedures supporting the alien filer interface protocol for programs running under the host file server,
4. procedures supporting access to peripherals of transputer evaluation boards.

4 Interface procedures - to be called in parallel

It is often desirable, when writing programs to read or write sequential text streams, to design the program to be independent of whether the input sources and output destinations are peripheral devices, files or processes. For this purpose a set of interface procedures is provided.

Calls, or instances, of one or more of these procedures are then suitable as processes to be run in parallel with an application process to obtain the effect required. The same application code (written as a separately compilable procedure) may be called in parallel with different combinations of interface procedures to take inputs from or direct outputs to a variety of sources and sinks.

The interface procedures are designed for use in programs which process streams of text to exhaustion. Input from a file or output to a file may require a pair of channels, but otherwise connections require a single channel each.

When building these procedures into a program it is important to ensure that every interface procedure will terminate. Interface procedures with a single input channel are terminated by sending a terminator on that channel. Multiplexors have a special stopper channel.

4.1 Protocol converters

Interface procedures are provided for reading key streams from host files and from TDS folded files in data mode (ignoring non-text folds and all the creases), and for writing screen streams to files of both these types.

Procedures are also provided for simple copying (buffering) of screen streams, for converting screen streams to simple byte streams for commonly used screen types, for converting from key stream to screen stream protocol, and for saving a screen stream in an array and subsequently regenerating it.

4.2 Multiplexors, etc.

Some of the interface procedures do not change the protocol but merely serve to join together various components of a program. Such procedures have different numbers of input and of output channels.

The screen multiplexor takes any number of input channels and merges screen stream protocol messages on these to a single output channel. For practical purposes it is probably desirable for the merged streams to be organised as sequences of complete lines of text, but the multiplexor does not enforce this mode of use.

The screen fan out procedure makes two copies of a screen stream input. It can therefore be used, for example, to file a copy of what is sent to the screen.

Key stream and screen stream sink procedures are provided for consuming streams which are no longer wanted, such as diagnostic output.

Examples of the use of interface procedures are given in [3].

4.3 An example calling interface procedures in parallel

This example shows the output from an application (arbitrarily called big.numbers) being duplicated by a call of scrstream.fan.out, and then one of these outputs being sent to a file.

The process structure of this program may be represented by the diagram below. In this diagram channels with different protocols are represented by lines drawn in different styles.

5 Table of procedures in the D700D libraries

Each of the library files provided in the IMS 07000 software package contains one or more separately compiled groups of procedures. Within the description of a library the groups of procedures are indicated. The occam compilation system permits only those groups of procedures which are required in a program to be included in the object code generated.

There are some interdependencies between the various libraries themselves. Programmers only need to mention those libraries they use explicitly. The majority of programs will only use procedures from the library userio and any necessary interface procedures.

The description here is purposely brief, as it is intended that serious users should study the detailed documentation [3], or the occam source of the procedures themselves. Note that libraries are named according to the host file in which they are found.

5.1 User procedures

Library ioconv - number/string conversions

These procedures for simple number to string conversions (and vice versa) are defined in [1]. They are used by the simple input output procedures in userio.

Library extrio - more number/string conversions

These extend the previous group for the extra integer and real types.

Library strings - string handling procedures and functions

Character manipulation

String handling

Appending text and numbers to text lines. These procedures allow the cumulation of text into a line buffer.

Library userio - user input and output procedures

Simple input procedures
These procedures support input from a key stream, with and without echo.

Simple output procedures
These procedures support output to a screen stream.

Procedures for the extra types
These procedures support input and output of values in the extended types. This group is incomplete and can be extended by the user if necessary.

Control codes to a screen stream

Folded stream output
These procedures support straightforward output to the folded file store of the TDS.

Folded stream input
These procedures support input from the folded file store of the TDS. The read. procedures read ahead the tag of the following item, the input. procedures do not.

Library slice - block transfer procedures

These procedures may be used for communicating blocks of bytes.

Library ufiler - user filer procedures

This group of procedures supports the user filer interface at a more intimate level than the folded stream procedures in userio.

Library msdos - DOS file via TDS server procedures

These procedures are used by the interface procedures which provide access to host files outside the TDS folded file store.

Library derivio - derived number inputs

These procedures are also described in [3] and support simple input and output using channels with BYTE protocol.

Library afiler - alien filer procedures

These correspond exactly to the operations with the same names described in the section on the ’Host file server’ in [3]. They are provided so that occam programs may do all the host operations available to the scientific languages.

5.2 Interface procedures

These procedures are listed separately solely to match the structure of the main part of this note. They are organised in groups in a similar manner to the user procedures.

Instances of these procedures are suitable for calling in parallel with application code using the user procedures listed above. Each procedure has channel parameters which must be ’joined’ to others using a matching protocol.

Library interf - interface procedures

These procedures handle the standard TDS protocols used by the procedures in userio.

Terminal to file protocol converters

These procedures allow files accessed sequentially to be treated in the same way as terminals.

Multiplexors, stream sinks, etc.

These procedures split and join screen streams and act as dummies to consume streams which are no longer wanted.

Library afinterf - alien filer interface procedures

Library t4board, t2board - transputer board procedures

These procedures support terminal access on INMOS evaluation boards.

References