Do

The DO command makes an entry in the GT.M invocation stack and transfers execution to the location specified by the entryref.

The format of the DO command is:

D[O][:tvexpr] [entryref[(expr|.lvn[,...])][:tvexpr][,...]]

An explicit or implicit QUIT within the scope of the DO, but not within the scope of any other DO, FOR, XECUTE, or extrinsic, returns execution to the instruction following the calling point. This point may be the next DO argument or another command. At the end of a routine, or the end of a nesting level created by an argumentless DO, GT.M performs an implicit QUIT. Any line that reduces the current level of nesting by changing the number of leading periods (.) causes an implicit QUIT, even if that line only contains a comment. Terminating the image and execution of ZGOTO commands are the only ways to avoid eventually returning execution to the calling point.

A DO command may optionally pass parameters to the invoked subroutine. For more information about entryrefs and parameter passing, refer to Chapter 5: “General Language Features of M.

Examples of DO

Example:

GTM>DO ^%RD

This example invokes the routine directory utility program (%RD) from Direct Mode. The caret symbol (^) specifies that the DO command invokes %RD as an external routine.

Example:

GTM>DO A(3)

This example invokes the subroutine at label A and passes the value 3 as a parameter. The DO argument does not have a caret symbol (^), therefore, it identifies A as a label in the current routine.

Example:

ReportA ; Label for ReportA
        SET di="" OPEN outfile USE outfile 
        FOR  SET di=$ORDER(^div(di)) QUIT:di=""  DO PREP DO  DO POST
        .SET de="",(nr,gr)=0
        .WRITE "Division ",di,! F   S de=$ORDER(^de(di,de)) QUIT:de=""   DO
        ..WRITE "Department ",de," Gross Rev: ",^grev(di,de),!
        ..WRITE "Department ",de," Net Rev: ",^nrev(di,de),!
        ..SET gr=gr+^grev(di,de),nr=nr+^nrev(di,de)
        .W "Division Gross Rev: ",gr,!,"Division Net Rev: ",nr,!
         DO PRINT^OUTPUT(outfile)
         QUIT

This routine first uses a DO with a label argument (PREP) to do some pre-processing. Then, it uses an argumentless DO to loop through each division of a company to format a report. Within the first argumentless DO, a second argumentless DO (line 4) loops through and formats each department within a division. After the processing of all departments, control returns to the first argumentless DO, which prints a summary of the division. Following processing of all divisions, a DO with a label argument (POST) does some post-processing. Finally, at the next-to-last line, the routine uses a DO that invokes a subroutine at a label (PRINT) in an external routine (^OUTPUT), passing the name of the output file (outfile) as a parameter.

Example:

GTM>zprint ^SQR
SQR(z);
  set revert=0
  if $view("undef") set revert=1 view "noundef"
  if z="" write "Missing parameter.",!     view:revert "undef" quit
  else  write z*z,! view:revert "undef" quit  
GTM>do ^SQR(10)
100
GTM>do ^SQR
Missing parameter.

This examples demonstrates label invocations using DO with and without parentheses.