$QLENGTH (ObjectScript)
Synopsis
$QLENGTH(var)
$QL(var)
Argument
| Argument | Description |
|---|---|
| var | A string, or expression that evaluates to a string, that contains the name of a variable. The variable name can specify no subscripts or one or more subscripts. |
Description
$QLENGTH returns the number of subscript levels in var. $QLENGTH simply counts the number of subscript levels specified in var. The var variable does not have to be defined for $QLENGTH to return the number of subscript levels.
Argument
var
A quoted string, or 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, var can specify an extended global reference by including a namespace name. Because var is a quoted string, the quotes around a namespace reference must be doubled to be parsed correctly as literal quotation marks. For example, "^|""SAMPLES""|myglobal(1,4,6)". The same applies to the quotes in a process-private global with "^" syntax. For example, "^|""^""|ppgname(3,6)". $QLENGTH does not check whether the specified namespace exists or whether the user has access privileges for the namespace.
A var must specify a variable name in canonical form (a fully expanded reference). To use $QLENGTH with a naked global reference, or with indirection, you can use the $NAME function to return the corresponding fully expanded reference.
Examples
The following example show the results of $QLENGTH when used with subscripted and unsubscripted globals. The first $QLENGTH takes a global with no subscripts and returns 0. The second $QLENGTH takes a global with two subscript levels and returns 2. Note that quotes found in the variable name are doubled because var is specified as a quoted string.
WRITE !,$QLENGTH("^|""USER""|test")
; returns 0
SET name="^|""USER""|test(1,""customer"")"
WRITE !,$QLENGTH(name)
; returns 2The following example returns the $QLENGTH value for a process-private global with three subscript levels. The $ZREFERENCE special variable contains the name of the most recently referenced variable.
SET ^||myppg("food","fruit",1)="apples"
WRITE !,$QLENGTH($ZREFERENCE) ; returns 3The following example returns the $QLENGTH value for a process-private global 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 !,$QLENGTH($NAME(^(2))) ; returns 3See Also
-
$QUERY function
-
$QSUBSCRIPT function
-
$NAME function
-
$ZREFERENCE special variable
