----------------------------------------------------------------------------- Title....: Language Reference Date.....: 2004-MAR-31 Author...: Axel Trocha (axel@freem.net) ----------------------------------------------------------------------------- +-- NOTE ------------------------------------------------------------------+ | | | Large portions are taken from Kevin O'Kanes MumpsVM. You can find their | | implentation at http://www.cs.uni.edu/~okane. I located their original | | documentation in the ./doc/okane directory. | | | +--------------------------------------------------------------------------+ [HARD-CODED MUMPS SHELL COMMANDS] cd Change Directory - without argument is will switch to your home directory - with argument it will switch to the given directory (just as in Un*x) e Internel Editor - without Argument it will edit the current routine (w $ZN => will tell you the current routine) - with Argument it will edit the given routine and load aftwards) Example: e test (will basically do: vi test.m) Note: - to change the default editor change VIEW 204) e.g.: v 204:"vi" w $v(204) => vi gd Outputs the Global Directory (basically: ls -la ^*) [~/cgi-bin/logs] gd GLOBAL DIRECTORY ^acctmp ^alias ^authfail ^axtmp ^board ^cmtnum ^hits ^info ^logi ^logn ^lognum ^logs ^mark ^minitab ^news ^pass ^ping ^rate ^server ^settings ^tmpxp ^visited ^wall ^warl ^xp 25 Globals. gl Global Lister - without arguments it issues a >gd< - with an argument it shows the given global Example: [~/cgi-bin/logs] gl visited visited("58652,43580","deimus")="5890305480-18" visited("58652,43965","axel")="5891345785-22" visited("58652,43965","dognar")="5891451905-22" : ls Lists Directory contents: (just as in Un*x) rd Outputs the Routine Directory (basically: ls -la *.m) ROUTINE DIRECTORY analyppl analysum analyze check conv credits disc error filter1a filtjmc0 fix1 font guest header htgui htlib html info kill link logbest logidx log logs logsppl mcgi mess minitab mirror ping pow ratec rate raterog rateshow rma search show signup stat2 stat3 stat4 stat test toplogs uinfo urlconv util warcron warlhist warlords warlsuch xp 53 Routines. shell Calls a System Shell Note: v 205:"/bin/bash" sets the shell you want to use when issueing the escape to shell command. (default: /bin/bash) ss Show System Status sys Shows system information and buffer pool Example: [~/project/freem-0.7.2/src] sys --- SYSTEN STATUS --------------------------------------------- routine buffer pool: idx name size last-call location 0 1 0 31 ^gg 18 0 32 ^test 34 7 2 out of 32 buffers used. Routine-buffersize 32769 bytes. Maximum Stacksize is 65536 bytes. Journaling: disabled currently used devices: none --------------------------------------------------------------- [COMMANDS] BREAK B{REAK} B{REAK}{:postcond} Interrupts program execution to allow debugging. x = 0 disable CTRL/C x = -2 enable normal error processing x = 2 enable DSM V 2 error processing default enable CTRL/C without Arguments this command stops code excution CLOSE Close Device C{LOSE}{:postcond} C{LOSE}{:postcond} The CLOSE command closes a unit number and makes it available for other uses. It also frees the system buffers for other uses. The argument must evaluate to a number which corresponds to an open unit. The close command may be post-conditionalized and it may have multiple arguments. Note: - no arguments: close all exept HOME DO Calls a Subroutine D{O}{:postcond} D{O}{:postcond} Label{:postcond}{,...} The DO command causes the VM to branch to the label specified and continue execution beginning at that label. Execution proceeds until the end of the program is reached or a QUIT command is encountered. When either of these terminating conditions is achieved, the VM returns to the original DO command and executes subsequent arguments or commands on that line and following lines. DO commands may have multiple arguments. They specify multiple routines to be executed. The DO command may be post-conditionalized and each of its arguments may be post-conditionalized. In the interpreters, an argumentless DO may be used. It causes the code on the immediately following line to be executed. This group must be terminated by a QUIT. An argumentless DO must be followed by two blanks (unless it is the last command on a line). It may be Post-Conditionalized. Thisn feature is normally used in connection with line level indicators. Examples: - D label - D ^routine - D label^routine - D label1,label2,^routine - D:x=1 label ELSE The ELSE command tests the value of the system wide built-in variable $TEST. If $TEST (abbreviated as $T) is zero, the remainder of the line on which the ELSE appears is executed. If $T is not zero, the remainder of the line is not executed. $TEST is set, among other ways, by the IF statement. Since ELSE does not take arguments, it must be followed by two blanks. FOR In the VM, the FOR command specifies repeated execution of the current line with a selected value for an index variable. There are three formats: the first is one in which a local variable (i.e., a global may not be used here) is set successively to values in a list for each execution of the portion of the current line following the FOR; the second is one in which a local variable is set to an initial numeric value, incremented by a fixed amount and the portion of the current line remaining after the FOR is executed until the local variable exceeds an upper limit; the final form is an infinite loop form with a local variable being incremented by a fixed amount with no upper limit test being performed. A given FOR command may have multiple arguments: each argument may be in any of the above formats. The FOR command has scope only for the remaining portion of the current line. A line containing a FOR command may invoke other lines of code, however, by means of a DO or XECUTE command. In these cases the index (or indices) are valid in the remote code executed. Multiple FOR commands may appear nested on the same line. A QUIT command may be used to prematurely terminate the execution of a FOR command. If there are nested FOR commands on the line, a QUIT applies to the most recent FOR. A QUIT used in the context of a FOR command will not cause a return to a DO command. Examples: F I=1,2,5,99 The remainder of the above line will be executed 4 times. The variable I will, successively, have the values 1, 2, 5 and 99. F J=2:4:20 In the above, the remaining portion of the line on which the FOR command appears will be executed 5 times with the value of J being 2, 6, 10, 14, and 18. Note that the first part (2) is the starting value; the second (4) is the increment; and the third (20) is the termination condition. F K=1:1 The above specifies an infinite loop. K will be incremented by one with no upper limit. The user must QUIT, HALT or GOTO to exit the loop. F L=10:-1:0,13,15:1 The above uses three arguments. The first specifies a loop with L ranging from 10 to zero stepping by minus one (10, 9, 8, ... 0); then L has the value 13; then L cycles with no upper limit from 15 upwards with an increment of one. F I="ABC","XYZ",1:1:20,"XXX" "I" will have the values ABC, AND XYZ (strings); then it will cycle from one to twenty by one; then, finally, it will have the value XXX (string). F A(99)=1:1:20 The local array element A(99) will cycle from one to twenty in steps of one. F I=J+1:K*L:A(9,3,2,1) In the above, expressions are used to specify the parameters to an iterative form of the FOR statement. Any valid expression may be used, including those involving global array references. If the iterative forms are used, the expressions will be interpreted as numerics. GOTO The GOTO command causes unconditional transfer of control. For the VM, arguments are specified in the same manner as the DO command listed above. You may post-conditionalize both the command word and the individual arguments. You may specify a label, a variable containing a label (variable name must be preceded by an at-sign [@]), a file name (preceded by circumflex with the file name optionally contained in a quoted field), a label and a file name, or a variable name containing a file name or a label and file name (preceded by an at-sign [@]). If you specify one of the file name forms, the named file completely replaces the transferring program. The symbol table is, however, left intact. Any open devices remain open and may be used by the newly loaded program. The only way to return to the original program is by another transfer of control (either a DO or GOTO). The MumpsVM VM does not permit numeric offsets from labels (as in the second, third and seventh examples below) although these are permitted in full Standard MUMPS. HALT The HALT command terminates execution of Mumps and returns you to the operating system or web server. It may be post-conditionalized. Example: H:I=3 HANG Hang for a given time Example: - h 1 (Hangs for one second) - h 0.5 (Hangs for 1/2 second) - h 0.100 (hangs for 100ms) - h 0.1 (hangs for 100ms) IF The IF command permits conditional execution. It has two forms: the first takes no arguments and the second takes one or more arguments. In the first form, the value of $TEST is examined. If $TEST is 1 (true), the remainder of the current line is executed. If $TEST is 0 (false), the remainder of the current line is not executed. If the no-argument form of the IF is specified, you must include two blanks following the letter I or the word IF to signify the omitted arguments. The other form of the IF command takes arguments. The arguments are evaluated and their result is used to set $TEST. If an argument expression evaluates as non-zero, $TEST is set to 1 (true). If an argument expression evaluates to zero, $TEST is set to 0 (false). If multiple argument expressions are present, they, in effect, are and'ed to produce a final result. The final result in $TEST is used to determine whether the remainder of the line should be executed. Note: there need not be any other commands on the line. The IF statement may be used solely to set $TEST. Note also that expressions are evaluated left to right. This sometimes causes problems for people used to dealing with FORTRAN or BASIC. For example, the expression: I=0&J<0 is always false since it is parsed as: (((I=0)&J)<0) if I is zero, the first expression is true (value of 1); if J is less than zero, then J is interpreted as true giving, as a result of the AND operation (&), a value of 1 which is not less than zero - therefore false. If I is not zero then, regardless of the value of J, the AND operation results in false (value of zero) which is not less than zero - therefore false. The expression should have been written as: (I=0)&(J<0) Note that the IF command may have multiple arguments. These are equivalent to AND'ed expressions. For example: IF A=10,B=20 ... The above is the same as saying: IF (A=10)&(B=20) ... Either form is acceptable. The OR operator may also be used: IF (A=10)!(B=20) ... JOB KILL The second form appears as a list of references (note: indirection for the names is permitted): KILL A,B,^G(1,2,33) The above would delete variables A, B and the global array node ^G(1,2,33). Note: if the global array node ^G(1,2,33) has descendants, they are also deleted. Also, if a local array node is deleted, any of its descendants are also deleted. The final form of the KILL may be used to delete all elements from the local symbol table except for certain protected elements. It has the following format: KILL (A,B(1,1),K) In the above, the local symbol table will be deleted except for variables A, B(1,1) and K. All other variables will be lost. Global array nodes may not be used in this form of the KILL statement. Indirection is permitted. LOCK The LOCK command gains exclusive access to a portion of the data base for an individual user. A LOCK with no arguments frees all prior LOCK's. MERGE Not implemented! NEW OPEN The OPEN command opens sequential files and associates them with device/unit numbers. Opened files may be read or written (see below) OPEN dev:filename/mode Examples: - O 1:"test.txt/r" Modes: r = READ only access w = WRITE new file a = WRITE append r+ = READ/WRITE access w+ = WRITE new file a+ = WRITE append Note: - OPEN implies a previous CLOSE on same channel PRINT It displays the current routine. A routine may be loaded by using the ZLOAD command. QUIT In the VM, the QUIT command provides an exit point for a FOR, DO or XECUTE commands. It may be post-conditionalized. It takes no arguments (therefore, you need two spaces after it if there are any commands following it on the same line). In the FOR case, the QUIT terminates the nearest loop. In the DO case, the QUIT returns to the most recently invoking command. In the XECUTE case, execution of the XECUTE text is terminated and control is returned to the original command line. READ The READ command reads data into variables. It may be post-conditionalized. Ordinarily the READ command reds from the user's terminal (unit number 5). The READ command can be redirected to other devices and files, however, by use of the USE command (see below). It is a common source of error - sometimes quite destructive errors - for the user to READ or WRITE to the wrong device. Many Mumps programmers explicitly place the USE command immediately prior to the READ or WRITE commands. Ordinarily, the READ command takes one or more arguments which may be local scalar variables, local array elements, or global array elements. Each of these is read successively from the input device. When more than one argument is present, a carriage return / line feed is taken as the delimiter between the successive input values. For example: READ A,B,^A(1,3,99) If the input is derived from the user's terminal, the user might type the following sequence in response to the above: The READ command may also write before it reads. This mode is only permitted at the user's console. The options permitted for "write before read" are: a literal constant in quotes; and a tab, new line, or new page operation. A tab operation is specified by a question mark followed by an expression which is interpreted as arithmetic. The effect is to cause the cursor to move to the named column on the page or screen. The new line operation is caused by typing an exclamation point (!). The VM will generate a carriage return / line feed pair. A new page is induced by the pound-sign (#) character. For example, if you wish to read name, social security number and password with user input from column 20, the following might be appropriate: R "NAME",?20,N,"SSN",?20,S,"PASS",?20,P After the above, the variable N will contain the name, S the social security number and P the password. The READ command also permits single character input. That is, a read operation will be satisfied as soon as the user strikes any character on the keyboard: no carriage return is required. The variable will contain a number which is the equivalent of the ASCII character struck. This mode is denoted by preceding the variable to be read by an asterisk. For example: READ "ENTER A LETTER ",*A The READ is satisfied when any character is struck. There is also another form of the READ: that which contains "time-outs" Time-outs permit the programmer to specify a maximum interval of time which the VM should wait for the user to reply to the READ operation. The time-out may be used with either the regular or character by character mode. The time-out is specified by placing a colon after the variable followed by an expression which will be interpreted as numeric. The value of the expression is the amount of time in seconds to wait for a user response to this operation. If the user fails to respond in the required interval, the $TEST built-in variable is set false (0) and the variable contains nothing. If the user does respond in time, $TEST is set true (1) and the variable contains the user's reply. For non-character by character mode input, the user must type the carriage return for the input to be valid. If the time-out expires before the user type the carriage return, all input is lost. For example: AGAIN READ "ENTER NAME ",N:20 IF '$TEST GOTO AGAIN Note: - $ZC will eval to -1, if an EOF was received while reading from a file SET The SET command is the assignment command for Mumps. The expression to the right hand side of the equals sign is evaluated and placed in the storage associated with the variable on the left hand side. Global variables may be used on the left hand side. The SET command may be post conditionalized. The $Piece function may be used on the left hand side of an expression. For example, if the variable a contains the value "aaa.bbb.ccc" the command: S $P(a,".",2)="xxx" will result in the value of a becomming "aaa.xxx.ccc" USE The USE command tells the VM which device (unit) number to use for input output operations (READs and WRITEs). The unit designated as the input/output device remains in effect until changed by the USE again or an error occurs. use 0:(0::::1) => echo off use 0:(0::::0) => echo on use dev:(fileseek:line_terminator:nodelay) e.g. u 1:(10) ?? 1: rightmargin, 3: input_field_length, 5: DSW 7: set-cursor-pos (word) ($X=lo-byte, $Y=high-byte) 9: line-terminators VIEW (see views.txt) WRITE The WRITE command transmits data to an output device. Normally output is directed to the user's console terminal. By the USE command, however, data may be directed to another unit number and its associated file. A unit number must be opened prior to writing to it. The WRITE command takes as arguments either literals in quotes, numeric constants, variable names: both local and global, and control codes and expressions for tab, new line and new page operations. The control operations are the same as those discussed above for the READ operation. Output is stream oriented: that is, each WRITE does not begin on a new line: it begins where the last line left off. Wrap-around occurs at your terminal depending upon the current terminal monitor level width setting. You may specify single character output by an asterisk followed by a decimal number. The system will send the ASCII character associated with the number you specify (e.g., *7 will send the BELL character). For example: WRITE "NAME OF PATIENT",?25,NAME WRITE !,"AGE",?20,AGE XECUTE The XECUTE command can take one or more arguments. The args must be strings. The XECUTE executes each of the arguments in order: that is, it causes the values in the string arguments to be interpreted as MumpsVM command lines. As such, the strings may contain any valid MumpsVM code including XECUTEs (be careful though). For example: SET A="FOR I=1:1:20 W !,I" XECUTE A The above XECUTE will cause the numbers 1, 2, 3, ... 20 to be printed down the side of the terminal. You may construct strings in local or global variables. ZALLOCATE ZBREAK ZDEALLOCATE ZGO ZHALT ZINSERT inserts a given text line on a given position into the active routine ZJOB ZLOAD loads the given routine into the buffer pool Example: zl test (loads test.m) Note: - a ZLOAD on the active routine always loads from disk ZNEW ZPRINT outputs the current routine ZQUIT ZREMOVE removes one or all routines from the buffer pool Note: - ZREMOVE without arguments removes all routines ZSAVE saves the current routine Example: zs test (saves the current routine from the buffer pool to test.m) Note: - ZSAVE without arguments saves the current routine to disk ZTRAP set error trapping Example: zt test (in case of an error test will be executed) ZWRITE ! Unix call ! execute given command !< shell escape with output to %-array !> shell escape with input from % array !! shell escape after HALTing FreeMUMPS Example: - !ls -la - !test : (see ;;) ;; every text after a ;; will be sent to stdout without running through the parser - that way you can add plain html to your M code. e.g. ;; ... ~! (the ~! will be interpreted as CR) [FUNCTIONS] $ASCII $ASCII returns the numeric value of an ASCII character. The string is specified in e1. If no i2 is specified, the first character of e1 is used. If i2 is specified, the i2'th character of e1 is chosen. Example: w $a("") ==> -1 w $a("axel") ==> a w $a("axel",3) ==> e $CHAR $CHAR translates numeric arguments to ASCII character strings. Exampe: w $c(99) ==> c w $c(97,120,101,108) ==> axel $DATA $DATA returns an integer which indicates whether the variable vn is defined. The value returned is 0, if vn is undefined, 1 if vn is defined and has no associated array descendants; 10 if vn is defined but has no associated value (but does have descendants); and 11 is vn is defined and has descendants. The argument vn may be either a local or global variable. $EXTRACT $EXTRACT(e1,i2) or $EXTRACT(e1,i2,i3) $EXTRACT returns a substring of the first argument. The substring begins at the position noted by the second operand. If the third operand is omitted, the substring consists only of the i2'th character of e1. If the third argument is present, the substring begins at position i2 and ends at position i3. Note that this differs from the usual SUBSTR function in PL/I. If only "e1" is given, the function returns the first character of the string "e1". If i3 specifies a position beyond the end of e1, the substring ends at the end of e1. Examples: w $e("axel",3) ==> e w $e("my name is jim",4,7) ==> name $FIND $FIND(e1,e2) or $FIND(e1,e2,i3) $FIND searches the first argument for an occurrence of the second argument. If one is found, the value returned is one greater than the end position of the second argument in the first argument. If i3 is specified, the search begins at position i3 in argument 1. If the second argument is not found, the value returned is 0. Examples: w $f("ABC","B") ==> 3 w $f("ABCABC","A",3) ==> 5 $FNUMBER $JUSTIFY $JUSTIFY(e1,i2) or $JUSTIFY(e1,i2,i3) $JUSTIFY right justifies the first argument in a string field whose length is given by the second argument. In the two operand form, the first argument is interpreted as a string. In the three argument form, the first argument is right justified in a filed whose length is given by the second argument with i3 decimal places. The three argument form imposes a numeric interpretation upon the first argument Examples: (_ => space) w $j(39,3) ==>_39 w $j("TEST",7) ==>___TEST w $j(39,4,1) ==>39.0 $LENGTH $LEN(e1) or $LEN(e1,e2) The $LEN function returns the string length of its argument. $NAME $ORDER $PIECE PIECE(e1,e2,i3) or $PIECE(e1,e2,i3,i4) The $PIECE function returns a substring of the first argument delimited by the instances of the second argument. The substring returned in the three argument case is that substring of the first argument that lies between the i3'th minus one and i3'th occurrence of the second argument. In the four argument form, the string returned is that substring of the first argument delimited by the i3'th minus one instance of the second argument and the i4'th instance of the second argument. If only two arguments are given, i3 is assummed to be 1. $QLENGTH $QSUBSCRIPT $REVERSE $RANDOM $RANDOM(i1) $RANDOM returns an integer in the range zero through i1-1. For example: $RANDOM(100) yields a value between 0 and 99 $SELECT $SELECT(t1:e1,t2:e2,...tn:en) The $SELECT function takes a variable number of arguments delimited by commas. Each argument consists of two parts: a logical expression and a result expression. The function evaluates in sequence each of the logical expressions (shown above as t1, t2, ...tn - note: these can be any expression in reality: a zero result is called false and a non-zero result is called true). If a logical expression is true, the result expression (e1, e2, ... en) is evaluated and becomes the value for the function. $STACK $TEXT $TEXT(l1) or $TEXT(L1+I2) or $TEXT(+I1) $TEXT returns a line of source program text. If just a label is given, the source program text at the label is returned. If a label plus an offset expression (numeric result) is given, then the line of source text returned is some number of lines forward of the line with the noted label. If an arithmetic expression are given, then the line of source text I1 lines from the beginning of the program is returned. $TRANSLATE $VIEW $ZAUTH $ZAUTH(passwd,crypted) checkes if the entered plain text password authenticates with the crypted passwd string . If yes, the result will be 1, otherwise 0. Note: - see $ZCRYPT to crypt a plain text password $ZBOOLEAN $zboolean(A,B,mode) -------------------- mode action -------------------- 0 always FALSE 1 A AND B 2 A AND NOT B 3 A 4 NOT A AND B 5 B 6 A XOR B 7 A OR B 8 A NOR B 9 A EQUALS B 10 NOT B 11 A OR NOT B 12 NOT A 13 NOT A OR B 14 A NAND B 15 always TRUE -------------------- $ZCRC ZCRC "cyclic redundancy check" check sums Example: w $zcrc("axel trocha") ==> 51 $ZCRYPT $ZCRYPT(str), crypts in the same manner as htpasswd does Example: w $zcrypt("axeltrocha") => jVGVOb4SuzmYo Note: - the string should be 6 characters or longer - see $ZAUTH $ZDATE(horolog[,type]) returns the current date / converts from horolog Example: w $ZD => this is a special variable (see below) => 2002/04/26 w $ZD(50000[,0]) => 1977/11/23 w $ZD(50000,1) => 11/23/1977 w $ZD(50000,2) => 23 NOV 1977 w $ZD(50000,3) => 23/11/1977 w $ZD(50000,4) => 23.11.1977 Special cases: (does not work with $ZH or $ZHTI) (outputs the GMT string used for cookies) w $ZD($h,8) => "Wed, 17-Mar-2004 23:38:34 GMT" (GMT) w $ZD($h,9) => "Thu, 18-Mar-2004 01:38:34 GMT+2" (local time) w $ZD($h,10) => "3, 17-03-2004 23:38:34 GMT" (GMT) w $ZD($h,11) => "4, 18-03-2004 01:38:34 GMT+2" (local time) note: the first number for type 10 and 11 is the weekday number (1 - 7 with Monday being 1) Also see: $ZHOROLOG() $ZEDIT(string[,pattern,pos[,pos2]]) 1 argument type: $zedit(txt) reverse string by default 3 argument type: $zedit(txt,pattern,len) implies mode=1 4 argument type: $zedit(txt,pattern,len,mode) ----------------------------------------------------------- mode $l(txt) from behind 1 1 fill behind with 2 0 cut left and right 2 1 center text and fill with 3 0 cut from the front 3 1 fill with in front ----------------------------------------------------------- additional to the list above: ----------------------------------------------------------- mode action ----------------------------------------------------------- <0 reverse >10 filter escape sequences <10 filter escape sequences ----------------------------------------------------------- Examples: $zedit("Axel","_",10) =>Axel______ $zedit("Axel"," _",10) =>Axel _ _ _ $zedit("Axel"," _",10,1) =>Axel _ _ _ $zedit("Axel"," _",10,2) => _ Axel _ $zedit("Axel"," _",10,3) => _ _ _Axel $ZGD(..) interface to the GD graphics library => see 'zgd.txt' (for more information check out http://www.boutell.com/gd ) $ZHORLOG(date[,type]) converts date string back to horolog. It is basically the complementary function to $ZDATE. So the given has to have the same syntax as given by the argument. See $ZDATE. Default type is 0. Example: w $ZD(59625) => 2004/03/31 w $ZH("2004/03/31") => 59625 $ZHTIME(time[,type]) converts time string back to horolog. It is the complementary function to $ZTIME. So the given