ARM Club 3/TheARMClub_PDCD3.iso/hensa/programming/b037_1/!MUMPS_UserDoc_Express

Text File | 1992-12-29 | 13.9 KB | 331 lines

Archimedes MUMPS v1.0 documentation


MUMPS EXPRESSIONS


In MUMPS expressions are evaluated from left to right, treating every
operator ('+','*','/' etc) with the same priority, so "2+3*4" evaluates to
20, not 14 as in most languages. The one way to change the evaluation order
is to use "(<expression>)", the <expression> will be evaluted as if it were
an atomic expression. So if you want "2+3*4" to be 4, write "2+(3*4)".

Another feature of MUMPS that there is only one datatype, the string (or you
could say that all variables are polymorphic: they can have string values,
integer values and floating point values (not at the same time of course!)).
Any conversions that are necessary are automatically performed by the
MUMPS-interpreter. As an example, "2+"12.34"*2" evaluates to 28.68, and
"1+"1017KH"" evaluates to 1018.

The syntax for <expression> is <expratom>[<rest of expression>].
<rest of expression> can be either:
_<expratom>
<arithmetic operator><expratom>
<boolean operator><expratom>
'<booleanoperator><expratom>
?<pattern>
'?<pattern>

The '_' operator concatenates strings, i.e. 12_45 evaluates to "1245".

An arithmetic operator is one of: +,-,*,/,\,#.
In a<operator>b the operators act as follows:

+  adds a to b
-  subtracts b from a
*  multiplies a and b
/  divides a by b
\  takes the integer part of a/b
#  calculates a modulo b and is defined: A#B=A-(B*floor(A/B))

A <boolean operator> evaluates a<boolean operator>b to 0 (zero) or 1 (one):
<  1 if a<b
>  1 if a>b
=  1 if a=b (on a character by character basis, "0.0"<>0)
[  1 if a "contains" b (e.g. "Hahahaha"["ahahah"=1)
]  1 if a "follows" b in the ASCII character set
&  1 if the boolean interpretation of a and b, a' and b' resp. evaluate to 1
        when ANDed. (boolean interpretation: a==0 ? 0 : 1)
!  1 if the boolean interpretation of a and b, a' and b' resp. evaluate to 1
        when ORed.

The "'" operator inverts the value of a boolean expression.

The pattern match operator tries to match a string with a specified pattern.
A pattern consists od a string a or (a) code(s) (one of C,N,P,A,L,U,E)
preceded by a repetition count. A repetition count looks like this:
integer
|[integer].[integer]
so either "1", "1.","1.2",".2", or just "." will do. A repetition count
specifies how many times the following code(s) (or string) must (or may) be
used in matching the string. The meaning of the codes is:
C :matches ASCII control characters
N :matches ASCII numeric characters
P :matches ASCII punctuation characters
A :matches ASCII alphabet characters
L :matches ASCII lowercase alphabet characters
U :matches ASCII uppercase alphabet characters
E :matches any ASCII character

A string in the pattern matches an exact copy of that string only.

As an example: consider checking a Dutch 'postcode', it consists of 4
numerics and 2 uppercase letters. You can check if the variable A is a valid
'postcode' by evaluating "A?4N2U". To check that A contains at least 1 digit
and at most 4, evaluate "A?1.4N". Very complex patterns can be specified
which give you a very powerful tool for input-checking.


EXPRESSION ATOMS

An <expratom> in MUMPS is one of the following:
- a numeric like 12 or -0.1 etc.
- a string like "This is a string"
- a MUMPS special variable
- a MUMPS function
- an expression enclosed in '(' and ')', e.g. (2*3-A)
- a unary operator followed by an <expratom>:
        '<expratom>,
        +<expratom> or
        -<expratom>
- a local variable (possibly indirected)
- a global variable (possibly indirected)

Variable names must start with a '%' or an alphabet character and may
otherwise consist of numeric or alphabet characters.
Global variable names are preceded by a '^' character.


MUMPS SPECIAL VARIABLES

MUMPS recognises a few 'special variables' that can be used in expressions
just like normal variables, but whose names start with a '$'. They are a
kind of MUMPS functions, but need no parameters for calculating their value.
The 'special variables' are:

$H[OROLOG]
        $H returns the date and time in the following format:
        <days since January 1, 1841>,<seconds since last midnight>
        You can convert +$H (or any other date) to a readable dateformat
        using the routine %DAT, supplied with Archimedes MUMPS.

$I[O]
        $I contains the current device number.

$J[OB]
        $J contains the JOB number of the JOB that executes the $J.

$S[TORAGE]
        $S contains the amount of memory free for use in the partition that
        executes the $S. $S is not exactly defined, the suggestion in the
        MUMPS standard is not followed by Archimedes MUMPS. $S contains the
        amount of memory free for routines or stack, local variable space is
        not taken into account when calculating $S.

$T[EST]
        $T contains either 0 (zero) or 1 (one). $T is set by executing an IF
        command, a LOCK, OPEN or READ command. For example, if X=2 and you
        write: "IF X=3 W *7" no BELL will sound and $T will have the value
        0.

$X
        $X contains the current device x-coordinate. For example,
        "W #?10 W $X" will print 10, because the current y-coordinate is 10
        at the time when $X is evaluated.

$Y
        $Y contains the current device y-coordinate. For example,
        "W #!!! W $Y" will print 3, because the current y-coordinate is 3
        at the time when $Y is evaluated.

$Z
        $Z special variables are covered in the file "Z".


MUMPS FUNCTIONS

MUMPS also recognises functions, whose names start with a '$', just like
special variables. The functions are very powerful and make data
manipulation extremely easy. Especially the $DATA, $ORDER and $PIECE
provide easy access and manipulation of your databases. The MUMPS functions
are:

$A[SCII](<expr 1>[,<expr 2>])
        $A returns the ASCII value of the first character of <expr1>, or the
        n-th character, if <expr 2> is present and evaluates to an integer
        n. IF n<1 or n>$L(<expr 1> then $A returns -1.

$C[HAR](<integer expr>[,<integer expr>])
        Builds a string whose characters are the ASCII characters
        corresponding to the numbers in the arguments. Integers outside the
        range [0,127] are skipped.

$D(ATA](<local or global variable>)
        Returns a number indicating existence of the variable and it's
        descendants. Suppose D is the value of $D and set to 0 (zero). If
        the variable exists, 1 (one) is added to D. If any descendant
        exists, add 10 to D. Then, D is the value of $D().

$E[XTRACT](<expr>[,<integer expr 2>][,<integer expr 3>])
        $E extracts a substring from it's first argument. Let n be the
        value of <integer expr 2> (or 1 if only one argument is specified)
        and m be the value of <integer expr 2> (or n if not specified). The
        substring starts at position n and ends at position m. Naturally,
        the result of $E is the empty string if m<n or n>$L(<expr>).

$F[IND](<expr 1>,<expr 2>[,<integer expr>])
        $F finds a substring sub (<expr 2>) in target (the first argument),
        starting at position n (<integer expr 3>), or 1 if n<1 or n is
        absent. If n>$L(target) or sub is not found in target, $F evaluates
        to 0 (zero). If not, $F returns the starting position of the
        leftmost occurrence (starting at n, of course) plus the $L(sub) plus
        1 (one).

$FN[UMBER](<numexpr>,<expr>[,<integer expr>])
        $FN formats numbers. Let n be the value of <numexpr>. The two
        argument form uses <expr> as a 'formatting string' for n. The
        following formatting codes are allowed in <expr>:

        P : put negative numbers between parentheses (and positive numbers
                between spaces). So, if n<0 then the result will be:
                "("_|n|_")" (|n| means absolutevalue of n), otherwise the
                result is: " "_|n|_" ".

        T : trail signs (either '-', '+' or ' ' (in case no sign is to be
                displayed)).

        , : Insert a comma every three digits left of the decimal point.

        + : Use a '+' sign for positive numbers.

        - : Do not display a '-' sign for negative numbers.

        Multiple occurrences of the same formatting code have the same
        effect as just one such code. The empty formatting string leaves the
        numbers representation unchanged. Use of non-defined codes or use of
        the "P" code togehter with "T","+" or "-" generates an error.
        $FN always puts a '0' in front of the decimal point if -1<n<1.

        The three rgument form does the same as the two argument form, but
        first the number is rounded to <integer expr> places.

$G[ET](<local or global variable>)
        $G returns the value of the variable or the empty string if the
        variable does not exist.

$J[USTIFY](<target string>,<integer expr 1>[,<integer expr 2>])
        Let A1 be the targetstring, A2 the value of the second argument and
        A3 the value of the third argument. If 3 arguments are specified,
        the numeric interpretation of A1 is taken and N2 specifies the field
        width and N3 specifies the number of decimal places.
        If only two arguments are given spaces are added (if necessary) at
        the front of A1 to make a field width of A2 places.

$L[ENGTH](<expr 1>[,<expr 2>])
        The one-argument form returns the number of characters in the string
        <expr 1>.
        The two argument form returns the number of non-overlapping
        occurrences of <expr 2> in <expr 1> plus 1 (one). If <expr 2> is the
        empty string, $F returns 0 (zero).

$N[EXT](<local or global variable>)
        $N is almost the same as $ORDER (but more limited). Instead od
        'starting' with an empty string,$N 'starts' with -1. Instead of
        ending with an empty string $N ends with -1 too. Not nice if you
        have "-1" as a legal subscript in your database. Do NOT use $NEXT,
        it will be removed from MUMPS in a future standard!

$ORDER(<local or global variable>)
        $O gives 'the next subscript in the database'. That is, if the
        variable looks like this: name(s1,s2,...,sn), $O returns the
        subscript that 'follows' subscript sn immediately. Numeric
        subscripts precede string subscripts. The empty string
        precedes all other legal subscripts. Example: if you have the
        following database:
        ^A(-100)=1000
        ^A(-10)=100
        ^A(-1)=10
        ^A(10)=-100
        ^A("HUIB","VERWEIJ")="Human"
        ^A("PIMMETJE","VERWEIJ")="Cat"
        ^A("ZZZ")="YYY"
        then the follwoing code will list all first subscripts:
        S N1="" F  S N1=$O(^A(N1)) Q:N1=""  W N1," "
        The following string will be written to the current device:
        "-100 -10 -1 10 HUIB PIMMETJE ZZZ ".
        The follwing code will write all data to a depth of two:
        S N1="" F  S N1=$O(^A(N1)) Q:N1=""  W:$D(^(N1))#10 ^(N1)," " S N2=""
         F  S N2=$O(^A(N1,N2) Q:N2=""  W:$D(^(N2))#10 ^(N2)," "
        The following string will be written to the current device:
        "1000 100 10 -100 Human Cat YYY ".

$P[IECE](<target string>,<delimiter string>[,<start>[,<end>]])
        $P uses the delimiter to partition the targetstring. It returns the
        substring from target string that includes partition start and
        includes partition end. If absent, 1 (one) is used for the third
        argument and the fourth argument is equal to the third.
        Examples:
        $P("AB*CD*EF*","*")      = "AB"
        $P("AB*CD*EF*","*",1)    = "AB"
        $P("AB*CD*EF*","*",1,2)  = "AB*CD"
        $P("AB*CD*EF*","*",2,3)  = "CD*EF"
        $P("AB*CD*EF*","*",2,4)  = "CD*EF*"
        $P("AB*CD*EF*","*",4)    = ""
        $P("AB*CD*EF*","*",5,10) = ""

$R[ANDOM](<integer expr>)
        $R returns an integer in the interval [0,N-1], where N is the value
        of it's argument.

$S[ELECT](<boolean expr>:<expr>[,<boolean expr>:<expr>])
        $S selects one of it's <expr> arguments. The one selected is the
        first one with a boolean that evaluates to true. It is an error when
        no such <boolean expr> is given. <expr> arguments are not evaluated
        when their boolean is not true.
        Examples:
        W $S(TYPE=1:"Globals",TYPE=2:"Routines",1:"Type unknown!")

$T[EXT](<line reference>|+<integer expr>)
        Return the text of the routine, as indicated by the argument. If the
        argument has the form +<integer expr>, +0 evaluates to the
        routinename, +1 evaluates to the text of the first line in the
        routine, +2 evaluates to the text of the second line in the
        routine, etc.
        If the argument has the other form (<line reference>) then the value
        of $T is the text of the designated routineline.
        If the line does not exist, $T returns the empty string.

$TRANSLATE(<string 1>,<string 2>[,<string 3>])
        If the third argument is missing, it is taken to be the
        empty string. $TRANSLATE replaces all characters in s1 (<string 1>)
        that match characters in s2 with characters from s3. If s3 is the
        empty string, characters are removed from s1.
        Examples:
        $TR("H1u2i3b4","0123456789")="Huib"
        $TR("1018 KH"," ")="1018KH"
        $TR(A,",.",".,") replaces all comma's with dots and vice versa.

 $V[IEW](<integer expr>[,<various other arguments>])
        $V should not be used in routines designed for portability.
        In Archimedes MUMPS, the following arguments can be given to $V:
        $V(1) returns the Naked Indicator.
        $V(2) returns the number of JOBs in the system.
        $V(4) returns the routine name
        $V(5) returns the principle device
        $V(6) returns the current device
        $V(7) returns a 'list' of open devices
        $V(9) returns a 'list' of jobnumbers
        $V(9,<jobnumber>) returns info about that JOB:
         "UCI name,routinename,status,partition size,PD[,openlist]"
          where status means: 0=awaiting input, 1=interpreting.
        $V(10,n) returns sin(n)
        $V(11,n) returns cos(n)
        $V(12) returns $ZT value
        $V(13) returns a 'list' of UCI's

$Z(...)
        $Z functions are covered in the file "Z".

/* end of Express */