%Library.Persistent

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.

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";

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

parameter EXTENTSIZE = 1000000;

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.

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:

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.

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.

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

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

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.

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")

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] */)

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

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.

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

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

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

Returns a %Status value indicating success or failure.

Returns a null string if there is no object Id.

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.

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.

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.

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

Returns a %Status value indicating success or failure.

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

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

Returns a %Status value indicating success or failure.

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.

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.