MUMPS Xcall 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.
$&%DIRECTORY(),
$&%ERRMSG(),
$&%FILE(),
$&%FORK(),
$&%GETENV(),
$&%HOST(),
$&%IC(),
$&%OPCOM(),
$&%ROUCHK(),
$&%SETENV(),
$&%SIGNAL(),
$&%SPAWN(),
$&%VERSION(),
$&%ZWRITE(),
$&E(),
$&PASCHK(),
$&V(),
$&X(),
Note: The name of an Xcall may not be abreviated.
XCall: $&%DIRECTORY Examine host directory
Form: $&%DIRECTORY(filespec or null)
Retn: Next matching file - null when done
Eg: S DIR(1)=$&%DIRECTORY("/home/*") ;Setup for directory
F I=2:1 Q:DIR(I-1)="" S DIR(I)=$&%DIRECTORY("") ;Get remaining entries
XCall: $&%ERRMSG Get text of an error
Form: $&%ERRMSG(error_code)
Retn: text version of the error
Eg: W $&%ERRMSG("M1") -> "Naked indicator undefined"
XCall: $&%FILE Obtain information on a file or Device
Form: $&%DIRECTORY(filespec,param)
Retn: Param Returns
EXISTS true (1) if the file/device exists else 0
SIZE size of the file in bytes, error if the file doesn't exist
Eg: W $&%FILE("/home/fred/.Xdefaults","EXISTS") ;Check for file
XCall: $&%FORK Create another process identical to current
Form: $&%FORK(dummy)
Retn: Failure: 0
Success (parent): Child MUMPS job number
Success (child): Minus (Parent MUMPS job number)
Eg: S JN=$&%FORK("") ;Create duplicate process
XCall: $&%GETENV Get value of an environment variable
Form: $&%GETENV(environment)
Retn: Content of specifiec environment variable.
Eg: S ED=$&%GETENV("EDITOR") ;Get value of EDITOR
XCall: $&%HOST Do host/ip lookup
Form: $&%HOST(spec,param)
Retn: Param Returns
IP ip address of specified host name
NAME hostname of the current or specified machine
Eg: W $&%HOST("fred.local","IP") ;Get ip address
W $&%HOST($&%HOST("","NAME"),"IP") ;Get current sys ip
XCall: $&%IC Check the database
Form: $&%IC(vol,flag)
where flag: -2 means validate and fix the map block
-1 means validate the map block
0 means check entire database
blk means check blk and descendants
Retn: Number of errors found - errors are printed on $IO
Eg: S ERR=$&%IC(1,0) ;Check the database
XCall: $&%OPCOM Log a message or write on a device
Form: $&%OPCOM("message"[,device])
Retn: null string
Eg: S %=$&%OPCOM("Invalid login attempt on "_$P($D,",",3)) ;Log it
S %=$&%OPCOM("Hello there","/dev/ttyd0")
XCall: $&%ROUCHK Check compile syntax for a routine
Form: $&%ROUCHK(routine)
Retn: zero
Eg: S %=$&%ROUCHK("ROU") ;Check syntax of ROU
XCall: $&%SETENV Set value of an environment variable
Form: $&%SETENV(environment,value)
Retn: null
Eg: S dummy=$&%SETENV("EDITOR","xed") ;Change EDITOR to xed
XCall: $&%SIGNAL
Form: $&%SIGNAL(pid,sig)
Retn: 1 if OK, 0 on fail, error M99 if pid<1 or sig<0 or sig>31
Eg: S %=$&%SIGNAL(pid,0) ;Check to see if pid is still there
XCall: $&%SPAWN Spawn a host o/s process
Form: $&%SPAWN(command)
Retn: null string
Eg: S %=$&%SPAWN("stty onlcr;ls -l /home/joe;stty -onlcr")
XCall: $&%VERSION Obtain implementation and version
Form: $&%VERSION("NAME") NOTE: This is for compatability with VAX-DSM
The argument is ignored
Retn: MUMPS V1.00 for FreeBSD i386
Eg: $&%VERSION("NAME") -> "MUMPS V1.00 for FreeBSD i386"
XCall: $&%ZWRITE Dump local symbols
Form: $&%ZWRITE(0) NOTE: This is for compatability with VAX-DSM
The argument is ignored
or $&%ZWRITE(global_ref) All local variables are stored as subscripts
of global_ref with their data.
Retn: null string
Eg: S %=$&%ZWRITE(0) ;Dump the entire local symbol table to $IO
XCall: $&E Edit a string
Form: $&E(expr[,param])
where param may be numeric or string as follows
Num Str Means
1 P trim Parity
2 D Discard all spaces and tabs
4 C discard all Control characters
8 B discard Beginning spaces and tabs
16 R Reduce spaces and tabs to one space
32 U convert lower case to Upper case
64 L convert upper case to Lower case
128 T discard Trailing spaces and tabs
256 Q preserve Quoted (except for parity trim)
The default action if param is omitted is 445 which is
1+4+8+16+32+128+256 or "PCBRUTQ".
Retn: Returns an edited form of the expression
Eg: $&E(" this is JUNK ") -> "THIS IS JUNK"
XCall: $&PASCHK Check a user password
Form: $&PASCHK(user,password)
Retn: Returns 1 if valid else 0
Eg: I '$&PASCHK(USR,PASS) W "Access failed",! H ;Check the password
XCall: $&V Screen address
Form: $&V(line,col)
Retn: The escape sequence to address to line lin, column col on an ANSI
standard terminal.
Eg: $&V(10,40) -> $C(27,91,49,48,59,52,48,72)
XCall: $&X Simple checksum
Form: $&X(expr)
Retn: The sum of the ASCII values of all characters in expr.
Eg: $&X("ABC") -> 198