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]] 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. 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]] 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. WRITE for Devices The WRITE command is of the form: WRITE comma separated list of writearguments where writearguments are:! carrige return, linefeed combination or specified out terminator 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 carrige return, linefeed combination or specified out terminator 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]] 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 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]] 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).
WRITE for Files The WRITE command is of the form: WRITE comma separated list of writearguments where writearguments are:! carrige return, linefeed combination or specified out terminator 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 carrige return, linefeed combination or specified out terminator 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]] 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 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]] 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).
WRITE for Network The WRITE command is of the form: WRITE comma separated list of writearguments where writearguments are:! carrige return, linefeed combination or specified out terminator 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 carrige return, linefeed combination or specified out terminator 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]] 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 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]] 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). WRITE for Pipes The WRITE command is of the form: WRITE comma separated list of writearguments where writearguments are:! carrige return, linefeed combination or specified out terminator 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 carrige return, linefeed combination or specified out terminator 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