Skip to main content

%Library.Persistent

abstract persistent class %Library.Persistent extends %Library.SwizzleObject

SQL Table Name: %Library.Persistent

For information on this class, see Working with Persistent Objects.

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 %Persistent class provides the basic mechanism by which objects are stored to and retrieved from a database.

Method Inventory

Parameters

parameter %XCOMPACTANCESTRY;
%XCOMPACTANCESTRY can be set to a string to replace the value of the %%CLASSNAME property (x__classname field) with a more compact value that will reduce the size of the data on disk stored for each record.
parameter DATALOCATIONGLOBAL;
Global name containing master map data for this class. Used in creating the oref to oid table so we can determine where the data for this class is located. Will normally be set automatically during compile for both default and SQL storage classes so normally there is no need to modify this setting unless you have custom storage and wish to point this at a specific global name. If the value is "" then we will not insert a data global location into the oid->obj table and so will assume if the same class (mapped from a common location) opens the same id in two different namespaces these are referring to the same instance and so the second open will return the first oref.
parameter DEFAULTGLOBAL;

If a persistent class uses %Storage.Persistent then the DEFAULTGLOBAL parameter is used as the default global root for the values of the storage keywords COUNTERLOCATION, DATALOCATION, IDLOCATION, INDEXLOCATION and STREAMLOCATION in the active storage definition. DEFAULTGLOBAL is only used to generate location keyword values that are not already defined. The location value is constructed by adding a location type to the end of DEFAULTGLOBAL. For example, if DEFAULTGLOBAL = "^GL.Account" the compiler will generate DATALOCATION = ^GL.AccountD.

If USEEXTENTSET is true, then DEFAULTGLOBAL is used as the default extent location.


The location types are:
LocationType
COUNTERLOCATIONC
DATALOCATIOND
IDLOCATIOND
INDEXLOCATIONI
STREAMLOCATIONS
parameter DSCONDITION;
DSCONDITION is the expression that will be evaluated before deciding whether certain actions must be taken. These actions are the same as those performed when DSTIME is set to AUTO - for instance updating ^OBJ.DSTIME on modifying a record.
parameter DSINTERVAL;
DSINTERVAL is the number of seconds between one DSTIME value and the next. The DSTIME value for DSINTERVAL > 0 is computed from $ZTIMESTAMP and is the number of seconds from day 0, time 0 to the nearest interval, rounded down. Using an interval has the effect of grouping all DSTIME entries for the class in some number of seconds.
parameter DSTIME;
If the DSTIME parameter is set to AUTO then the most recent filing operation in the current DSTIME value for each object will be recorded in a global, ^OBJ.DSTIME:
^OBJ.DSTIME(ExtentName,DSTIME,objectID) = filing operation
For DSTIME=AUTO the DSTIME value is recorded in ^OBJ.DSTIME and is set by the consumer of DSTIME data.
Refer to %DeepSee documentation for more information on how DSTIME is used by %DeepSee.
The filing operations are:
CodeOperation
0Update
1Insert
2Delete

If the DSTIME parameter is set to MANUAL then the user is responsible for journaling object filing operations. If DSTIME is set to "CONDITIONAL", the user is expected to define the parameter DSCONDITION setting it to an expression which will determine if the actions performed when DSTIME is set to AUTO will execute or not
parameter EXTENTQUERYSPEC;
The EXTENTQUERYSPEC parameter defines the properties to be retrieved in addition to the IDKEY value for the built-in Extent query.

Persistent classes should define a value of for EXTENTQUERYSPEC if they wish to include additional properties in their built-in Extent query.

For example:

parameter EXTENTQUERYSPEC = "Name,SSN,Age";
parameter EXTENTSIZE = 100000;
The EXTENTSIZE parameter is used to inform the SQL Query Optimizer of the approximate number of instances in the extent containing instances of this class.

For example, a class that expects to have about 1,000,000 instances should define:

parameter EXTENTSIZE = 1000000;
parameter GUIDENABLED = 0;
If this parameter is set to 1 then a GUID will be assigned (to the %GUID property) to each new object. When the object is saved for the first time this GUID value will be recorded in a namespace index which will allow GUID to be resolved to OIDs.
deprecated parameter IDENTIFIEDBY;
The IDENTIFIEDBY parameter can optionally be set to the name of a required property whose type is a reference to another class (not a literal). This property's IDKEY is then used as the prefix for the IDKEY of this class.
Deprecated parameter, use parent/child relationships instead
parameter MANAGEDEXTENT = 1;
The MANAGEDEXTENT parameter can be set to 0 (zero) to cause the Extent Manager to ignore this class. If set to 1 then the Extent Manager will register globals used by the class and detect collisions. Unmanaged extents (MANAGEDEXTENT = 0) are not checked. Currently, only classes using default storage (%Storage.Persistent) can be managed.
parameter READONLY = 0;
READONLY = 1 means that objects can be created, opened but not saved or deleted. Tables are projected to SQL as READONLY.
parameter ROWLEVELSECURITY;
ROWLEVELSECURITY = 1 | <property> means that row level security is active and the list of users/roles for a given instance/row is contained in a generated property. If the value of this parameter is a valid property name then that property will be used as the reader list and only generated if not already defined.
parameter SQLPREVENTFULLSCAN = 0;
SQLPREVENTFULLSCAN = 1 means an attempt to prepare a query that will result in a full scan of the data map will result in an error. This applies only to queries that result in a master map scan (not indexes), with no subscript-limiting conditions on %ID or any of its components, including queries with aggregates, and including UPDATE/DELETE.
parameter STORAGEDEFAULT;
STORAGEDEFAULT defines the default storage allocation to use for properties in this class. The Storage Generator will use this value when building the initial Storage Definition or amending it when new properties have been added to a class. Allowed values are "column" and "". Leaving it undefined ("") means the overall system default row-based storage model will be used when persisting this extent. This value can be overridden for individual properties with the corresponding property-level parameter, where additional values are available for specific property types.
parameter USEEXTENTSET = 0;

If a persistent class uses %Storage.Persistent then the USEEXTENTSET parameter is used to specify the global naming strategy used by the default storage class (%Storage.Persistent). If TRUE, then global names are generated for each index that is not already allocated a LOCATION in the active storage definition.

If the storage definition specifies EXTENTLOCATION then that value is used as the base reference for all globals assigned to indices that do not have an explicit LOCATION assigned.

The global name generator for USEEXTENTSET = TRUE honors the package prefix defined in the Package Definition. If none is defined then the package prefix is generated using a based-62 encoded integer produced from CRC32 of the package name. The specific class identifier is generated from the unqualified class name using the same hash (class->crc32->base62) to form EXTENTLOCATION. Specific index suffixes are produced using a generated offset that is local to the first persistent class with an enumerated extent in which the index appears (either defined or inherited).

There are several factors that influence the generation of EXTENTLOCATION:

  1. If the EXTENTLOCATION keyword is defined then its value is used,
  2. If the DEFAULTGLOBAL class parameter is defined then its value is used,
  3. otherwise, the value is generated as two dot delimited segments. The first segment is either the defined package prefix retrieved from the package definition global or, if none is defined, a hash of the package name. The second segment is generated by a hash of the unqualified class name. The hash used is a base 62 encoded CRC32 of the value. For example, Sample.Person produces ^EW3K.wPC9 if no package prefix is defined.
The EXTENTLOCATION value is used as the base for specific globals allocated to indices. Each index is assigned an offset that is incremented from 1 by 1, offset = 1 is reserved for the IDKEY index.

EXTENTLOCATION is specific to each class. When a persistent class extends another persistent class, forming a subextent, then the subclass's EXTENTLOCATION is specific to that subclass. The index location for any inherited index is already defined specifically in the superclass so the subclass's EXTENTLOCATION will only be used as the base for any index that originates in the subclass. For example, Sample.Employee extends Sample.Person. The EXTENTLOCATION generated for Sample.Person is ^EW3K.wPC9 and the EXTENTLOCATION for Sample.Employee is ^EW3K.D1Ex. Since Sample.Employee inherits several indices from Sample.Person, the global name assigned to each of those indices is already defined and inherited by Sample.Employee. However, any index defined in Sample.Employee and not inherited from Sample.Person will be assigned a global name based on Sample.Employee's EXTENTLOCATION, not on Sample.Person's EXTENTLOCATION. In other words, the EXTENTLOCATION storage keyword is not inherited.

The following tables show the indices and locations for Sample.Person and Sample.Employee. Notice the last index in the Sample.Employee table:

Class = Sample.Person
IndexLocation
IDKEY^EW3K.wPC9.1
$Person^EW3K.wPC9.2
NameIDX^EW3K.wPC9.3
SSNKey^EW3K.wPC9.4
ZipCode^EW3K.wPC9.5
Class = Sample.Employee extends Sample.Person
IndexLocation
IDKEY^EW3K.wPC9.1
$Person^EW3K.wPC9.2
NameIDX^EW3K.wPC9.3
SSNKey^EW3K.wPC9.4
ZipCode^EW3K.wPC9.5
$Employee^EW3K.D1Ex.2

Any generated global index locations and EXTENTLOCATION are updated back into the active storage definition after the class is compiled.

If USEEXTENTSET is FALSE, then global names are generated using the package-hash.class-hashSuffix strategy. For example, ^Sample.PersonD and ^Sample.PersonI("SSNKey") are globals used by Sample.Person and specific index structures are all stored in ^Sample.PersonI with the index name used as the first subscript.


parameter VERSIONCLIENTNAME;
VERSIONCLIENTNAME can be set to a valid CLIENTNAME (see property CLIENTNAME) value. This value will be used for client projections of the %Version property.
parameter VERSIONPROPERTY;
VERSIONPROPERTY = <property> means that the <property> in memory will be compared to the <property> on disk during an update. If different a concurrency conflict error will be reported and the save will fail.
parameter masterClassName;

Methods

classmethod %BuildDeferredIndices(pLockFlag As %Integer = 0, pJournalFlag As %Integer = "") as %Status

Builds index entries for all defined indexes for each object contained in the Deferred Indexing Index.

If pLockFlag is one (1) then an extent lock will be acquired before the indices are built. If the lock cannot be acquired then an error is returned. The lock is released after the index build is completed. If pLockFlag is two (2) then a lock is acquired prior to filing indices for that instance and it is released as soon the indices for that instance are filed. If it is zero (0) then no locks are used while filing the indices. If it is three (3) then a shared extent lock will be acquired before the indices are built and released upon completion.

If pJournalFlag is 0 then journaling is disabled for the processes used to build the indices (except where the database is in a Mirror). If this flag is 1 then the journaling is enabled for the process used to build the indices. The default value of this argument is "" meaning use the current process setting.

Returns a %Status value indicating success or failure. This method is normally generated by the storage class for persistent classes using %Storage.Persistent or %Storage.SQL.

If your index is corrupt running this function will not fix the corruption unless you rebuild the entire index and purge the existing indexes.

classmethod %BuildIndices(pIndexList As %RawString = "", pAutoPurge As %Integer = 1, pLockFlag As %Integer = 0, pJournalFlag As %Integer = "", pStartID As %RawString = "", pEndID As %RawString = "", pIgnoreIndexList As %RawString = "", pKeepSelectability As %Integer = 0, pNumberJobs As %Integer = "") as %Status

Builds entries for each index specified in the pIndexList argument. If pIndexList is empty then all indices that originate in the class are rebuilt. If not empty you can specify a $list of indexes to build, e.g. $lb("MyIndex1","MyIndex2"). If there are other bitmap indexes specified in pIndexList and there is a bitmap extent index defined for the class then it will be implicitly included in pIndexList. If the bitmap extent index is included then the bitmap extent index for each subextent is also built.

If pAutoPurge is true then the indices contained in pIndexList will be purged before they are built as long as no range is specified, if a range is specified we will skip any purge. The default is TRUE (1).

If pLockFlag is one (1) then an extent lock will be acquired before the indices are built. If the lock cannot be acquired then an error is returned. The lock is released after the index build is completed. If pLockFlag is two (2) then a lock is acquired prior to filing indices for that instance and it is released as soon the indices for that instance are filed. If it is zero (0) then no locks are used while filing the indices. If it is three (3) then a shared extent lock will be acquired before the indices are built and released upon completion.

If pJournalFlag is 0 then journaling is disabled for the processes used to build the indices (except where the database is in a Mirror). If this flag is 1 then the journaling is enabled for the process used to build the indicies. The default value of this argument is "" meaning use the current process setting.

pStartID and pEndID define a range of IDs for which indices will be built. The range is inclusive. If the starting ID is null then the range begins at the first ID defined in the extent. If the ending ID is null then the range ends at the last ID defined in the extent.

If pIgnoreIndexList is defined, it should be a $list of index names that should not be built. This argument allows you to build all indices except those defined in pIgnoreIndexList. The default value of this argument is "", which means all indices, or all indices specified in pIndexList, will be built.

If pKeepSelectability is 1, any index maps defined as Not Selectable prior to the %BuildIndices() call will remain Not Selectable after the %BuildIndices() call. If pKeepSelectability is 0 any index maps defined as Not Selectable prior to the %BuildIndices() call will be set to Selectable after the successful %BuildIndices() call.

If pNumberJobs is defined, the system should use this explicitly specify the number of workers to run %BuildIndices(). The default value of this argument is "", which means the system should calculate how many jobs to run %BuildIndices()

If %OnBeforeBuildIndices() is implemented and is runnable then it will be called just prior to purging and building any index structures. Refer to %OnBeforeBuildIndices() for more information.

If %OnAfterBuildIndices() is implemented and is runnable then it will be called after all index structures have been built completely. Refer to %OnAfterBuildIndices() for more information.

Returns a %Status value indicating success or failure. This method is normally generated by the storage class for persistent classes using %Storage.Persistent or %Storage.SQL.

If your index is corrupt running this function will not fix the corruption unless you rebuild the entire index and purge the existing indexes. If you have inserted some new items but have deferred building the index for these new items then you can run %BuildIndices on this range of IDs to add the index entries for these new items.

classmethod %BuildIndicesAsync(Output queueToken As %String, pIndexList As %RawString = "", pAutoPurge As %Integer = 1, pLockFlag As %Integer = 0, pJournalFlag As %Integer = "", pStartID As %RawString = "", pEndID As %RawString = "", pIgnoreIndexList As %RawString = "", pTimeout As %Integer = 86400, pKeepSelectability As %Integer = 0) as %Status

%BuildIndicesAsync() instantiates a work queue and queues a %BuildIndices() call. The argument list after the output queueToken is the same as for %BuildIndices().

This method returns a work queue token as the first argument (output) that can be used to retrieve the status of the %BuildIndices() worker using %BuildIndicesAsyncResponse().

The return value is a %Status value indicating success or failure.

queueToken output The token identifying the %BuildIndices() task. This argument must be passed by reference as it is the identifier of the work queue and it is needed to retrieve the completion status using %BuildIndicesAsyncResponse().
pIndexList input The names of the indexes to be built. If empty then all indices that originate in the class are built. If not empty you can specify a $list of index names to build, e.g. $lb("MyIndex1","MyIndex2"). If there are other bitmap indexes specified and there is a bitmap extent index defined for the class then it will be implicitly included in the list of indexes to build. If the bitmap extent index is included then the bitmap extent index for each subextent is also built.
pAutoPurge input If true then the indices contained in pIndexList will be purged before they are built as long as no range is specified, if a range is specified we will skip any purge. The default is TRUE (1).
pLockFlag input If one (1) then an extent lock will be acquired before the indexes are built. If the lock cannot be acquired then an error is returned. The lock is released after the index build is completed. If pLockFlag is two (2) then a lock is acquired prior to filing indices for that instance and it is released as soon the indices for that instance are filed. If it is zero (0) then no locks are used while filing the indices. If it is three (3) then a shared extent lock will be acquired before the indices are built and released upon completion.
pJournalFlag input If false then journaling is disabled for the processes used to build the indices (except where the database is in a Mirror). If this flag is true then the journaling is enabled for the process used to build the indicies. The default value of this argument is "" meaning use the current process setting.
pStartID input The starting ID for the range of ID's for which indices will be built, inclusive. If the starting ID is null then the range begins at the first ID defined in the extent.
pEndID input Then ending ID for the range of ID's for which indexes will be built, inclusive. If the ending ID is null then the range ends at the last ID defined in the extent.
pIgnoreIndexList input A list of index names that should not be built. This argument allows you to build all indices except those defined in pIgnoreIndexList. The default value of this argument is "", which means all indices, or all indices specified in pIndexList, will be built.

pTimeout input pTimeout is the number of seconds to pass for the %SYSTEM.WorkMgr.Detach() method's timeout argument. The default timeout is 86400s (24 hours). If the %BuildIndices time is expected to be more than 24 hours and you don't want the build to timeout, increase this value to an appropriate number of seconds.

pKeepSelectability input If pKeepSelectability is 1, any index maps defined as Not Selectable prior to the %BuildIndices call will remain Not Selectable after the %BuildIndices() call. If pKeepSelectability is 0 any index maps defined as Not Selectable prior to the %BuildIndices() call will be set to Selectable after the successful %BuildIndices() call.

return The %Status value indicates success or failure. If queueToken is null then the return status value can indicate an error involving the work queue or it can be the completion status from the %BuildIndicesAsync() task.

classmethod %BuildIndicesAsyncResponse(ByRef queueToken, wait As %Boolean = 1) as %Status

Return the completion status of a %BuildIndicesAsync task, identified by queueToken. The global array node reference is defined by a globalName and a variable number of subscripts.

This method returns a %Status value.

queueToken byref The token identifying the %BuildIndicesAsync() task. This argument must be passed by reference as it is the identifier of the work queue and it can be changed by this method. If the returned queueToken is not null (should only happen if wait is false) then the task is not yet complete and the new token value can be used to call this method again to check and possibly return the completion status. If this value is null on return then the task has completed or cannot be located and the return status value is the final status (completion status).
wait input

A boolean value indicating whether or not %BuildIndicesAsyncResponse should wait for the %BuildIndicesAsync() task to complete before returning.

If this value is true then this method will wait until the task identified by queueToken is complete before returning.

If it is false, then this method will return as quickly as possible. In that case, if the task is not yet complete then queueToken will not be null on return and can be used to invoke this method again.

If this method detects an error reported by the task identified by the token then this method will wait for the final completion of the task before returning.

return The %Status value indicating success or failure. If queueToken is null then the return status value can indicate an error involving the work queue or it can be the completion status from the %BuildIndicesAsync() task.

classmethod %CheckConstraints(pID As %String(MAXLEN=""), pConstraintList As %List = "", pCheckDisabled As %Integer = 0, Output pErrorInfo As %List) as %Status

This method checks the constraints defined in the current class for one object, identified by pID. If only selected constraints are to be checked, then pConstraintList can be passed as a $list of the names of the constraints to be checked. If any constraint fails then the failure status will be included in the returned %Status value. In addition, the output parameter pErrorInfo will contain the object ID and the values of all properties that are referenced by constraints defined for the current class.

If the current class is not the most specific type class (MSTC) of the object identified by pID, then this method will dispatch to the object's most specific type class. Note that if you do not pass a constraint list then all constraints present for the MSTC are checked, which may include others in addition to those present for the current class.

SAMPLES>set status = ##class(Sample.Person).%CheckConstraints(1,,,.errorinfo)

SAMPLES>do $system.OBJ.DisplayError(status)                                 

ERROR #5808: Key not unique: Sample.Person.SSNKey
SAMPLES>zw errorinfo                                                        
errorinfo=$lb(1,"798-92-1974")

Parameters
Name Direction Description
pID Input The ID of the object to be checked.
pConstraintList Input A $list of constraints to be checked. If null then all constraints defined for this class will be checked.
pCheckDisabled Input If this value is passed as a true value (1) then %CheckConstraints will also check any constraints that are defined as %NOCHECK.
pErrorInfo Output If an error is reported then pErrorInfo will contain the object's ID and all property values that are referenced by constraints defined for this class.
Return %Status return value. This value contains %Status values for each constraint that failed. If no errors are reported then %Status will be $$$OK.

classmethod %CheckConstraintsForExtent(pConstraintList As %String(MAXLEN="")="", pCheckDisabled As %Integer = 0, Output pErrorLog As %String(MAXLEN="")) as %Status

This method will loop over each object in the extent of the current class and invoke %CheckConstraints(). If only selected constraints are to be checked then pConstraintList can be passed as a $list of the names of the constraints to be checked. All constraint failures are included in the returned %Status value, subject to the maximum %Status size. In addition, the output parameter pErrorLog contains up to 1,000 entries containing the object ID and the values of all properties that are referenced by constraints defined for the current class. The error log also adds the %Status value returned by %CheckConstraints() as the last $list element.

SAMPLES>set status = ##class(Sample.Person).%CheckConstraintsForExtent(,,.errorlog)

SAMPLES>do $system.OBJ.DisplayError(status)                                       

ERROR #5808: Key not unique: Sample.Person.SSNKey
ERROR #5808: Key not unique: Sample.Person.SSNKey
SAMPLES>zw errorlog
errorlog=2
errorlog(1)=$lb(1,"798-92-1974","0 "_$lb($lb(5808,"Sample.Person.SSNKey",,,,,,,,"%CheckConstraints+7^Sample.Person.1:SAMPLES"))/* ERROR #5808: Key not unique: Sample.Person.SSNKey [%CheckConstraints+7^Sample.Person.1:SAMPLES] */)
errorlog(2)=$lb(100,"798-92-1974","0 "_$lb($lb(5808,"Sample.Person.SSNKey",,,,,,,,"%CheckConstraints+7^Sample.Person.1:SAMPLES"))/* ERROR #5808: Key not unique: Sample.Person.SSNKey [%CheckConstraints+7^Sample.Person.1:SAMPLES] */)

Parameters
Name Direction Description
pConstraintList Input A $list of constraints to be checked. If null then all constraints defined for the most specific type class of each object will be checked.
pCheckDisabled Input If this value is passed as a true value (1) then %CheckConstraints will also check any constraints that are defined as %NOCHECK.
pErrorLog Output This is an array of up to 1,000 entries containing error information reported by %CheckConstraints().
Return %Status return value. This value contains %Status values for each constraint that failed. If no errors are reported then %Status will be $$$OK.

classmethod %ComposeOid(id As %String(MAXLEN=""))
%ComposeOid() This class method accepts an ID and returns a fully qualified OID, containing the most specific type class of the object identified by the id argument. If default storage is used then the %%CLASSNAME value is used to determine the most specific type class, otherwise call %OnDetermineClass to determine the most specific type class. If neither case is true then the current class is used. If there is a problem determining the most specific type class then null ("") is returned.
final classmethod %Delete(oid As %ObjectIdentity = "", concurrency As %Integer = -1) as %Status
Deletes the stored version of the object with OID oid from the database. It does not remove any in-memory versions of the object that may be present. Refer to Object Concurrency Options for more details on the optional concurrency argument. For classes defined as Sharded=1, concurrency=0 is always used.

Returns a %Status value indicating success or failure.

Internally, %Delete() initiates a transaction and then invokes the storage interface method %DeleteData(). If %DeleteData() succeeds, the transaction is committed, otherwise it is rolled back. No transaction is initiated if this class is defined as Sharded=1

classmethod %DeleteExtent(concurrency As %Integer = -1, ByRef deletecount, ByRef instancecount, pInitializeExtent As %Integer = 1, Output errorLog As %Status) as %Status
Delete all instances of this class from its extent. On exit instancecount contains the original number of instances while deletecount contains the number of instances actually deleted.

Internally, %DeleteExtent() iterates over the set of instances in the collection and invokes the %Delete() method.
Refer to Object Concurrency Options for more details on the optional concurrency argument.
The option pInitializeExtent argument allows the user to override the default behavior of calling %KillExtent() when all instances are successfully deleted. %KillExtent() is called by default when the extent is empty so that empty globals can be killed. If %KillExtent() is not called then some empty globals can remain as well as the ID counter if it exists. The default value for pInitializeExtent is 1. Unless the caller specifies a false value for pInitializeExtent the globals used by the extent will be killed. If the process' GlobalKillDisabled flag is enabled and not the default of false the process' GlobalKillDisabled flag will be changed temporarily to false to allow the operation to complete without a possible error. In some cases, the globals used by the extent are not used exclusively by the extent. In those cases it is possible that some globals will still be defined even when pInitializeExtent is true. By default this call to %KillExtent() will not delete default stream storage global, but if you pass '2' in pInitializeExtent and if the entire extent was deleted we will call %KillExtent passing the 'killstreams' flag to ask it to remove kill the default storage global.

Returns a %Status value indicating success or failure.

final classmethod %DeleteId(id As %String, concurrency As %Integer = -1) as %Status
Deletes the stored version of the object with ID id from the database.

%DeleteId() is identical in operation to the %Delete() method except that it uses an Id value instead of an OID value to find an object. Refer to Object Concurrency Options for more details on the optional concurrency argument. For classes defined as Sharded=1, concurrency=0 is always used.

classmethod %Exists(oid As %ObjectIdentity) as %Boolean
Checks to see if the object identified by the OID oid exists in the extent.

Returns %Boolean TRUE if it exists, FALSE if it does not.

classmethod %ExistsId(id As %String) as %Boolean
Checks to see if the object identified by the ID id exists in the extent.

Returns %Boolean TRUE is it exists, FALSE if it does not.

classmethod %GUID(oid As %ObjectIdentity, pDeepSearch As %Integer = 0) as %String
This method returns the GUID assigned to <oid>. This method is only runnable if the GUIDENABLED parameter is TRUE. This method will dispatch polymorphically and will determine the most-specific-type class if the oid does not contain that information. If pDeepSearch is true and no GUID is found for the object then a deep search of the GUID registry will be performed, starting with the current class. This is useful if the most specific type class cannot be determined, such as in the case of an object that has been deleted.
classmethod %GUIDSet(oid As %ObjectIdentity, guid As %String = "") as %String
classmethod %GetLock(id As %String, shared As %Boolean = 0) as %Integer
This method acquires a lock on the object identified by 'id'. If the number of locks already taken out for this extent is greater than the configured maximum then the lock will be escalated to an extent-level lock. If the lock is successfully obtained a 1 will be returned, 2 will be returned if the lock was escalated to an extent-level lock. A zero, '0', is returned if the method failed to obtain a lock.
final method %GetSwizzleObject(force As %Integer = 0, ByRef oid As %ObjectIdentity) as %Status
%GetSwizzleObject() is used to obtain a state of the object that can later be used to restore the object. In the case of a persistent object, it returns the OID.

Returns a %Status value indicating success or failure.

final method %Id() as %String
Returns the persistent object Id, if there is one, of this object.

Returns a null string if there is no object Id.

classmethod %KillExtent(pDirect As %Integer = 1, killstreams As %Boolean = 0) as %Status
%KillExtent performs a physical kill of the extent. No constraints are enforced. This method should not be used in place of %DeleteExtent. Only physical storage occupied by this extent will be killed. If this extent is a subextent of another class then no data is killed. Indexes that originate with this extent will be killed. %KillExtent will be called on any subextents and on any child extents (the extent of the type class of a relationship whose cardinality = children is a 'child' extent) of this extent.
This method is not meant for production applications. It is meant to be a development utility to quickly clear extent physical data. Also this will not remove stream data associated with these instances.
If killstreams is true (default is false) it will also kill the default stream storage global.
classmethod %LockExtent(shared As %Boolean = 0) as %Status
%LockExtent acquires a lock on the entire extent of the class. If shared is true then a shared lock is acquired, otherwise an exclusive lock is acquired. If the requested lock cannot be acquired then a failure %Status value is returned. The default implementation returns an error indicating that the method is not implemented. This method is automatically generated for persistent classes using %Storage.Persistent or %Storage.SQL.
classmethod %LockId(id As %String, shared As %Boolean = 0, timeout As %Integer) as %Status
Obtain an exclusive or shared lock on the object identified by id. The type of lock obtained is determined by shared. This method is normally generated by the storage class for persistent classes using %Storage.Persistent or %Storage.SQL.
classmethod %ObjectIsNull(pOID As %ObjectIdentity) as %Boolean
Return true if pOID is a null object and false if the object is not null
final method %Oid() as %ObjectIdentity
Returns the OID of this object.
abstract classmethod %OnDeleteFinally(oid As %ObjectIdentity, status As %Status)
%OnDeleteFinally is an optional user implemented callback. There is no return value and any exceptions are trapped and discarded.
classmethod %OnDetermineClass(oid As %ObjectIdentity, ByRef class As %String) as %Status
Inherited description: This callback method is invoked by the %Open() method to determine the classname of the object specified by oid.
classmethod %OnOpenFinally(oid As %ObjectIdentity, status As %Status)
%OnOpenFinally is an optional user implemented callback. There is no return value and any exceptions are trapped and discarded.
abstract classmethod %OnSaveFinally(oref As %ObjectHandle, status As %Status)
%OnSaveFinally is an optional user implemented callback. There is no return value and any exceptions are trapped and discarded.
final classmethod %Open(oid As %ObjectIdentity, concurrency As %Integer = -1, ByRef sc As %Status = $$$OK) as %ObjectHandle
Loads an object from the database into memory and returns an OREF referring to the object. oid is the OID value of the object to load. If oid is a partially-formed OID, that is it does not include a class name, then %Open() does the following: a) calls the method, %OnDetermineClass(), to determine the class name, otherwise b) it assumes the class name is the same as the object class on which %Open() was called.

If a version of the specified object is already in memory, then %Open() increments the object's reference count and returns the OREF value referring to this version. %Open() also has an optional concurrency argument which specifies the concurrency setting for this object (and sets the value of the %Concurrency attribute). If the concurrency argument is omitted then the system default value (1: Atomic) is used. Refer to Object Concurrency Options for more details on the optional concurrency argument. For classes defined as Sharded=1, concurrency=0 is always used.

%Open() returns an OREF value that refers to the in-memory object instance or a null reference ($$$NULLOREF) if it cannot find or otherwise load the object.

final classmethod %OpenId(id As %String = "", concurrency As %Integer = -1, ByRef sc As %Status = $$$OK) as %ObjectHandle
Loads an object from the database into memory or finds existing reference and returns an OREF referring to the object. id is the Id (not a full OID) value of the object to load.

If a version of the specified object is already in memory, then %Open() increments the object's reference count and returns the OREF value referring to this version. %Open() also has an optional concurrency argument which specifies the concurrency setting for this object (and sets the value of the %Concurrency attribute). If the concurrency argument is omitted then the system default value (1: Atomic) is used. Refer to Object Concurrency Options for more details on the optional concurrency argument. For classes defined as Sharded=1, concurrency=0 is always used.

%OpenId() returns an OREF value that refers to the in-memory object instance or a null reference ($$$NULLOREF) if it cannot find or otherwise load the object.

classmethod %PurgeIndices(idxlist As %List = "", lockExtent As %Boolean = 0, pIgnoreIndexList As %RawString = "", pJournalFlag As %Library.Integer = "") as %Status

Deletes all entries from each index specified in the idxlist argument. If idxlist is empty then all indices that originate in the class are purged. The index definition remains intact.

If pIgnoreIndexList is defined, it should be a $list of index names that should not be purged. This argument allows you to purge all indices except those defined in pIgnoreIndexList. The default value of this argument is "", which means all indices, or all indices specified in pIndexList, will be purged.

If pJournalFlag is set to 1, journaling will be enabled (if not already) for the duration of the purge. If it is set to 0, journaling will be disabled (if not already) for the duration of the purge. The default value of this argument is "", which means journaling behavior will not be altered.

If %OnBeforePurgeIndices() is implemented and is runnable, then it will be called just after acquiring the extent lock, if one is requested, and just prior to performing the purge. If %OnBeforePurgeIndices() returns an error status then %PurgeIndices will exit immediately, no indices will be purged and that error status will be returned to the caller of %PurgeIndices.

If %OnAfterPurgeIndices() is implemented and is runnable, then it will be called just prior to releasing the extent lock, if one is requested. cAll index structures have been purged prior to calling %OnAfterPurgeIndices(). If %OnAfterPurgeIndices() returns and error status then that status will be returned to the caller of %PurgeIndices but all structures will still have been purged.

Returns a %Status value indicating success or failure. This method is normally generated by the storage class for persistent classes using %Storage.Persistent or %Storage.SQL. Persistent classes using some other storage class, such as %Library.CustomStorage must override this method.

method %Reload() as %Status

%Reload is an instance method that re-reads an object from disk into the current instance. Calling %Reload is similar to closing the OREF and then %Open(), but it uses the same OREF. %Open is not called and no %Open callbacks are called.

After %Reload is called, there are no swizzled references for the object, and %IsModified() returns 0.

%Reload performs the following steps. First, all swizzled objects for the instance are unswizzled. Then the object is reloaded from disk, using the %Id() of the current object. Finally, the modified bit for each property is cleared.

method %RollBack() as %Status
This method is called by %Save() when a transaction is rolled back. It will invoke a user-supplied %OnRollBack() method if it exists.

Returns a %Status value indicating success or failure.

final method %Save(related As %Integer = 1) as %Status
Stores an in-memory version of an object to disk. If the object was stored previously (and thus, already has an OID), %Save() updates the on-disk version. Otherwise, %Save() assigns a new OID to the object and saves it.

The related argument specifies how %Save() handles references to other objects. It can take the following values:

0: Shallow Save If this object has been modified then save it. Only save related objects if they have never been saved (do not have an OID value) and must be saved in order to serialize this object's property values.
1: Deep Save Save this object and all "related" objects that have been edited. In this case, "related" means any in-memory objects it refers to, and any in-memory objects they in turn refer to, and so on. However, only objects that have been changed (%IsModified() returns true) will actually be saved to the database, including the object upon which %Save() was initially called.

%Save() automatically detects and handles circular references between objects. For example, %Save() will detect if object A refers to object B and object B likewise refers to object A. In this case it will avoid falling into an infinite, recursive loop.

Note that either reference attribute, A to B or B to A, can be specified as a required attribute but not both of them. If both reference attributes are required then %Save() will fail.

By default %Save() automatically manages transactions. You can enable and disable automatic transaction support using the $$SetTransactionMode^%apiOBJ() routine.

When %Save() saves an object to the database, it initiates one transaction (by calling TSTART) for the entire set of saves, including the original object and any related objects. If the save operation is successful, %Save() will issue a TCOMMIT command to commit the transaction and write the data to the database. If %Save() encounters a problem when saving the original object or any of its related objects, it rolls back the entire transaction and performs the following actions:

  • It issues a TROLLBACK command to rollback any changes to the database that may have occurred. (In the case of the %Storage.Persistent class, changes to the on-disk counter value, used to determine the next available object id number, are not rolled back.)
  • It restores the in-memory state of all the objects involved in the transaction to their pre-transaction state. This includes restoring any modified flags, and restoring to null ("") any OID values that have been assigned during the course of the transaction. Additional property values changed during the course of the transaction are not restored, however.
  • It calls the %RollBack() method on each object involved with the transaction. The order in which the %RollBack() methods are called is undefined. %RollBack() will call a user-written %OnRollback() method if it is present.

Returns a %Status value indicating success or failure.

classmethod %SaveDirect(ByRef id As %String = "", idList As %List = "", ByRef data As %Binary, concurrency As %Integer = -1) as %Status
%SaveDirect() - saves an object to disk, checks uniqueness and referential integrity constraints, and maintains index structures. The state of the object is passed to this method in three arguments. id contains the ID value if the object has been previously saved. idList is a $list value containing the IDKEY components. If the class is a child class (contains a relationship with CARDINALITY = PARENT) then the first value in the list is the parent reference. If the ID is system assigned the next value (or only value if the class is not a child class) is the system assigned ID value. If the ID is based on a user-defined IDKEY, then there is a $list element corresponding to each property in the same order as defined in the IDKEY index.
data is a structure that mirrors the disk structure of the object. The root value (unsubscripted) contains the properties stored in the data node from the storage definition with a null subscript. Additional entries in the data structure correspond to any additional data nodes defined in the storage definition.
This method is not commonly called directly.
This method is implemented by the storage class.

Returns a %Status value indicating success or failure.

classmethod %SortBegin(idxlist As %List = "", excludeunique As %Integer = 0) as %Status
Executes a $SortBegin for the base global reference of each index specified in the idxlist argument. If idxlist is empty then a $SortBegin is executed for all indices that originate in the class.

The excludeunique argument, if TRUE, causes any index defined as UNIQUE or PRIMARY KEY to be ignored.

Returns a %Status value indicating success or failure.

classmethod %SortEnd(idxlist As %List = "", commit As %Integer = 1, excludeunique As %Integer = 0) as %Status
Executes a $SortEnd for the base global reference of each index specified in the idxlist argument. If idxlist is empty then a $SortEnd is executed for all indices that originate in the class.

The commit argument, if FALSE, causes the data to be discarded. Otherwise, all data placed in the global since the $SortBegin is committed.

The excludeunique argument, if TRUE, causes any index defined as UNIQUE or PRIMARY KEY to be ignored.

Returns a %Status value indicating success or failure.

classmethod %UnlockExtent(shared As %Boolean = 0, immediate As %Boolean = 0) as %Status
%UnlockExtent releases a lock on the entire extent of the class. The type of lock released is determined by shared. The default implementation returns an error indicating that the method is not implemented. This method is automatically generated for persistent classes using %Storage.Persistent or %Storage.SQL.
classmethod %UnlockId(id As %String, shared As %Boolean = 0, immediate As %Boolean = 0) as %Status
Release an exclusive or shared lock on the object identified by id. The type of lock released is determined by shared. If this method is not overridden then the default implementation returns an error. This method is normally generated by the storage class for persistent classes using %Storage.Persistent or %Storage.SQL.

Queries

query Extent()

This is a system provided query that returns a row for each instance within this extent. The first column of the row is the object ID. Additional columns can be included in the select list by adding the desired columns to the EXTENTQUERYSPEC parameter.

The Extent query default implementation is generated by %Library.ExtentSQLQuery. That class supports the COMPILEMODE parameter with possible values of IMMEDIATE and DYNAMIC. If DYNAMIC is specified then the SQL statement used to implement the query will be generated as a dynamic SQL statement. If IMMEDIATE is specified then the statement is generated as an embedded SQL statement.


This query can be overridden by a subclass so long as two requirements are met. The list of columns must include %ID as the first column and it must return a row corresponding to each instance/row in the extent.

Triggers

trigger %OBJGUID (AFTER event INSERT);
trigger %OBJJRND (BEFORE event DELETE);
trigger %OBJJRNIU (AFTER event INSERT/UPDATE);

Inherited Members

Inherited Methods

Storage

Gray indicates storage defined by superclasses.

Subclasses

FeedbackOpens in a new tab