Provides routine information.
Description
You can use the ^$ROUTINE structured system variable as an argument to the $DATA, $ORDER, and $QUERY functions to return routine information from the current namespace (the default) or a specified namespace. ^$ROUTINE returns routine information on the OBJ code version of the routine.
In InterSystems ObjectScript, a routine exists in three code versions: MAC (user-written code, which may include macro pre-processor statements); INT (compiled MAC code, which performs macro preprocessing), and OBJ (executable object code). You can use the ^ROUTINE global to return information on the INT code version. You can use ^$ROUTINE to return information on the OBJ code version.
Examples
The following are examples of using ^$ROUTINE as an argument to the $DATA, $ORDER, and $QUERY functions.
As an Argument to $DATA
$DATA(^$|nspace|ROUTINE(routine_name))
^$ROUTINE as an argument to $DATA returns an integer value that specifies whether the routine_name OBJ code version exists as a node in ^$ROUTINE. The integer values that $DATA can return are shown in the following table.
Value |
Meaning |
0 |
Routine name does not exist |
1 |
Routine name exists |
The following Terminal example tests for the existence of the OBJ code version of the myrou routine. This example assumes that there is a compiled MAC routine named myrou in the USER namespace:
USER>WRITE ^ROUTINE("myrou",0,"GENERATED") // INT code version exists
1
USER>WRITE $DATA(^$ROUTINE("myrou")) // OBJ code version exists
1
USER>KILL ^rOBJ("myrou") // Kills the OBJ code version
USER>DO ^myrou
DO ^myrou
^
<NOROUTINE> *myrou
USER>WRITE ^ROUTINE("myrou",0,"GENERATED") // INT code version exists
1
USER>WRITE $DATA(^$ROUTINE("myrou")) // OBJ code version does not exist
0
USER>
As an Argument to $ORDER
$ORDER(^$|nspace|ROUTINE( routine_name),direction)
^$ROUTINE as an argument to $ORDER returns the next or previous routine name in collating sequence to the routine name you specify. If no such routine name exists as a node in ^$ROUTINE, $ORDER returns a null string.
The direction argument specifies whether to return the next or the previous routine name: 1=next, -1=previous. If you do not provide a direction argument, InterSystems IRIS returns the next routine name in collating sequence to the one you specify. For further details, refer to the $ORDER function.
The following subroutine searches the USER namespace and stores the routine names in a local array named ROUTINE.
SET rname=""
FOR I=1:1 {
SET rname=$ORDER(^$|"USER"|ROUTINE(rname))
QUIT:rname=""
SET ROUTINE(I)=rname
WRITE !,"Routine name: ",rname
}
WRITE !,"All routines stored"
QUIT
As an Argument to $QUERY
$QUERY(^$|nspace|ROUTINE(routine_name))
^$ROUTINE as an argument to $QUERY returns the next routine name in collating sequence to the routine name you specify. The specified routine name does not have to exist. If there is no routine name later in the collating sequence, $QUERY(^$ROUTINE) returns a null string.
In the following example, two $QUERY functions return the next routine after the specified routine name in the USER namespace.
SET rname=""
WRITE !,"1st routine: ",$QUERY(^$|"USER"|ROUTINE(rname))
SET rname="%m"
WRITE !,"1st ",rname, " routine: ",$QUERY(^$|"USER"|ROUTINE(rname))
QUIT