^$ROUTINE (ObjectScript)
Synopsis
^$|nspace|ROUTINE(routine_name)
^$|nspace|R(routine_name)
Arguments
Argument | Description |
---|---|
|nspace| or [nspace] |
Optional — An extended SSVN reference, either an explicit namespace name or an implied namespace. Must evaluate to a quoted string, which is enclosed in either square brackets (["nspace"]) or vertical bars (|"nspace"|). Namespace names are not case-sensitive; they are stored and displayed in uppercase letters. |
routine_name | An expression that evaluates to a string containing the name of a routine. |
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.
Arguments
nspace
This optional argument allows you to specify a global in another namespace by using an extended SSVN reference. You can specify the namespace name either explicitly, as a quoted string literal or as a variable, or by specifying an implied namespace. Namespace names are not case-sensitive. You can use either bracket syntax ["USER"] or environment syntax |"USER"|. No spaces are allowed before or after the nspace delimiters.
You can test whether a namespace is defined by using the following method:
WRITE ##class(%SYS.Namespace).Exists("USER"),! ; an existing namespace
WRITE ##class(%SYS.Namespace).Exists("TESTNAMESPACE1") ; a non-existent namespace
You can use the $NAMESPACE special variable to determine the current namespace. The preferred way to change the current namespace is NEW $NAMESPACE then SET $NAMESPACE="nspacename".
routine_name
An expression that evaluates to a string containing the name of an existing routine. A routine name must be unique within the first 255 characters; routine names longer than 220 characters should be avoided.
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
See Also
-
$DATA function
-
$ORDER function
-
$QUERY function
-
$NAMESPACE special variable