Class %ExtentMgr.Util

abstract class %ExtentMgr.Util

The Extent Manager maintains extent definitions and globals registered for use by those extents. Extent definitions most commonly originate from compiling a persistent class but can also be defined outside of any class. The Util class provides a public interface for deleting extent definitions and registering the extents of all managedextent classes or a single class.

In addition to the public interface implemented here, the %ExtentMgr tables are visible to SQL and can be queried directly. There are two examples implemented in %ExtentMgr.Util - GlobalUses and GlobalsUsed. Both are public class methods that return a single result set and both are projected as stored procedures and can be invoked by dynamic SQL, embedded SQL or through an xDBC client. These methods are more important as examples of how the %ExtentMgr tables can be queried. The primary global registry is modeled by %ExtentMgr.GlobalRegistry. That class contains just a few properties of interest: GlobalName, GlobalReference and UsedBy. The GlobalName is the unsubscripted global name, GlobalReference is the full global reference of the root global reference that is used by the UsedBy extent. Querying this class is trivial. UsedBy is a reference to %ExtentMgr.Catalog.Extent. The IDKEY of %ExtentMgr.Catalog.Extent is the extent name. The extent name is almost always the same as the class name followed by the extent type of ".cls". The GlobalsUsed method includes a sample query that returns all of the globals registered for use by a specified extent. To retrieve the globals used by Sample.Person, one could execute this dynamic SQL statement (using the SQL Shell)

select usedby->name as UsedByExtent, globalname, globalreference
  from %ExtentMgr.GlobalRegistry
 where usedby->name = 'Sample.Person.cls' order by globalreference

UsedByExtent		GlobalName		GlobalReference	
Sample.Person.cls	^Sample.PersonD	^Sample.PersonD
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("$Person")
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("NameIDX")
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("SSNKey")
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("ZipCode")

5 Rows(s) Affected

Inventory

Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
		11

Summary

Methods
DeleteAllExtentDefinitions	DeleteExtent	DeleteExtentDefinition	DeleteExtentDefinitionIfExists
DeleteGlobalReference	GlobalUses	GlobalsUsed	RegisterAllClasses
RegisterClass	RegisterCustomExtent	RegisterGlobalReference

Methods

• classmethod DeleteAllExtentDefinitions(display As %Integer = 0) as %Status

This method deletes all extent definitions from the catalog. No data is affected. If display is true then status messages will be displayed on the current device.

• classmethod DeleteExtent(extent As %String(MAXLEN=""), extentType As %String = "cls") as %Status

DEPRECATED - refer to DeleteExtentDefinition. Maintained for backward compatibility only.

• classmethod DeleteExtentDefinition(extent As %String(MAXLEN=""), extentType As %String = "cls") as %Status

DeleteExtentDefinition() will delete the extent metadata from the Extent Manager and remove all global registry entries that are registered for use by this extent. This method does not delete the extent data. Only the extent metadata is deleted.

• classmethod DeleteExtentDefinitionIfExists(extent As %String(MAXLEN=""), extentType As %String = "cls") as %Status

• classmethod DeleteGlobalReference(pReference As %String(MAXLEN="")="", Output pUsedBy As %ExtentMgr.Catalog.Extent) as %Status

DeleteGlobalReference will delete a registered global reference from the GlobalRegistry. If the reference was previously registered then it is deleted, the name of the extent it was registered for use by is returned in pUsedBy and the method succeeds. Otherwise, a failure status is returned.

• classmethod GlobalUses(pGlobalReference As %String(MAXLEN="")="") [ SQLProc ]

GlobalUses is a class method that returns a result set in a context object. This method is easily invoked as an SQL procedure. The single result set contains the global name, global reference and extent name that is using the global reference for the global reference passed in as the single argument.

SAMPLES>d ##class(%ExtentMgr.Util).GlobalUses("^Sample")

SAMPLES>d %sqlcontext.%Display()


Dumping result #1
GlobalName	GlobalReference	UsedByExtent	
^Sample.CompanyD	^Sample.CompanyD	Sample.Company.cls
^Sample.CompanyI	^Sample.CompanyI("NameIdx")	Sample.Company.cls
^Sample.CompanyI	^Sample.CompanyI("TaxIDIdx")	Sample.Company.cls
^Sample.PersonD	^Sample.PersonD	Sample.Person.cls
^Sample.PersonI	^Sample.PersonI("$Employee")	Sample.Employee.cls
^Sample.PersonI	^Sample.PersonI("$Person")	Sample.Person.cls
^Sample.PersonI	^Sample.PersonI("NameIDX")	Sample.Person.cls
^Sample.PersonI	^Sample.PersonI("SSNKey")	Sample.Person.cls
^Sample.PersonI	^Sample.PersonI("ZipCode")	Sample.Person.cls

9 Rows(s) Affected
SAMPLES>

• classmethod GlobalsUsed(pExtentName As %String(MAXLEN="")="") [ SQLProc ]

GlobalsUsed is a class method that returns a result set in a context object. This method is easily invoked as an SQL procedure. The single result is a result set containing the extent name, global name and global reference for each global reference registered for use by the extent name passed in as the single argument.

SAMPLES>s st=##class(%SQL.Statement).%New()

SAMPLES>w st.%Prepare("call %ExtentMgr.GlobalsUsed(?)")

1

SAMPLES>s rs=st.%Execute("Sample.Person.cls")

SAMPLES>d rs.%Display()

UsedByExtent GlobalName GlobalReference

Sample.Person.cls ^Sample.PersonD ^Sample.PersonD

Sample.Person.cls ^Sample.PersonI ^Sample.PersonI("$Person")

Sample.Person.cls ^Sample.PersonI ^Sample.PersonI("NameIDX")

Sample.Person.cls ^Sample.PersonI ^Sample.PersonI("SSNKey")

Sample.Person.cls ^Sample.PersonI ^Sample.PersonI("ZipCode")

UsedByExtent	GlobalName	GlobalReference
Sample.Person.cls	^Sample.PersonD	^Sample.PersonD
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("$Person")
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("NameIDX")
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("SSNKey")
Sample.Person.cls	^Sample.PersonI	^Sample.PersonI("ZipCode")

• classmethod RegisterAllClasses(display As %Integer = 0) as %Status

This method registers the extents all classes in the current namespace. If display is true then status messages will be displayed on the current device.

• classmethod RegisterClass(pClassName As %String(MAXLEN=""), ByRef pGlobalRef As %String) as %Status

This method registers the extent of pClassName in the Extent Manager Catalog. If the extent has been previously registered and the new extent definition is compatible with the existing extent then the extent is updated.

• classmethod RegisterCustomExtent(pExtentName, ByRef pExtentType As %String = "", ByRef pGlobalRef As %String) as %Status

This method registers an extent that is not necessarily an extent of a Cache persistent class. It can be either the extent of a Cache persistent class that does not use default storage or it can simply be an extent that exists with no class definition. It can be used to simply register global references so that those globals cannot be used for any conflicting purpose.

This method accepts an extent name, extent type and an array of global references that are used by the extent.

pExtentType is expected to be "cls" for the extent of a Cache class. The extent type is always converted to lower case.

Parameters
pExtentName Input The name of the entity whose extent is to be registered. This name is normally a class name of a persistent class but for custom extents this name can be anything that does not conflict with another extent name. This name and the pExtentType form the extent name that is registered in the Extent Catalog. For example, "SampleCustomGlobals" with a pExtentType = "gbl" might be a custom extent name used to register globals used directly in the Sample applications, forming an extent name of "SampleCustomGlobals.gbl".

pExtentType Input The extent type. "cls" is the type for Cache persistent extents. For custom extents, this can be anything but it should be descriptive. For example, "gbl" might be used to register globals used directly by and application.

pGlobalRef ByRef An array of global references to be registered as used by this extent. This array is expected to be defined as pGlobalRef(subscript)=global_reference where subscript is normally a simple integer and global_reference is the global reference to be registered for use by this extent. The number of entries is not limited but there are practical limits.

Return value: This method returns a %Status value indicating success or failure.

Parameters
pExtentName	Input	The name of the entity whose extent is to be registered. This name is normally a class name of a persistent class but for custom extents this name can be anything that does not conflict with another extent name. This name and the `pExtentType` form the extent name that is registered in the Extent Catalog. For example, "SampleCustomGlobals" with a `pExtentType` = "gbl" might be a custom extent name used to register globals used directly in the Sample applications, forming an extent name of "SampleCustomGlobals.gbl".
pExtentType	Input	The extent type. "cls" is the type for Cache persistent extents. For custom extents, this can be anything but it should be descriptive. For example, "gbl" might be used to register globals used directly by and application.
pGlobalRef	ByRef	An array of global references to be registered as used by this extent. This array is expected to be defined as pGlobalRef(`subscript`)=`global_reference` where `subscript` is normally a simple integer and `global_reference` is the global reference to be registered for use by this extent. The number of entries is not limited but there are practical limits.

• classmethod RegisterGlobalReference(pExtentName As %String, pExtentType As %String = "cls", pReference As %String, Output pExisting As %Integer) as %Status

This method registers a global reference in the global registry for use by the requested pExtentName extent. If no incompatible uses are found then the method succeeds. Otherwise, an error message indicating the conflict and type of conflict is returned.

Parameters
pExtentName Input The name of the entity that uses the reference to be registered. This name is normally a class name of a persistent class but for custom extents this name can be anything that does not conflict with another extent name. This name and the pExtentType form the extent name that is registered in the Extent Catalog. For example, "SampleCustomGlobals.gbl" might be a custom extent name used to register globals used directly in the Sample applications.

pExtentType Input The extent type. "cls" is the type for Cache persistent extents. For custom extents, this can be anything but it should be descriptive. For example, "gbl" might be used to register globals used directly by and application.

pReference Input The global reference to be registered.

pExisting Output Returns 1 to indicate that the reference registered was already registered.

Return value: This method returns a %Status value indicating success or failure.

Parameters
pExtentName	Input	The name of the entity that uses the reference to be registered. This name is normally a class name of a persistent class but for custom extents this name can be anything that does not conflict with another extent name. This name and the `pExtentType` form the extent name that is registered in the Extent Catalog. For example, "SampleCustomGlobals.gbl" might be a custom extent name used to register globals used directly in the Sample applications.
pExtentType	Input	The extent type. "cls" is the type for Cache persistent extents. For custom extents, this can be anything but it should be descriptive. For example, "gbl" might be used to register globals used directly by and application.
pReference	Input	The global reference to be registered.
pExisting	Output	Returns 1 to indicate that the reference registered was already registered.


[BASEXML] > [%ExtentMgr] > [Util]		Private Storage