The Annotated M[UMPS] Standards

☜

USE

M[UMPS] by Example

☞

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

Clarification (no change intended) in a future 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 the 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 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:(OUTTIMEOUT=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":OUTTIMEOUT=5:"X3.64"
Assuming that the implementation allows for the deviceparameter OUTTIMEOUT 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":OUTTIMEOUT=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,

Copyright © Standard Documents; 1977-2024 MUMPS Development Committee;
Copyright © Examples: 1995-2024 Ed de Moel;
Copyright © Annotations: 2003-2008 Jacquard Systems Research
Copyright © Annotations: 2008-2024 Ed de Moel.

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

Some specifications are "approved for inclusion in a future standard". Note that the MUMPS Development Committee cannot guarantee that such future standards will indeed be published.

This page most recently updated on 08-Jan-2024, 12:14:37.

For comments, contact Ed de Moel (demoel@jacquardsystems.com)