MUMPS IO Documentation

   Copyright (c) 1999, 2000, 2001, 2002, 2003
        Raymond Douglas Newman.  All rights reserved.
  
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:
  
   1. Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
   2. Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
   3. Neither the name of Raymond Douglas Newman nor the names of the
      contributors may be used to endorse or promote products derived from
      this software without specific prior written permission.
  
   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS"
   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
   THE POSSIBILITY OF SUCH DAMAGE.

Introduction

MUMPS IO may be performed to the following classes:

Devices
Files
Network
Pipes

The MUMPS commands that are used to do IO are:

OPEN
USE
WRITE
READ
CLOSE

How to use these commands with each class is discussed below.

Devices

The Device class includes such things as the console, serial lines (terminals or printers), parallel ports (printers) and pseudo terminals (xterms).
Standard in (stdin) or MUMPS channel 0 (zero) is usually of class Device.

OPEN for Devices

NOTE: OPEN may not be used with MUMPS channel 0.

The OPEN command is of the form:

OPEN channel:(device:mode)[:timeout[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive.
device is the full device specification - like /dev/cuaa0.
mode is one of:
IO - open the device for both Reading and Writing
READ - open the device for Reading only
WRITE - open the device for Writing only
timeout is the optional time in seconds to wait for the device.
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

For example: OPEN 1:("/dev/lpt0":"W") ;Open the printer for writing

USE for Devices

The USE command is of the form:

USE channel[:parameters[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive. parameters are zero or more of the following. If more than one parameter is supplied, they must be enclosed in parenthesis () and separated with colons.
TERMINATOR=$C(n,...) Specify the input terminators. All input terminators must be in the range of ASCII 0 to ACSII 31. The special case of $C(13,10) requires both characters to be in the input stream to terminate input. The terminating character(s) is/are returned in the special variable $KEY.
The default input terminator for this class is $C(13).

OUTPUT=$C(n,...) Specify the output terminators to output when WRITE ! is executed. This may be up to 6 (six) characters.
The default output terminators for this class are $C(13,10).

[NO]CONTROLC Enable/Disable interuption of a running process.
NOTE: This applies to stdin only and defaults to CONTROLC.

[NO]CONTROLT Enable/Disable mimi process status.
NOTE: This applies to stdin only and defaults to CONTROLT.

[NO]ESCAPE Enable/Disable escape sequence processing. When enabled, escape sequences are returned in the variable $KEY.
The default for this class is ESCAPE.

[NO]ECHO Enable/Disable character echo.
The default for this class is ECHO.

DELETE= Define the character delete key as NONE, BACK $C(8), DELETE $C(127) or BOTH $C(8) and $C(127).
The default for this class is DELETE=DELETE.
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

WRITE for Devices

The WRITE command is of the form:

WRITE comma separated list of writearguments

where writearguments are:

# output terminator, page feed combination
! carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
expression - output any valid MUMPS expression
*intexpr - output the ASCII character intexpr#256

READ for Devices

The READ command is of the form:

READ comma separated list of readarguments

where readarguments are:

# output terminator, page feed combination
! output carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
variable[#count][:timeout] - input data to a maximum length of [#count] into a MUMPS variable.
*variable[:timeout] - input one ASCII character as an integer (0 to 255)

If :timeout is specified and is zero or a positive number, the system will wait that many seconds for data to become available. Should the read be a *variable and a single character is received or should the [#count] be reached or a terminator be received, then $TEST is set to 1. Else $TEST is set to zero.
If the form READ "literal",VAR is used, all typeahead is canceled before the read is done.

CLOSE for Devices

The CLOSE command is of the form:

CLOSE channel

Note: Closing channel 0 is ignored.

Files

The File class includes text files (binary or ASCII).
Standard in (stdin) or MUMPS channel 0 (zero) can be of class File.

OPEN for Files

NOTE: OPEN may not be used with MUMPS channel 0.

The OPEN command is of the form:

OPEN channel:(file:mode)[:timeout[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive.
file is the full file specification - like /home/me/myfile.
mode is one of:
APPEND - open the file for Writing and append to the end of the file
READ - open the file for Reading only
WRITE - open the file for Writing only and delete the current file
timeout doesn't do anything for a file
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

For example: OPEN 1:("/home/me/myfile":"W") ;Open myfile for writing

USE for Files

The USE command is of the form:

USE channel[:parameters[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive. parameters are zero or more of the following. If more than one parameter is supplied, they must be enclosed in parenthesis () and separated with colons.
TERMINATOR=$C(n,...) Specify the input terminators. All input terminators must be in the range of ASCII 0 to ACSII 31. The special case of $C(13,10) requires both characters to be in the input stream to terminate input. This is typically used for reading files created on DOS. The terminating character(s) is/are returned in the special variable $KEY.
The default input terminator for this class is $C(10).

OUTPUT=$C(n,...) Specify the output terminators to output when WRITE ! is executed. This may be up to 6 (six) characters.
The default output terminator for this class is $C(10).
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

WRITE for Files

The WRITE command is of the form:

WRITE comma separated list of writearguments

where writearguments are:

# output terminator, page feed combination
! carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
expression - output any valid MUMPS expression
*intexpr - output the ASCII character intexpr#256

READ for Files

The READ command is of the form:

READ comma separated list of readarguments

where readarguments are:

# output terminator, page feed combination
! output carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
variable[#count] - input data to a maximum length of [#count] into a MUMPS variable.
*variable - input one ASCII character as an integer (0 to 255)

CLOSE for Files

The CLOSE command is of the form:

CLOSE channel

Note: Closing channel 0 is ignored.
A file may be deleted by opening it for WRITE then closing it. For example:

OPEN 1:("file":"W") ;Open file to be deleted
CLOSE 1 ;Delete it

Network

The Network class includes tcp socket connections (Server or Client).
Standard in (stdin) or MUMPS channel 0 (zero) can be of class Network.

OPEN for Network

NOTE: OPEN may not be used with MUMPS channel 0.

The OPEN command is of the form:

OPEN channel:(port/address:mode)[:timeout[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive.
port/address is the port to be opened (Server) or the ip address space port (Client).
mode is one of:
TCPIP - open the specified ip address/port combination (Client connection)
SERVER[=n] - open the specified port in Server mode. When =n is specified fork each connection up to a maximum of n simultaneous jobs.
timeout specifies the time to wait for the connection to become available (Client) or to wait for a client to connect (Server).
An error will occur when a non-existant address is assessed after a specific time. Both the error and the time are O/S specific as follows:
	                        linux           FreeBSD
	Timeout (secs)              3                60
	Error                    Z313              Z260
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

For example: OPEN 1:("80":"S=5") ;Open http port as server

USE for Network

The USE command is of the form:

USE channel[:parameters[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive. parameters are zero or more of the following. If more than one parameter is supplied, they must be enclosed in parenthesis () and separated with colons.
TERMINATOR=$C(n,...) Specify the input terminators. All input terminators must be in the range of ASCII 0 to ACSII 31. The special case of $C(13,10) requires both characters to be in the input stream to terminate input. This is typically used for reading files created on DOS. The terminating character(s) is/are returned in the special variable $KEY.
The default input terminator for this class is $C(13).

OUTPUT=$C(n,...) Specify the output terminators to output when WRITE ! is executed. This may be up to 6 (six) characters.
The default output terminator for this class is $C(13).
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

WRITE for Network

The WRITE command is of the form:

WRITE comma separated list of writearguments

where writearguments are:

# output terminator, page feed combination
! carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
expression - output any valid MUMPS expression
*intexpr - output the ASCII character intexpr#256

READ for Network

The READ command is of the form:

READ comma separated list of readarguments

where readarguments are:

# output terminator, page feed combination
! output carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
variable[#count] - input data to a maximum length of [#count] into a MUMPS variable.
*variable - input one ASCII character as an integer (0 to 255)

CLOSE for Network

The CLOSE command is of the form:

CLOSE channel

Note: Closing channel 0 is ignored.

Pipes

The Pipes class includes named unix pipes

OPEN for Pipes

The OPEN command is of the form:

OPEN channel:(pipe:mode)[:timeout[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive.
pipe is the full pipe specification - like /home/me/mypipe.
mode is one of:
NEWPIPE - open a new named pipe for reading.
PIPE - open an existing named pipe for writing.
timeout doesn't do anything for a pipe
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

For example: OPEN 1:("/home/me/mypipe":"N") ;Open mypipe for reading

USE for Pipes

The USE command is of the form:

USE channel[:parameters[:namespace]]

where:

channel is the MUMPS channel number from 1 to 15 inclusive. parameters are zero or more of the following. If more than one parameter is supplied, they must be enclosed in parenthesis () and separated with colons.
TERMINATOR=$C(n,...) Specify the input terminators. All input terminators must be in the range of ASCII 0 to ACSII 31. The special case of $C(13,10) requires both characters to be in the input stream to terminate input. This is typically used for reading files created on DOS. The terminating character(s) is/are returned in the special variable $KEY.
The default input terminator for this class is $C(13,10).

OUTPUT=$C(n,...) Specify the output terminators to output when WRITE ! is executed. This may be up to 6 (six) characters.
The default output terminator for this class is $C(13,10).
namespace is optional and must be the name of a routine that performs any required control sequences. For example see %X364 from the distribution.

WRITE for Pipes

The WRITE command is of the form:

WRITE comma separated list of writearguments

where writearguments are:

# output terminator, page feed combination
! carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
expression - output any valid MUMPS expression
*intexpr - output the ASCII character intexpr#256

READ for Pipes

The READ command is of the form:

READ comma separated list of readarguments

where readarguments are:

# output terminator, page feed combination
! output carrige return, linefeed combination or specified out terminator
?n tab to character position n (leftmost posn is 0)
/cmd[(params)] to provide device specific control (see namespace)
variable[#count] - input data to a maximum length of [#count] into a MUMPS variable.
*variable - input one ASCII character as an integer (0 to 255)

CLOSE for Pipes

The CLOSE command is of the form:

CLOSE channel