M[UMPS] Commands

U[SE]

Introduced in the 1977 ANSI M[UMPS] language standard.

Clarification (no change intended) in a future ANSI M[UMPS] language standard:

Any keywords in the argument of the command are processed in strict left-to-right order. When multiple equivalent parameters are encountered, the last occurrence processed will define the action(s) to be taken.

OPEN VDU,PRINT FOR I=1:1:END FOR DEV=VDU,PRINT USE DEV WRITE !,X(I) CLOSE VDU,PRINT
Print the same text on two devices.

OPEN DEVICE::50 ELSE WRITE "Can't open..." QUIT
Attempt to open the device. If the device does not become available within the time-out period (50 seconds), stop trying and set the value of $TEST to false.

Addition in the 1995 ANSI M[UMPS] language standard.

OPEN DEVICE:::"X3.64" USE DEVICE::"X3.64"
Open a device with the mnemonicspace "X3.64" (VT- 100 compatible terminal).

The most common functions in ANSI X3.64 are itemized in X3.64 description.

OPEN DEVICE::10:("X3.64","GKS")
This command opens a device and specified both the mnemonicspaces X3.64 and GKS. It also specifies a time-out of 10 seconds. X3.64 will be the initial mnemonicspace for the device; GKS may be selected in subsequent USE commands, and X3.64 may be re-selected. No other mnemonicspaces may be selected in subsequent USE commands.

Additions in a future ANSI M[UMPS] language standard.

More mnemonicspaces are becoming available.

The ability to specify "user-defined" mnemonicspaces is added. It will be possible to specify to an implementation to use entries in a specific routine (let's call it USER for the purpose of this discussion) for the processing of the commands OPEN, USE and CLOSE and the various controlmnemonics for specific combinations of device and mnemonicspace.

When this feature is active, the controlmnemonic /ABC(P1,P2) will be executed as DO ABC^USER(P1,P2), and the command USE device:(PARAM1:KEY2=VALUE2) will be executed as:

DO
. NEW X,Y
. SET (X,Y)=2 ; Number of deviceparameters
. SET X(1)="PARAM1" ; First deviceparameter
. SET X(2)="KEY2",Y(2)=VALUE2
. DO %USE^USER(device,.X,.Y,"")
. QUIT

The name of a device may contain an environment specification
USE |"LONDON"|MTA47

A time-out for output operations may be specified. In order for this capability to be available, the current device must have established a mnemonicspace that supports this feature.

Use device:(OUTPUTTIMEOUT=duration)

will establish a time-out period of duration seconds. If any subsequent output-producing argument of a READ or WRITE command fails to complete execution within this time-out period, this condition will be visible in two fashions:

^$DEVICE(device,"OUTSTALLED")=1
an error occurs with ecode equal to M100

If the value of duration in the example above would not be greater than zero, no time-out would apply for the device in question.

The ability to specify an "output time-out" is added. An output time-out is specified as a device parameter in an OPEN or USE command.

OPEN "TTY2":OUTPUTTIMEOUT=5:"X3.64"
Assuming that the implementation allows for the deviceparameter OUTPUTTIMEOUT in the class library called "X3.64" (VT-100 compatible devices), an error with code M100 will occur when an attempt is made to output data to the device called "TTY2", and it is not possible to produce this output within 5 seconds.

Until external action has cleared this error condition, the value of ^$D[EVICE]("TTY2","OUTSTALLED") will have the value 1 (true).

USE "TTY2":OUTPUTTIMEOUT=0
will cancel the recognition of output time-out conditions, and will cause the system to wait until output to the device in question has completed.

The addition of a binding to TCP/IP socket devices includes a number of new deviceparameters.

Below, a number of sample programs are shown that could be used as clients and servers in a network of programs that communicate through TCP/IP sockets.

Client Process

 ; connect to any server providing the service
 SET timeout=10
 OPEN dev:(connect="myservice"):timeout:"SOCKET"
 IF '$TEST WRITE !,"Unable to connect to server" QUIT
 USE dev
 ;==> WRITE/READ dialogue with server ...
 CLOSE dev QUIT

 ; restrict the search to TCP/IP servers
 OPEN dev:(connect="myservice:IP:TCP")::"SOCKET"
 IF '$TEST WRITE !,"Unable to connect to server" QUIT
 SET sockindx=^$DEVICE(dev,"SOCKETINDEX")
 SET address=^$DEVICE(dev,sockindx,"REMOTEADDRESS")
 USE $PRINCIPAL WRITE !,"Connected to server at ",address
 USE dev
 ;==> WRITE/READ dialogue with server ...
 CLOSE dev QUIT

 ; connect to a specific server and port
 OPEN dev:(connect="128.200.1.5:IP:TCP:2001")::"SOCKET" USE dev
 ;==> WRITE/READ dialogue with server ...
 CLOSE dev QUIT

Serial Server Process

 SET timeout=10
 ; obtain a socket
 OPEN dev:(listen=":IP:TCP:2001"):timeout:"SOCKET"
 IF '$TEST WRITE !,"Unable to open server port" QUIT
 ; establish a queue depth of 3
 USE dev WRITE /listen(3)
 ; wait for a client connection
 FOR  USE dev WRITE /wait(timeout) QUIT:$DEVICE  IF $KEY'="" d
 . ;==> READ/WRITE dialogue with client ...
 . SET sockindx=^$DEVICE(dev,"SOCKETINDEX")
 . SET sockhndl=^$DEVICE(dev,sockindx,"SOCKETHANDLE")
 . ; close current device
 . CLOSE dev:(socket=sockhndl)
 CLOSE dev QUIT

Concurrent Server Process

 SET timeout=10
 ; obtain a socket
 OPEN dev:(listen=":IP:TCP:2001"):timeout:"SOCKET"
 IF '$TEST WRITE !,"Unable to open server port" QUIT
 ; establish a queue depth of 3
 USE dev WRITE /listen(3)
 ; wait for a client connection
 FOR  USE dev WRITE /wait(timeout) QUIT:$DEVICE  IF $KEY'="" d
 . SET sockindx=^$DEVICE(dev,"SOCKETINDEX")
 . SET sockhndl=^$DEVICE(dev,sockindx,"SOCKETHANDLE")
 . USE dev:(detach=sockhndl)
 . JOB server^srv(sockhndl)
 CLOSE dev QUIT

In this example, the routine ^srv could look like

 ...
server(sockhndl) ;
 ...
 OPEN dev:(attach=sockhndl)::"SOCKET"
 USE dev
 ;==> READ/WRITE dialogue with client
 CLOSE dev QUIT

Multi Protocol Server Process

 SET timeout=10
 OPEN dev:::"SOCKET"  ; acquire M[UMPS] device
 USE dev:(listen=":IP:TCP:2001") ; Establish TCP protocol
 IF $DEVICE USE $PRINCIPAL WRITE !,"Unable to listen for TCP connections" CLOSE dev QUIT
 SET tcpindx=^$DEVICE(dev,"SOCKETINDEX")
 SET tcphndl=^$DEVICE(dev,tcpindx,"SOCKETHANDLE")
 USE dev:(listen=":SPX:1025") ; Establish SPX protocol
 IF $DEVICE USE $PRINCIPAL WRITE !,"Unable to listen for SPX connections" CLOSE dev QUIT
 SET spxindx=^$DEVICE(dev,"SOCKETINDEX")
 SET spxhndl=^$DEVICE(dev,spxindx,"SOCKETHANDLE")
 ; wait for a client connection on either protocol
 FOR  USE dev WRITE /wait(timeout) QUIT:$DEVICE  IF $KEY'="" d
 . SET sockindx=^$DEVICE(dev,"SOCKETINDEX")
 . SET sockhndl=^$DEVICE(dev,sockindx,"SOCKETHANDLE")
 . IF $KEY'="CONNECT" USE $PRINCIPAL WRITE "Shouldn't happen" CLOSE dev:(socket=sockhndl) QUIT
 . USE dev:(detach=sockhndl)
 . JOB server^srv(sockhndl) ; Same server as above example
 CLOSE dev QUIT

For a program that parses a programming language, it is hard to see the difference between:
...:(abc=xyz):...
and
...:(FILENAME="C:\temp\ABC.TMP"):...
In the former example, the text between the parentheses should be an expression that happens to return a boolean value, whereas in the latter example, the text between the parentheses could be a "keyword equals value" combination that has a meaning in certain mnemonicspaces.

In order to make it easier to indicate this difference, the option to precede a devicekeyword with a slash has been introduced. This would make the latter example look like:
...:(/FILENAME="C:\temp\ABC.TMP"):...

Examples with naked references:

USE DEVICE
SET ^ABC(1,2)="reset naked indicator"
; Naked indicator is now ^ABC(1, USE ^(3,4)
; Naked indicator is now: ^ABC(1,3,
; Actual reference is: ^ABC(1,3,4)

USE DEVICE:PARAMETERS
SET ^ABC(1,2)="reset naked indicator"
; Naked indicator is now ^ABC(1, USE ^(3,4):^(5,6)
; 1. fetch ^(3,4) = ^ABC(1,3,4)
; 2. fetch ^(5,6) = ^ABC(1,3,5,6)
; Naked indicator is now: ^ABC(1,3,5,

This document is © Ed de Moel, 1995-2005.
It is part of a book by Ed de Moel that is published under the title "M[UMPS] by Example" (ISBN 0-918118-42-5).
Printed copies of the book are no longer available.

This document describes the various commands that are defined in the M[UMPS] language standard (ANSI X11.1, ISO 11756).

The information in this document is NOT authoritative and subject to be modified at any moment.
Please consult the appropriate (draft) language standard for an authoritative definition.

In this document, information is included that will appear in future standards.
The MDC cannot guarantee that these 'next' standards will indeed appear.