Add metadata for subscripts
Final Release Note
Description
The current implementation only provides cross references, and optionally statistics, for values of nodes. However, both types of metadata are useful for second and subsequent subscripts, and statistics are meaningful for first subscripts (cross references are not meaningful for first subscripts as the subscripts allow nodes to be referenced directly in order without needing cross references).
YottaDB/DBMS/YDBOcto#660 can make use of this enhancement.
Initial Release Note
The *SUB()
functions are an API to manage metadata for subscripts, just as the *DATA()
functions manage metadata for values at nodes.
XREFSUB(gbl,xsub,nmonly,omitfix,stat,type)
Create subscript metadata for subscript of a global variable, including triggers to maintain that subscript.
Parameters
-
gbl
is the global variable name, e.g.,"^ABC"
-
xsub
is a specification of the subscripts that precede the subscript to be cross referenced. To compute metadata for the nth subscript (n>1), the first n-1 subscripts must be specified, e.g., if the fifth subscript of the global variable is to be cross referenced,xsub
must specify the first four subscripts. There are three cases:-
xsub
has a positive integer value at the root, and no subtrees (i.e., $DATA(xsub) is 1): The value specifies the level (number of subscripts) of the application global variable in the cross reference (i.e., n-1), with all subscripts at each level to be included. In this case, the actual parameter can be a literal or a variable passed by value. In other cases it must be passed by reference. -
xsub
has no value at the root, but positive integer subscripts (1), (2), (3), etc. (i.e., $DATA(xsub) is 10): The subscripts of the local variable specify the values of the global variable subscript to be cross referenced, using the same syntax as for XREFDATA(). Any omitted intervening subscript (e.g., if the local variable has nodes (1) and (3) but not (2)), means that all subscripts at that level should be included in the cross reference. -
xsub
has both a value at the root, as well as positive integer subscripts (i.e., ($DATA(xsub) is 11): This is similar to the previous case, except that if the value at the root exceeds the last subscript, that is the level of the global variable to be cross referenced. For example, ifxsub
has nodes (1) and (3) but the value at the root is 5, five subscripts of the global variable will be in the cross reference of the sixth subscript. A value at the root smaller than the last subscript is ignored, so with the subscripts above and a value of 2 at the root, three subscripts will be in the cross reference.
Other cases (e.g., non integer subscripts of xsub) raise errors.
-
-
nmonly
, if 1, means just return the metadata global variable name but don't set triggers or compute metadata. This allows code to be written to use metadata without the need to use indirection, allowing the metadata to be computed at run-time only when needed. -
omitfix
, if 1 instructs XREFDATA() to omit from the subscripts of the cross reference any subscripts of the application global that are fixed constants because the code to traverse the application global using the cross reference will include those known fixed subscripts when making the access. If not specified, omitfix defaults to 1. Note that at least one of then-1
subscripts must be variable; all of them cannot be fixed. -
stat
if 1 or 2 specifies whether the metadata should include statistics. The default is only cross references with no statistics. -
type
is reserved for future enhancements. It is ignored.
Return value: name of global variable with cross reference e.g., "^%ydbAIMSZzUmfwxt80MHPiWLZNtq4", a prefix of "^%ydbAIMS" followed by a 128-bit hash derived from the parameters. The subscripts of cross reference variables are (value,sub[,sub]) where value
is the value of the nth subscript, and sub
values are the preceding n-1
subscripts other than those which have been omitted because they are constants because omitfix=1
.
Just as cross references are metadata for application global subscripts, metadata for the cross reference global variables are stored in nodes of the metadata global variable as follows:
-
the root node is the application global variable name; subscripted nodes are:
-
("") if
stat
is 2, this contains the number of different values of the nth subscript -
(0) space separated $zut, $job, $zyrelease, metadata format version number
-
(1) number of subscripts of the application global variable in the metadata (
n-1
) -
(6) SET trigger for this metadata
-
(7) KILL trigger for this cross reference; see also comment for (12) below
-
(8) ZKILL trigger for this cross reference
-
(9) 1 means that omitting fixed subscripts was requested, whether or not any subscripts were actually omitted
-
(10) if 1 or 2 means that statistics are maintained, as specified by the
stat
parameter -
(11) if
stat
is 2, this contains the total number of nodes being tracked -
(12) & up - triggers for KILLs of higher level nodes. Until YDB is enhanced to invoke at lower levels of the tree when a higher level node is KILLed. YDBAIM creates triggers documented in nodes (12) and up for levels of the tree above the one for which YDBAIM maintaine metadata. The trigger described in (7) also does a recursive traversal of the tree below. Once the YDB#659 enhancement is implemented, the triggers in nodes (12) and up are not required, and the KILL trigger in (7) can be simplified, and potentially merged with the ZKILL trigger in (8).
Since the number of nodes in the metadata global are known (one for the value of the nth subscript, n-1 for other subscripts, less fixed subscripts for omitfix=1
(say this number is m), if stat
is 1 or 2, statistics are maintained in nodes whose first subscript is the value, followed by m+1 additional subscripts all with the empty string as their value., e.g., for an application global variable ^USPresidents() whose first subscript is the year a former US President took office and the second subscript is the year that President left office, so that metadata for the second subscript consists of the year a former President left office followed by the year that President took office (i.e., m is 1), for stat=1
or stat=2
^%ydbAIMSZzUmfwxt80MHPiWLZNtq4(1841,"","")=2
because two Presidents left office in 1841. The corresponding cross reference nodes would be ^%ydbAIMSZzUmfwxt80MHPiWLZNtq4(1841,1837) and ^%ydbAIMSZzUmfwxt80MHPiWLZNtq4(1841,1841) for the application global variable nodes, corresponding to Martin Van Buren and William Henry Harrison respectively.
UNXREFSUB(gbl,xsub,nmonly,omitfix,stat,type)
Remove subscript metadata for a subscript of a global variable, including triggers to maintain that subscript.
Parameters:
The parameters are as described in the definition of XREFSUB(). All parameters are optional, and parameters nmonly
, stat
and type
are ignored. They are included in the API for symmetry with XREFSUB() as as potential support for application readability.
-
If none of
gbl
,xsub
, oromitfix
is specified, all subscript metadata is removed. -
If only
gbl
is specified:-
If it is an application global variable, all subscript metadata for that global variable are removed.
-
If it is an AIM metadata global variable, it and the metadata for the corresponding global variable, are removed.
-
-
If
gbl
andxsub
are specified, but notomitfix
, the default value ofomitfix
is 1, as with XREFSUB().
LSXREFSUB(lvn,[gbl])
List specified metadata, all cross references for a global variable, or all cross references
Parameters:
-
lvn
is a local variable passed by reference. In that local variable, the function describes metadata as follows:-
The first subscript is the metadata global variable name, e.g., "^%ydbAIMDgBPWsnL76HLyVnlvsrvE19". The value of that node (i.e., with a first subscript and no second subscript) is the application global variable name, e.g., "^xyz".
-
Nodes with positive integer second subscripts have metadata about the metadata. These are described with XREFSUB().
Nodes of lvn other than those corresponding to reported cross references remain unaltered.
-
-
gbl
is an optional global variable name. There are three cases:-
It is an application global variable name, e.g., "^USPresidents". In lvn, as described above, the function returns all cross references for that global variable.
-
It starts with "^%ydbAIMS". In lvn, the function returns information about the specified cross reference.
-
It is omitted or the empty string (""). In lvn, the function returns information about all cross references.
-
[#5]