| Server:basexml |
| Instance:SOAXML |
| User:UnknownUser |
 |
|||
| Private Storage | |||
The
|
|
|
|
|
|
If a persistent class uses %Library.CacheStorage 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.
The location types are:
Location Type COUNTERLOCATION C DATALOCATION D IDLOCATION D INDEXLOCATION I STREAMLOCATION S
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.
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:
Code Operation 0 Update 1 Insert 2 Delete
If the DSTIME parameter is set to MANUAL then the user is responsible for journaling object filing operations.
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 { default = "Name,SSN,Age"; }
The EXTENTSIZE parameter is used to inform the Caché 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 { default = 1000000; }
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.
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.
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 (%Library.CacheStorage) can be managed.
PROPERTYVALIDATION parameter defined in %RegisteredObject overridden here to VALIDATEONSAVE (2).
READONLY = 1 means that objects can be created, opened but not saved or deleted. Tables are projected to SQL as READONLY.
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.
VERSIONCLIENTNAME can be set to a valid CLIENTNAME (see property CLIENTNAME) value. This value will be used for client projections of the %Version property.
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.
|
|
Builds all entries for each index specified in the idxlist argument. If idxlist is empty then all indices that originate in the class are rebuilt.
If autoPurge is true then the indices contained in idxlist will be purged before they are built.
If lockExtent is true 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
%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%Library.CacheStorage or%Library.CacheSQLStorage .
%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.
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 About Concurrency for more details on the optional concurrency argument.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.
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 About Concurrency 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. 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.Returns a
%Status value indicating success or failure.
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 About Concurrency for more details on the optional concurrency argument.
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.
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.
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.
%GUID
%GetLock() 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.
%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.
Returns the persistent object Id, if there is one, of this object.Returns a null string if there is no object Id.
%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.
%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%Library.CacheStorage and %Library.CacheSQLStorage• classmethod %LockId(id As %String , shared As%Boolean = 0) as%Status %LockId() 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%Library.CacheStorage or%Library.CacheSQLStorage .• final method %Oid() as %ObjectIdentity Returns the OID of this object.• classmethod %OnDetermineClass(oid As %ObjectIdentity , ByRef class As%String ) as%Status This callback method is invoked by the%Open method to determine the classname of the object specified by oid.• 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 About Concurrency for more details on the optional concurrency argument.
%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 and returns an OREF referring to the object. id is the Id (not a full OID) value of the object to load.
%OpenId is identical in operation to the%Open method except that it uses an Id value instead of an OID value to find an object instance. Refer to About Concurrency for more details on the optional concurrency argument.
%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) 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
%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 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. All 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%Library.CacheStorage or%Library.CacheSQLStorage . 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 calling
%Close 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
%CacheStorage 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) as%Status Executes a $SortEnd 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 commit argument, if FALSE, causes the data to be discarded. Otherwise, all data placed in the global since the $SortBegin is committed.
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. 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%Library.CacheStorage and %Library.CacheSQLStorage• classmethod %UnlockId(id As %String , shared As%Boolean = 0, immediate As%Boolean = 0) as%Status %UnlockId() 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%Library.CacheStorage or%Library.CacheSQLStorage .
|
|
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.