%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
- DeleteAllExtentDefinitions()
- DeleteExtent()
- DeleteExtentDefinition()
- DeleteExtentDefinitionIfExists()
- DeleteGlobalReference()
- GetRowVersion()
- GlobalUses()
- GlobalsUsed()
- RegisterAllClasses()
- RegisterClass()
- RegisterCustomExtent()
- RegisterGlobalReference()
Methods
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>
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()
| 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") |
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.
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.