$QLENGTH (ObjectScript)

Synopsis

$QLENGTH(varname)
$QL(varname)

Description

$QLENGTH returns the number of subscript levels in varname. $QLENGTH simply counts the number of subscript levels specified in varname. The top-level varname variable does not have to be defined for $QLENGTH to return the number of subscript levels.

Argument

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 $QLENGTH("^|""SAMPLES""|myglobal(1,4,6)")
 write $QLENGTH("^|""^""|myglobal(3,6)")

$QLENGTH does not check whether the specified namespace exists or whether the user has access privileges for the namespace.

A varname 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 2

The 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 3

The 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 3

See Also

• $QUERY function

• $QSUBSCRIPT function

• $NAME function

• $ZREFERENCE special variable

• Formal Rules about Globals