Button for 1977 Button for 1984 Button for 1990 Button for 1995 Button for MDC Button for notes Button for examples
Left Hand Pointer

USE

M[UMPS] by Example

Right Hand Pointer

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:

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

or

; 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,

Button for 1977 Button for 1984 Button for 1990 Button for 1995 Button for MDC Button for notes Button for examples

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

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 13-Sep-2014, 09:18:38 .

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