Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

$QSUBSCRIPT (ObjectScript)

Returns a variable name or a subscript name.

Synopsis

$QSUBSCRIPT(varname,intexpr)
$QS(varname,intexpr)

Arguments

Argument Description
varname An expression that evaluates to the name of a variable, with or without subscripts.
intexpr An expression that evaluates to an integer code; this specifies which name to return: variable name, subscript name, or namespace name.

Description

$QSUBSCRIPT returns the variable name, or the value of a specified subscript of varname, depending on the value of intexpr. If varname is a global variable, you can also return the namespace name, if it was explicitly specified. $QSUBSCRIPT does not return a default namespace name.

Arguments

varname

An expression that evaluates to a string, which specifies a variable. It can be a local variable, a process-private global, or a global variable.

If the string is a global reference, varname can be an extended global reference. In this case, because varname is a quoted string, the quotes around the namespace reference must be doubled to be parsed correctly as literal quotation marks. The following shows two examples:

 write $QSUBSCRIPT("^|""SAMPLES""|myglobal(1,4,6)",1)
 write $QSUBSCRIPT("^|""^""|myglobal(3,6)",1)

A varname must reference a variable name in canonical form (a fully expanded reference). To use $QSUBSCRIPT with a naked global reference, or with indirection, you can use the $NAME function to return the corresponding fully expanded reference.

intexpr

An integer expression code that indicates which value to return. Assume that the namevalue argument has the form NAME(s1,s2,...,sn), where n is the ordinal number of the last subscript. The intexpr argument can have any of the following values:

Code Return Value
< -1 Generates a <FUNCTION> error; these numbers are reserved for future extensions.
-1 Returns the namespace name if a global variable namevalue includes one; otherwise, returns the null string ("").
0 Returns the variable name. Returns ^NAME for a global variable, and ^||NAME for a process-private global variable. Does not return a namespace name.
<=n Returns the subscript value for the level of subscription specified by the integer n, with 1 being the first subscript level and n being the highest defined subscript level.
>n An integer > n returns the null string (""), where n is the highest defined subscript level.

Examples

The following example returns $QSUBSCRIPT values when namevalue is a subscripted global with one subscript level and a specified namespace:

   SET global="^|""account""|%test(""customer"")"
   WRITE !,$QSUBSCRIPT(global,-1)  ; account
   WRITE !,$QSUBSCRIPT(global,0)   ; ^%test
   WRITE !,$QSUBSCRIPT(global,1)   ; customer
   WRITE !,$QSUBSCRIPT(global,2)   ; null string

The following example returns $QSUBSCRIPT values when namevalue is a process-private global with two subscript levels. The $ZREFERENCE special variable contains the name of the most recently referenced variable.

   SET ^||myppg(1,3)="apples"
   WRITE !,$QSUBSCRIPT($ZREFERENCE,-1)  ; null string
   WRITE !,$QSUBSCRIPT($ZREFERENCE,0)   ; ^||myppg
   WRITE !,$QSUBSCRIPT($ZREFERENCE,1)   ; 1
   WRITE !,$QSUBSCRIPT($ZREFERENCE,2)   ; 3

The following example returns the $QSUBSCRIPT value for a global variable specified as a naked global reference. The $NAME function is used to expand the naked global reference to canonical form:

   SET ^grocerylist("food","fruit",1)="apples"
   SET ^(2)="bananas"
   WRITE !,$QSUBSCRIPT($NAME(^(2)),2)   ; returns "fruit"

See Also

$QUERY (ObjectScript)Next section
Previous section$QLENGTH (ObjectScript)
FeedbackOpens in a new tab