home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / languages / progs / mumps / !MUMPS_UserDoc_Commands < prev    next >
Encoding:
Text File  |  1992-11-17  |  15.6 KB  |  403 lines
  1.  
  2. Archimedes MUMPS v1.0 documentation
  3.  
  4.  
  5. MUMPS COMMANDS
  6.  
  7.  
  8.  
  9. BREAK
  10.         - no arguments.
  11.         - may be post-conditionalised
  12.  
  13.         Halts execution. There is no way (yet) to continue after BREAK.
  14.  
  15.         EXAMPLE:
  16.         S X=Y B:DEBUG  ; Examine value of X if DEBUG'=0
  17.  
  18.  
  19. CLOSE_<expression specifying a device>[:<device parameters>]
  20.         <device parameters> ::= <expression> |
  21.                                 (<expression>[:<expression>]*)
  22.         - may be post-conditionalised
  23.         - argument listing is possible
  24.         - argument indirection is allowed
  25.         - argument cannot be post-conditionalised
  26.  
  27.         Closes one or more devices (if they're open).
  28.  
  29.         EXAMPLES:
  30.         C:DEV'=0 DEV ; Close device if it isn't the default device
  31.         CLOSE FILE1,FILE2 ; FILE1 & 2 are device specifiers (ints in MUMPS)
  32.  
  33.  
  34. DO_<entry reference>
  35.         - may be post-conditionalised
  36.         - argument listing is possible
  37.         - argument indirection is allowed
  38.         - arguments can be post-conditionalised
  39.  
  40.         Call the subroutine specified by the <entry reference>.
  41.  
  42.         EXAMPLES:
  43.         D TOTAL ; Call subroutine total in current routine
  44.         D:DSPL DISPLAY^UTILS ; Call label DISPLAY in routine UTILS if DSPL'=0
  45.         DO:'ERR TOTAL:TOT,AVG:AVG,MIN:MIN,MAX:MAX ; Skip DO on error
  46.         ; DO any of the arguments if their postconditions are <> 0
  47.         D @SUB ; Choose subroutine indirectly.
  48.  
  49.  
  50. ELSE_
  51.         - may not be post-conditionalised
  52.  
  53.         ELSE does not have arguments. It tests $T. If $T is 1, the rest of
  54.         the line is skipped.
  55.  
  56.         EXAMPLE:
  57.         I X=Y W "X equals Y"
  58.         E  W "X does not equal Y"
  59.  
  60.  
  61. FOR_<local variable>=<for parameter>[,<for parameter>]*
  62.         <for parameter> ::= <expression>
  63.                           | <numex> 1:<numex> 2
  64.                           | <numex> 1:<numex> 2:<numex> 3
  65.         (<numex> is short for <numeric expression>
  66.         - may not be post-conditionalised
  67.         - argument listing is not possible
  68.         - argument indirection is not allowed (FOR parameters also)
  69.         - arguments cannot be post-conditionalised
  70.  
  71.         Execute a FOR loop.
  72.         If the FOR parameter is just one expression, then the FOR loop is
  73.         executed with the <local variable> having the value of the
  74.         expression.
  75.         If the FOR parameter is of the second form, an endless loop is
  76.         specified. Termination of the loop can be achieved by executing a
  77.         QUIT command or a GOTO command
  78.         The third form specifies the 'usual' FOR loop that has a begin and
  79.         an end. If <numex> 1 'exceeds' <numex> 3 at the start of the FOR
  80.         loop, the loop is never executed.
  81.  
  82.         EXAMPLES:
  83.         F I=0:1:99 W I ; Write the first 100 numbers in |N
  84.         F I="Hi there,","I am","your",1:1:10,"computer !" W I," "
  85.         ; Result: "Hi there, I am your 1 2 3 4 5 6 7 8 9 10 computer ! "
  86.         F I=1:1 ; Endless loop
  87.         F I=1:1 Q:I>100  ; Let I have the values 1..101
  88.         F I=1:1:100 ; At the end of the FOR loop, I=100
  89.         F I=-1,1 F J=1,-1 W $J(I*J,4) ; Output: "  -1   1   1  -1"
  90.         F I=1:1:2 S I="HI" W I ; Produce an endless loop of "HI"'s !
  91. FOR__   The argumentless FOR loops forever, but it does not use a
  92.         loop-variable.
  93.  
  94.  
  95. GOTO_<entry reference>
  96.         - may be post-conditionalised
  97.         - argument listing is possible
  98.         - argument indirection is allowed
  99.         - arguments can be post-conditionalised
  100.  
  101.         If no label is specified, control transfers to the first line of the
  102.         specified routine. If both a line and routine are specified, control
  103.         transfers of course to the specified line in the specified routine.
  104.         If only a line reference is given, then control transfers to that
  105.         line in the current routine.
  106.         All FOR loops on the same line as the GOTO are terminated
  107.  
  108.         EXAMPLE:
  109.         G:TRANSFER A:x=1,B:x=2,C:x>2,ERR
  110.         If TRANSFER is non-zero, control is transferred to label A of the
  111.         current routine if x=1, label B if x=2, label C if x>2, and finally,
  112.         if none of the postconditions of the arguments was true, to label
  113.         ERR. So only ONE of the jumps is made !
  114.  
  115.  
  116. HALT_
  117.         - may be post-conditionalised
  118.  
  119.         Halts execution of the current JOB. It's LOCK list is emptied, the
  120.         devices that were opened by the partition are closed and released.
  121.  
  122.  
  123. HANG_<numeric expression>
  124.         - may be post-conditionalised
  125.         - argument listing is possible
  126.         - argument indirection is allowed
  127.         - arguments cannot be post-conditionalised
  128.  
  129.         Waits a specified time (in seconds) before execution is continued.
  130.  
  131.         EXAMPLES:
  132.  
  133.         H:SLOW DELAY
  134.         OPENDEV O 2:("FILE":"R"):0 I '$T H 1 G OPENDEV
  135.  
  136.  
  137. IF_<boolean expression>
  138.         - may not be post-conditionalised
  139.         - argument listing is possible
  140.         - argument indirection is allowed
  141.         - arguments cannot be post-conditionalised
  142.  
  143.         Evaluates the expression, if it is non-zero (i.e. 1) the rest of the
  144.         line is executed, otherwise it is skipped.
  145. IF__    (No arguments) The boolean expression in the above explanation is
  146.         taken to be $T.
  147.  
  148.  
  149. JOB_<entry reference>[:<job parameters>[<timeout>] | <timeout>]
  150.         - may be post-conditionalised
  151.         - argument listing is possible
  152.         - argument indirection is allowed
  153.         - arguments cannot be post-conditionalised
  154.  
  155.         A new JOB is created in it's own partition. The routine specified by
  156.         the <entry reference> is loaded and control is transferred to the
  157.         specified line (or the first if no line was specified).
  158.  
  159.         The job parameters in Archimedes MUMPS are:
  160.         1) A UCI name (default: UCI name of parent partition)
  161.         2) Partition size (default: partition size of parent partition)
  162.         3) Principle device ((default: principle device of parent partition)
  163.         The parameters are specified as follows:
  164.         (<par1>:<par2>:<par3>)
  165.         Note that parameters are not portable !
  166.  
  167.         EXAMPLES:
  168.         J ^QSORT ; run QSORT in current UCI
  169.         J ^QSORT:("TST":4:20) ; run QSORT in UCI "TST", partition size=4
  170.         ; principle device is NULL-device.
  171.  
  172.  
  173. KILL__
  174. KILL_<glvn>
  175. KILL_(<glvn>[,<glvn>]*)
  176.         - may be post-conditionalised
  177.         - argument listing is possible
  178.         - argument indirection is allowed
  179.         - arguments cannot be post-conditionalised
  180.  
  181.         The form without arguments kills all local variables. The second form
  182.         kills thespecified variable (and it's descendants !). The third form
  183.         kills all local variables, except the once that are specified in the
  184.         argument and their descendants
  185.  
  186.         EXAMPLES:
  187.         K  D READVARS ; kill old values and read fresh ones
  188.         K:NEW ^TEMP ; Kill the global ^TEMP (the entire global is killed !)
  189.         K (POSPOSC,U,INE,INO) ; kill all local variables except the ones
  190.         ; specified in the only argument
  191.         K (A,B,C,D,EF(10)),^ZZZ
  192.         K @A ; using argument indirection is possible
  193.  
  194.  
  195. LOCK__
  196. LOCK_<glvn>[timeout]
  197. LOCK_(<glvn>[,<glvn>]*)[timeout]
  198.         - may be post-conditionalised
  199.         - argument listing is possible
  200.         - argument indirection is allowed
  201.         - arguments cannot be post-conditionalised
  202.  
  203.         All LOCK forms release all previously locked variables. A LOCK with
  204.         arguments stores all it's arguments in the partitions LOCK-list,
  205.         unless a timeout is specified and it was impossible to satisfy the
  206.         LOCK; the $T switch is then set to 0, afterwards. If a timeout was
  207.         specified and it WAS possible to satisfy the LOCK, then $T is set to
  208.         1 afterwards. A LOCK can be satisfied if all the arguments do NOT
  209.         violate the "descendant-exclusivity-rule" for any other variables in
  210.         the LOCK lists of ALL the other partitions. One variable violates
  211.         the "descendant-exclusivity-rule" if it is a 'prefix' of the other
  212.         variable, or the other variable is a prefix of the one variable. In
  213.         other words, they may not 'interfere' with each other. The LOCK
  214.         command ensures that no two processes modify the same data (or
  215.         datatree-branch) at the 'same' time.
  216.         *Note: LOCK does not provide protection against modification of
  217.         the same information by two processes. It merely provides a
  218.         mechanism by which clashes can be avoided.
  219.  
  220.  
  221. OPEN_<device>[:[<device parameters><timeout>|<timeout>]]
  222.         - may be post-conditionalised
  223.         - argument listing is possible
  224.         - argument indirection is allowed
  225.         - arguments cannot be post-conditionalised
  226.  
  227.         For the syntax and meaning of the device parameters, look at the
  228.         "DEVICE"-entrypoint in the "MUMPS TERMINOLOGY" chapter.
  229.         The parameters are specified as follows: (<par>[:<par>]*)
  230.         OPEN tries to open the specified device(s) in the argument list. To
  231.         open a device, no other partition may have that device in it's
  232.         "open-list" (when a device is succesfully opened, it is put in the
  233.         partition's "open-list"). If a device cannot be opened, execution is
  234.         stopped until that device can be opened. Unless there's a timeout
  235.         (say t), in which case execution is only stopped for a maximum of
  236.         t seconds. If the device could not be opened after t seconds, the $T
  237.         switch is given the value 0 (zero), otherwise it is given the value
  238.         1 (one).
  239.  
  240.         EXAMPLES:
  241.         O 1:("FILE"_I:"W")
  242.         PRT O 11::1 I '$T W *7,"Printer in use, try again N//" R R Q:R="N" G PRT
  243.         O DEV U DEV W !,"Hi there, device DEV !" U 0 C DEV
  244.  
  245.  
  246. PRINT
  247.         Print prints out the current routine
  248.  
  249.  
  250. QUIT
  251.         - may be post-conditionalised
  252.  
  253.         QUIT is used to terminate a DO a XECUTE or a FOR command. If a QUIT
  254.         command is executed in a FOR loop, it terminates the FOR loop.
  255.         Execution proceeds with the 'next FOR' of the FOR loop to the left
  256.         of the terminated FOR, or with the nextline if there's no FOR to the
  257.         left of the terminated FOR.
  258.  
  259.         EXAMPLES:
  260.         F I=1:1 D TEST Q:I>TEST  W I ; Write I until I>TEST
  261.         R A G:A="AGAIN" START Q:A="QUIT"  W !,"'AGAIN' OR'QUIT',PLEASE !"
  262.         F I=1:1:3 F I=1:1:3 Q:J>I  W $J(J,2) ; Write "1 1 2 1 2 3"
  263.  
  264.  
  265. READ_<string>
  266.      |<format>
  267.      |<locvar>[<readcount>][<timeout>]
  268.      |*<locvar>[<timeout>]
  269.         <readcount>::= #<integer expression>
  270.         <format>: see MUMPS TERMINOLOGY
  271.         - may be post-conditionalised
  272.         - argument listing is possible
  273.         - argument indirection is allowed
  274.         - arguments cannot be post-conditionalised
  275.  
  276.         READ is used for I/O using the current device. The first form
  277.         outputs the string to the current device (if that's possible,
  278.         otherwise an error will occur). The second form is explained under
  279.         the "FORMAT" entry in "MUMPS TERMINOLOGY".
  280.         The third form reads characters from the current device and puts the
  281.         resulting string in the local variable. If a <readcount> is present
  282.         (say r), a maximum of r characters is read. If a timeout is present
  283.         (say t), reading is terminated after t seconds (or when a READ
  284.         terminator is received before that time).
  285.         The fourth form reads exactly one character and puts the ASCII value
  286.         of that character as an integer result in the local variable. Again,
  287.         a timeout (say t) may be specified, and -1 is the value if no
  288.         character was read in t seconds.
  289.  
  290.         EXAMPLES:
  291.         R R
  292.         R @A
  293.         ASK R !,"A,B,C or D",*ANS G A:ANS=65,B:ANS=66,C:AND=67,D:ANS=68,ASK
  294.         R !,NAME#32,!,STREET#32,!,CITY#32
  295.         READ D:0 IF D'=-1 D @$S(R=65:UP,R=90:DOWN,1:DEFAULT)
  296.  
  297.  
  298. SET_$P(...)=<expression>
  299.     | <glvn>=<expression>
  300.     | (<glvn>[,<glvn>]*)=<expression>
  301.         - may be post-conditionalised
  302.         - argument listing is possible
  303.         - argument indirection is allowed
  304.         - arguments cannot be post-conditionalised
  305.  
  306.         SET sets (values of) local or global variables. The first form of the
  307.         set argument is used for setting a $P of a local or global (see
  308.         $PIECE). The second form sets just one variable. The third form
  309.         conceptually sets all named variables at the same time, i.e. it's an
  310.         atomic action. SET evaluates any indirections or subscripts first,
  311.         then evaluates the <expression>, and finally sets the variable(s).
  312.         This is significant if you're using a Naded Indicator, because any
  313.         arguments may change the naked indicator before the full
  314.         variablename is evaluated.
  315.  
  316.         EXAMPLES:
  317.         S A=1
  318.         S @A=9 ; Gives B the value 9 if A="B"
  319.         S @A ; Gives B the value 10 if A="B=9"
  320.         S:NEWHS (X(1),^SCORE($I),Y($I,"score"))=SCORE
  321.         S ^C("A","B")="Hi",^D("HUIB")="VERWEIJ",^(^("HUIB))=^C("A","B")
  322.         ; An example of indirection:
  323.         ; ^(^("HUIB")) expands/evaluates to: ^C("A","VERWEIJ")
  324.         ; First the argument ^("HUIB") is evaluated: "VERWEIJ".
  325.         ; Then the expression ^C("A","B") which sets the naked indicator to
  326.         ; ^C("A").
  327.         ; Then the 'name' of ^(^(3)) is evaluated and the use of the naked
  328.         ; indicator expands ^("VERWEIJ") into ^C("A","VERWEIJ").
  329.  
  330.  
  331. USE_<expression specifying a device>[:<device parameters>]
  332.         <device parameters> ::= <expression> |
  333.                                 (<expression>[:<expression>]*)
  334.         - may be post-conditionalised
  335.         - argument listing is possible
  336.         - argument indirection is allowed
  337.         - argument cannot be post-conditionalised
  338.  
  339.         After opening a device using OPEN i/o may be directed to the device
  340.         using the USE command.
  341.  
  342.         EXAMPLES:
  343.         O 1:("VARS":"R") F  U 1 R VAR,VAL C:VAR="" 1 Q:VAR=""  S @VAR=VAL
  344.         ; read variables from file "VARS"
  345.         O 0:(2:0) ; Input not echoed in Archimedes MUMPS
  346.         U:WRITE DEV ; Post conditions can be used
  347.  
  348.  
  349. VIEW_<expression>[:(<expression>[:<expression>]*)]
  350.         - may be post-conditionalised
  351.         - argument listing is not possible
  352.         - argument indirection is not allowed
  353.         - argument cannot be post-conditionalised
  354.  
  355.         In Archimedes MUMPS, the VIEW command has no meaning whatsoever.The
  356.         VIEW command just eats all its arguments and so may set the naked
  357.         indicator, but no other actions take place.
  358.         WARNING: The VIEW command is not portable and should only be used in
  359.         system specific routines.
  360.  
  361.  
  362. WRITE__
  363. WRITE_<format>
  364.      |<expression>
  365.      |*<integer expression>
  366.         <format>: see MUMPS TERMINOLOGY
  367.         - may be post-conditionalised
  368.         - argument listing is possible
  369.         - argument indirection is allowed
  370.         - arguments cannot be post-conditionalised
  371.  
  372.         WRITE is the PRINT/printf command of MUMPS. It outputs the values
  373.         evaluated to the current device. The third form of the argument
  374.         outputs the ASCII character corresponding to the integer
  375.         interpretation of the <expression>.
  376.         The argumentless form of WRITE is not standard MUMPS, but 'all'
  377.         implementations use it to list the local variables, Archimedes MUMPS
  378.         is no exception.
  379.  
  380.         EXAMPLES:
  381.         W #!?35,"Main Menu" S X=10,Y=5 W@POSC
  382.         ; POSC="*31,*X-1,*Y-1", it positions the cursor in RISC OS
  383.         I ERR W *7," error "
  384.         W @A
  385.         W:OUTPUT A1,A2,A3,@B ; Postconditionalise the command
  386.  
  387.  
  388. XECUTE_<expression>
  389.         - may be post-conditionalised
  390.         - argument listing is possible
  391.         - argument indirection is allowed
  392.         - arguments can be post-conditionalised
  393.  
  394.         XECUTE interprets the <expression> as if it were MUMPS code.
  395.  
  396.         EXAMPLES:
  397.         X ^% ; invoke the editor
  398.         X "W 12*12" ; Output "144"
  399.         S X="X X" X X ; Run out of stack space
  400.         X "ZL @%ROU W $T(+1)" ; Write first line of routine @%ROU
  401.  
  402. /* end of Commands */
  403.