Caché ObjectScript Reference
^$ROUTINE
[Home] [Back] 
InterSystems: The power behind what matters   
Class Reference   
Search:    

Provides routine information.
Synopsis
^$|nspace|ROUTINE(routine_name)
^$|nspace|R(routine_name)
Parameters
or 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.
Parameters
nspace
This optional parameter 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("LOSER")   ; a non-existent namespace
 
You can use the $NAMESPACE special variable to determine the current namespace, and the ZNSPACE command to change the current namespace.
routine_name
An expression that evaluates to a string containing the name of a 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 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 example tests for the existence of a routine in the default namespace:
   XECUTE "ZREMOVE"
   XECUTE "ZSAVE ROU"
   WRITE !,$DATA(^$ROUTINE("^ROU"))
   XECUTE "ZSAVE ROU"
   WRITE !,$DATA(^$ROUTINE("^ROU"))
 
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. If you do not provide a direction argument, Caché 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