Static Public Member Functions
_.Library.Status	DeleteAllExtentDefinitions (_.Library.Integer display)
	This method deletes all extent definitions from the catalog. More...

_.Library.Status	DeleteExtent (_.Library.String extent, _.Library.String extentType)
	DEPRECATED - refer to <method>DeleteExtentDefinition</method>. More...

_.Library.Status	DeleteExtentDefinition (_.Library.String extent, _.Library.String extentType)
	DeleteExtentDefinition() will delete the extent metadata from the Extent Manager and remove all global registry. More...

_.Library.Status	DeleteGlobalReference (_.Library.String pReference, _.ExtentMgr.Catalog.Extent pUsedBy)
	DeleteGlobalReference will delete a registered global reference from the GlobalRegistry. More...

_.Library.BigInt	GetRowVersion ()
	GetRowVersion returns the current ROWVERSION counter for this database. More...

	GlobalUses (_.Library.String pGlobalReference)
	GlobalUses is a class method that returns a result set in a context object. More...

	GlobalsUsed (_.Library.String pExtentName)

_.Library.Status	RegisterAllClasses (_.Library.Integer display)
	This method registers the extents all classes in the current namespace. More...

_.Library.Status	RegisterClass (_.Library.String pClassName, _.Library.String pGlobalRef)
	This method registers the extent of pClassName in the Extent Manager Catalog. More...

_.Library.Status	RegisterCustomExtent (pExtentName, _.Library.String pExtentType, _.Library.String pGlobalRef)

_.Library.Status	RegisterGlobalReference (_.Library.String pExtentName, _.Library.String pExtentType, _.Library.String pReference, _.Library.Integer pExisting)

Detailed Description

For information on this class, see Extents.

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

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 - <method>GlobalUses</method> and <method>GlobalsUsed</method>. 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 <class>ExtentMgr.Catalog.Extent</class>. 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.

Member Function Documentation

◆ DeleteAllExtentDefinitions()

_.Library.Status DeleteAllExtentDefinitions ( _.Library.Integer display )

static

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.

◆ DeleteExtent()

_.Library.Status DeleteExtent	(	_.Library.String	extent,
		_.Library.String	extentType
	)

static

DEPRECATED - refer to <method>DeleteExtentDefinition</method>.

Maintained for backward compatibility only.

◆ DeleteExtentDefinition()

_.Library.Status DeleteExtentDefinition	(	_.Library.String	extent,
		_.Library.String	extentType
	)

static

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.

◆ DeleteGlobalReference()

_.Library.Status DeleteGlobalReference	(	_.Library.String	pReference,
		_.ExtentMgr.Catalog.Extent	pUsedBy
	)

static

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.

◆ GetRowVersion()

_.Library.BigInt GetRowVersion ( )

static

GetRowVersion returns the current ROWVERSION counter for this database.

The rowversion counter is used by classes with a property of type Library.RowVersion.

◆ GlobalUses()

GlobalUses ( _.Library.String pGlobalReference )

static

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>

◆ GlobalsUsed()

GlobalsUsed ( _.Library.String pExtentName )

static

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</thead> <tbody>

Sample.Person.cls

^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") </tbody>

◆ RegisterAllClasses()

_.Library.Status RegisterAllClasses ( _.Library.Integer display )

static

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.

◆ RegisterClass()

_.Library.Status RegisterClass	(	_.Library.String	pClassName,
		_.Library.String	pGlobalRef
	)

static

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.

◆ RegisterCustomExtent()

_.Library.Status RegisterCustomExtent	(		pExtentName,
		_.Library.String	pExtentType,
		_.Library.String	pGlobalRef
	)

static

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.

◆ RegisterGlobalReference()

_.Library.Status RegisterGlobalReference	(	_.Library.String	pExtentName,
		_.Library.String	pExtentType,
		_.Library.String	pReference,
		_.Library.Integer	pExisting
	)

static

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.

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ DeleteAllExtentDefinitions()

◆ DeleteExtent()

◆ DeleteExtentDefinition()

◆ DeleteGlobalReference()

◆ GetRowVersion()

◆ GlobalUses()

◆ GlobalsUsed()

◆ RegisterAllClasses()

◆ RegisterClass()

◆ RegisterCustomExtent()

◆ RegisterGlobalReference()