$XECUTE (ObjectScript)
Synopsis
$XECUTE(code,paramlist)
Arguments
Argument | Description |
---|---|
code | An expression that resolves to a valid ObjectScript command line, specified as a quoted string. A command line can contain one or more ObjectScript commands. The final command must be an argumented QUIT. |
paramlist | Optional — A list of parameters to be passed to code. Multiple parameters are separated by commas. |
Description
The $XECUTE function allows you to execute user-written code as a function, supplying passed parameters and returning a value. The code argument must evaluate to a quoted string containing one or more ObjectScript commands. The code execution must conclude with a QUIT command that returns an argument. InterSystems IRIS then returns this QUIT argument as the $XECUTE return code value.
You can use the paramlist argument to pass parameters to code. If you are passing parameters, there must be a formal parameter list at the beginning of code. Parameters are specified positionally. There must be at least as many formal parameters listed in code as there are actual parameters specified in paramlist.
You can use the CheckSyntax()Opens in a new tab method of the %Library.RoutineOpens in a new tab class to perform syntax checking on code.
Each invocation of $XECUTE places a new context frame on the call stack for your process. The $STACK special variable contains the current number of context frames on the call stack.
The $XECUTE function performs substantially the same operation as the XECUTE command, with the following differences: The $XECUTE function does not support postconditionals or the use of multiple command line arguments. The $XECUTE function requires every execution path to end with an argumented QUIT; the XECUTE command neither requires a QUIT nor permits an argumented QUIT.
Arguments
code
An expression that evaluates to a valid ObjectScript command line, specified as a quoted string. The code string must not contain a tab character at the beginning or a <Return> at the end. The string can be no longer than a valid ObjectScript program line. The code string must contain a QUIT command that returns an argument at the conclusion of each possible execution path.
If $XECUTE passes parameters to code, the code string must begin with a formal parameter list. A formal parameter list is enclosed in parentheses; within the parentheses, parameters are separated by commas.
paramlist
A list of parameters to pass to code, specified as a comma-separated list. Each parameter in paramlist must correspond to a formal parameter within the code string. The number of parameters in paramlist may be less than or equal to the number of formal parameters listed in code.
You can use a dot prefix to pass a parameter by reference. This is useful for passing a value out from code. An example is provided below. For further details, refer to Passing by Reference.
Examples
In the following example, the $XECUTE function executes the command line specified in cmdline. It passes two parameters, num1 and num2 to this command line.
SET cmd="(dvnd,dvsr) IF dvsr=0 {QUIT 99} ELSE {SET ^testnum=dvnd/dvsr QUIT 0}"
SET rtn=$XECUTE(cmd,num1,num2)
IF rtn=99
{WRITE !,"Division by zero. ^testnum not set"}
ELSE
{WRITE !,"global ^testnum set to",^testnum}
The following example uses passing by reference (.y) to pass a local variable value from the code to the invoking context.
CubeIt
SET x=7
SET rtn=$XECUTE("(in,out) SET out=in*in*in QUIT 0",x,.y)
IF rtn=0 {WRITE !,x," cubed is ",y}
ELSE {WRITE !,"Error code=",SQLCODE}
The following example shows how $XECUTE increments the $STACK special variable. This example either writes the $STACK value from within $XECUTE, or has $XECUTE invoke the XECUTE command, which writes the $STACK value:
StackIt
SET stackit=$RANDOM(3)
IF stackit=0 {GOTO StackIt}
WRITE "initial stack level ",$STACK,!
SET cmd="(stackit) IF stackit=1 {WRITE ""stack is "",$STACK,! QUIT 1} "_
"ELSEIF stackit=2 {WRITE ""stack is "",$STACK XECUTE ""WRITE """" stack is """",$STACK,!"" QUIT 1} "_
"ELSE { QUIT 0}"
SET rtn=$XECUTE(cmd,stackit)
IF rtn=1 { WRITE "return stack level ",$STACK }
ELSE {WRITE "unexpected value: rtn=",rtn}