Skip to main content

%ExtentMgr.Util

abstract class %ExtentMgr.Util

For information on this class, see Extents.

The sample class mentioned here (Sample.Person) is part of https://github.com/intersystems/Samples-Data.Opens in a new tab See Downloading SamplesOpens in a new tab.

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.

Method Inventory

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.
deprecated 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 GetRowVersion() as %Library.BigInt
GetRowVersion returns the current ROWVERSION counter for this database. The rowversion counter is used by classes with a property of type %Library.RowVersion.
classmethod GlobalUses(pGlobalReference As %String(MAXLEN="")="") [ SQLProc = GlobalUses ]
Projected as the stored procedure: GlobalUses
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 ]
Projected as the stored procedure: GlobalsUsed

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>set st=##class(%SQL.Statement).%New()

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

1

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

SAMPLES>do rs.%Display()

UsedByExtentGlobalNameGlobalReference
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 persistent class. It can be either the extent of a 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 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 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.

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 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.

FeedbackOpens in a new tab