Caché MultiValue Basic Reference
EXECUTE
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Executes a MultiValue command from within a program, passing and returning values.
Synopsis
Use any of the following three syntactical forms:
EXECUTE command 
                   [CAPTURING {dynarray | NULL} |  OUTPUT oref]
                   [PASSLIST [dynarray]] 
                   [RTNLIST var] 
                   [{SETTING | RETURNING} dynarray]

EXECUTE command 
                   [ , IN < expression] 
                   [ , OUT > var]
                   [ , SELECT[ (list) ] < dynarray]
                   [ , SELECT[ (list) ] > var]
                   [ , PASSLIST[ (dynarray) ]]
                   [ , STATUS > var]

EXECUTE command 
                   [ ,//IN. < expression] 
                   [ ,//OUT. > var]
                   [ ,//SELECT.[ (list) ] < dynarray]
                   [ ,//SELECT.[ (list) ] > var]
                   [ ,//PASSLIST.[ (dynarray) ]]
                   [ ,//STATUS. > var]
Arguments
command One or more MultiValue commands, each command specified as a quoted string. A string can be quoted using single quotes ('cmd arg'), double quotes ("cmd arg"), or backslashes (\cmd arg\). To specify multiple commands, separate the commands with a Field Mark ("cmd1 arg":@FM:"cmd2 arg").
var A variable used to hold a value.
dynarray A dynamic array.
oref An object reference. The corresponding class must have (at minimum) a WriteLine() method (which inserts a newline at the end of the write operation) and a Write() method (which does not insert a newline).
Description
The EXECUTE command executes the specified Caché MultiValue command(s), then returns execution to the next MVBasic statement following the EXECUTE. It initially searches the VOC for the command; if the command is not found in the VOC, it searches the global catalog. For lookup details, refer to CATALOG in the Caché MultiValue Commands Reference.
The first syntactical form supports the following optional clauses:
The second and third syntactical forms support the following optional clauses:
EXECUTE, PERFORM, and CHAIN
The EXECUTE command executes one or more MultiValue commands from within MVBasic, then returns execution to the next MVBasic statement. EXECUTE can pass values to the MultiValue command(s) and return values from the MultiValue command(s).
The PERFORM command executes one or more MultiValue commands from within MVBasic, then returns execution to the next MVBasic statement. PERFORM cannot pass or return values.
The CHAIN command executes a single MultiValue command from within MVBasic. It does not return execution to MVBasic. CHAIN cannot pass values.
Emulation
In Reality emulation, EXECUTE executes all stacked data, regardless of list status. In Caché and all other emulations, only the EXECUTE command argument is executed. For all emulations (except Reality) EXECUTE either clears or maintains stacked data on the DATA queue, depending on the STACK.GLOBAL option.
EXECUTE supports the STACK.GLOBAL option, which can be set using $OPTIONS. When STACK.GLOBAL is on, EXECUTE does not clear unused items from the DATA queue upon completion. By default, STACK.GLOBAL is on for Caché, and for UniVerse, UniData, PICK, Prime, PIOpen, and IN2 emulations. STACK.GLOBAL is off for all other emulations.
In jBASE emulation, the RTNLIST clause returns the select list expanded to a dynamic array. All other emulations return the select list name. The PASSLIST clause requires that the select list be designated as external. This external select list bit setting is only used for jBASE emulation.
EXECUTE supports the RETURNING.CODE option, which can be set using $OPTIONS.
In UniData and UDPICK emulations, a command name with an initial character of * is handled as a global name. EXECUTE removes the leading * and then looks up the resulting command name in the global catalog in SYS.MV, rather than looking up in the VOC. If the runtime environment is not a UniData emulation, a normal VOC lookup is done on the *command name.
Invoking Other Command Shells
You can use the $XECUTE command to issue a ObjectScript command from within Caché MVBasic.
You can use the PCPERFORM command to issue an operating system command from within Caché MVBasic.
Examples
The following example issues the MultiValue LISTME command, captures its output in the dynamic array variable currusers and then returns execution to the MVBasic program:
PRINT TIME()
EXECUTE "LISTME" CAPTURING currusers
PRINT TIME()
PRINT currusers
The following example shows how to use EXECUTE to execute multiple MultiValue commands:
PRINT TIME()
EXECUTE "SLEEP 2":@FM:"SLEEP 3"
PRINT TIME()
This following example directs output to a sequential file using the OUTPUT clause. It uses the standard Caché-supplied %Stream.FileCharacter class, which uses an operating system file as temporary storage. The location of the file is determined by the class itself, although a method allows you to override the default location. This example uses the default location. Once the object is closed, the temporary file is deleted. In this example, the size of the output from the LIST command is limited only by the maximum size of the file:
* Execute the LIST command to an object.
* 
oref = "%Stream.FileCharacter"->%New() 
EXECUTE "LIST BIGFILE ID-SUPP A1 SAMPLE 100" OUTPUT oref 
* 
* Read back that object, one line at a time. 
* 
oref->Rewind() 
lineno = 1 
LOOP WHILE oref->AtEnd = 0 DO 
line = oref->ReadLine() 
PRINT lineno "R%4":": " : OCONV(line,"MCP") 
lineno = lineno + 1 
REPEAT
The following example uses an OUTPUT clause with a user-defined MVExecute.Output class:
0001: oref = "MVExecute.Output"->%New() 
0002: EXECUTE "LIST BIGFILE ID-SUPP A1 SAMPLE 100" OUTPUT oref 
0003: * 
0004: * Read back that object, one line at a time. 
0005: * 
0006: LineCount = oref->LineCount 
0007: PRINT "Line count = ":LineCount 
0008: FOR I = 1 TO LineCount 
0009: PRINT I "R%4" : ": " : oref->ReadLine(I) 
0010: NEXT I
The following is the definition of this user-defined MVExecute.Output class. It contains the required Write() and WriteLine() methods, and a ReadLine() method:
Class MVExecute.Output Extends %Persistent 
{ 

Property LineCount As %Integer; 

Property Lines As array Of %String; 

Method Write(line As %String) As %Integer [ Language = mvbasic ] 
{ 
    IF NOT(@ME->LineCount) THEN 
        @ME->LineCount = 1 
        dummy = @ME->Lines->SetAt("",1) 
    END 
    LineNew = @ME->Lines->GetAt(@ME->LineCount) : line 
    dummy = @ME->Lines->SetAt(LineNew , @ME->LineCount) 
    RETURN 0 
} 

Method WriteLine(line As %String) As %Integer [ Language = mvbasic ] 
{ 
    IF NOT(@ME->LineCount) THEN 
        @ME->LineCount = 1 
        dummy = @ME->Lines->SetAt("",1) 
    END 
    LineNew = @ME->Lines->GetAt(@ME->LineCount) : line 
    dummy = @ME->Lines->SetAt(LineNew , @ME->LineCount) 
    @ME->LineCount = @ME->LineCount + 1 
    RETURN 0 
} 

Method ReadLine(LineNumber As %Integer) As %String [ Language = mvbasic ] 
{ 
    IF LineNumber LE 0 OR LineNumber GT @ME->LineCount THEN RETURN "??" 
    RETURN @ME->Lines->GetAt(LineNumber) 
} 

}
See Also