Class Reference
IRIS for UNIX 2018.1.1
InterSystems: The power behind what matters   
Documentation  Search
Private  Storage  

abstract persistent class %Library.Persistent extends %SwizzleObject

The %Persistent class provides the basic mechanism by which objects are stored to and retrieved from a database.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
14 62 1 3


Summary

Methods
%AddToSaveSet %AddToSyncSet %BuildIndices %CheckConstraints
%CheckConstraintsForExtent %ClassIsLatestVersion %ClassName %ComposeOid
%ConstructClone %Delete %DeleteExtent %DeleteId
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Exists
%ExistsId %Extends %GUID %GUIDSet
%GetLock %GetParameter %GetSwizzleObject %Id
%IsA %IsModified %IsNull %KillExtent
%LockExtent %LockId %New %NormalizeObject
%ObjectIsNull %ObjectModified %Oid %OnBeforeAddToSync
%OnDetermineClass %Open %OpenId %OriginalNamespace
%PackageName %PurgeIndices %Reload %RemoveFromSaveSet
%ResolveConcurrencyConflict %RollBack %Save %SaveDirect
%SerializeObject %SetModified %SortBegin %SortEnd
%SyncObjectIn %SyncTransport %UnlockExtent %UnlockId
%ValidateObject

Subclasses
%CSP.Session %CSP.Util.CSPLogEvent %CSP.Util.Performance
%Calendar.Hijri %Compiler.Informix.ConversionRule %Compiler.Informix.ImportedObject
%Compiler.Informix.Symbol %Compiler.LG.WrapperPropDef %Compiler.TSQL.sysSymbol
%DeepSee.CubeManager.Audit %DeepSee.CubeManager.CubeEvent %DeepSee.CubeManager.CubeRegistry
%DeepSee.DimensionTable %DeepSee.FactTable %DeepSee.IDList
%DeepSee.ListingTable %DeepSee.PMML.Dataset.Base %DeepSee.PMML.Dataset.BootstrapLink
%DeepSee.PMML.Utils.TempResult %DeepSee.Report.DataView %DeepSee.Report.DataViewField
%DeepSee.SetBuilder.ListingTable %DeepSee.SetBuilder.Set %DeepSee.SetBuilder.Snapshot
%DeepSee.Sets.ArraySetRepository %DeepSee.UserLibrary.Folder %DeepSee.UserLibrary.FolderItem
%DeepSee.UserLibrary.NamedFilter %DeepSee.UserLibrary.PivotVariable %DeepSee.UserLibrary.SharedCalcMember
%DeepSee.UserLibrary.UserSetting %DeepSee.UserPortal.Data.Alert %DeepSee.UserPortal.Data.User
%DeepSee.XMLA.EnumerationsRowset %DeepSee.XMLA.KeywordsRowset %DeepSee.XMLA.LiteralsRowset
%DeepSee.XMLA.PropertiesRowset %DeepSee.XMLA.SchemasRowset %DeepSee.extensions.clusters.Sample
%DeepSee.extensions.components.PCA %DeepSee.extensions.modelling.iKnow.MetricValue %DeepSee.extensions.utils.LDA
%Dictionary.ClassDefinition %Dictionary.CompiledClass %Dictionary.CompiledConstraint
%Dictionary.CompiledConstraintMethod %Dictionary.CompiledForeignKey %Dictionary.CompiledIndex
%Dictionary.CompiledIndexMethod %Dictionary.CompiledIndexProperty %Dictionary.CompiledInstanceVar
%Dictionary.CompiledMethod %Dictionary.CompiledParameter %Dictionary.CompiledProjection
%Dictionary.CompiledProperty %Dictionary.CompiledPropertyMethod %Dictionary.CompiledPropertyUDLText
%Dictionary.CompiledQuery %Dictionary.CompiledQueryMethod %Dictionary.CompiledStorage
%Dictionary.CompiledStorageData %Dictionary.CompiledStorageDataValue %Dictionary.CompiledStorageIndex
%Dictionary.CompiledStorageProperty %Dictionary.CompiledStorageSQLMap %Dictionary.CompiledStorageSQLMapData
%Dictionary.CompiledStorageSQLMapRowIdSpec %Dictionary.CompiledStorageSQLMapSub %Dictionary.CompiledStorageSQLMapSubAccessvar
%Dictionary.CompiledStorageSQLMapSubInvalidcondition %Dictionary.CompiledTrigger %Dictionary.CompiledUDLText
%Dictionary.CompiledXData %Dictionary.ForeignKeyDefinition %Dictionary.IndexDefinition
%Dictionary.MethodDefinition %Dictionary.PackageDefinition %Dictionary.ParameterDefinition
%Dictionary.ProjectionDefinition %Dictionary.PropertyDefinition %Dictionary.PropertyUDLTextDefinition
%Dictionary.QueryDefinition %Dictionary.StorageDataDefinition %Dictionary.StorageDataValueDefinition
%Dictionary.StorageDefinition %Dictionary.StorageIndexDefinition %Dictionary.StoragePropertyDefinition
%Dictionary.StorageSQLMapDataDefinition %Dictionary.StorageSQLMapDefinition %Dictionary.StorageSQLMapRowIdSpecDefinition
%Dictionary.StorageSQLMapSubAccessvarDefinition %Dictionary.StorageSQLMapSubDefinition %Dictionary.StorageSQLMapSubInvalidconditionDefinition
%Dictionary.TriggerDefinition %Dictionary.UDLTextDefinition %Dictionary.XDataDefinition
%DocDB.Database %DocDB.Document %Document.Persistent
%ExtentMgr.Catalog.Extent %ExtentMgr.Catalog.Index %ExtentMgr.Catalog.Property
%ExtentMgr.Catalog.ShardIdRanges %ExtentMgr.GUID %ExtentMgr.GlobalRegistry
%FileMan.Field %FileMan.File %FileMan.MappedField
%FileMan.MappedFile %FileMan.MappedFilePackage %Library.AbstractDefinition
%Library.CompiledClass %Library.CompiledMethod %Library.CompiledParameter
%Library.CompiledProperty %Library.CompiledQuery %Library.GlobalEdit
%Library.ListOfPersistentChildObjects %Library.ObjectJournal %Library.ObjectJournalRecord
%Library.ObjectJournalTransaction %Library.PersistentXEP %Library.RoutineIndex
%Library.SQLConnection %Library.SysLogTable %MFT.FolderContents
%MFT.ItemInfo %MFT.UserInfo %MFT.UserList
%Monitor.Alert %Monitor.AlertLog %Monitor.Application
%Monitor.Item %Monitor.ItemGroup %Net.Remote.ActivityLog
%Net.Remote.ObjectGateway %OAuth2.Server.Properties %SQL.DICT.Routine
%SQL.DICT.RoutineColumn %SQL.DICT.Synonym %SQL.Manager.QButtons.Base
%SQL.Manager.UI %SYNC.SyncTime %SYS.Audit
%SYS.Bench.Run %SYS.Bench.Test %SYS.Journal.File
%SYS.Journal.Record %SYS.Journal.Transaction %SYS.MFT.Connection.Base
%SYS.MVACTIVELISTS %SYS.Maint.Bitmap %SYS.Maint.BitmapResults
%SYS.Monitor.ComponentClass %SYS.Monitor.Reading %SYS.Monitor.Sensor
%SYS.Monitor.SensorReading %SYS.Namespace %SYS.OAuth2.Request
%SYS.OpenAM.IdentityServices %SYS.PTools.SQLBenchMarkQueries %SYS.PTools.SQLBenchMarkResults
%SYS.PTools.SQLQuery %SYS.PTools.SQLStats %SYS.PTools.SQLUtilResults
%SYS.PTools.SQLUtilities %SYS.PTools.Stats %SYS.PTools.UtilSQLAnalysisDB
%SYS.PTools.UtilSQLStatements %SYS.PhoneProviders %SYS.Portal.Resources
%SYS.Portal.Users %SYS.ProcessQuery %SYS.SQLObjectQuery
%SYS.SQLStatementCache %SYS.Task.Config %SYS.Task.History
%SYS.TaskSuper %SYS.X509Credentials %SYSTEM.DSTIME
%SYSTEM.TaskConfig %SYSTEM.TaskHistory %Studio.BreakPoint
%Studio.Extension.Menu %Studio.Extension.MenuBase %Studio.OpenDialogItems
%Studio.Package %Studio.Project %Studio.ProjectItem
%Studio.SourceControl.Change %Studio.SourceControl.ItemSet %Studio.Template.HTMLAttribute
%Studio.Template.HTMLElement %Studio.WatchPoint %Studio.WatchVariable
%TSQL.sys.cacheMsgXRef %TSQL.sys.columns %TSQL.sys.constraints
%TSQL.sys.indexes %TSQL.sys.keys %TSQL.sys.messages
%TSQL.sys.messagesXRef %TSQL.sys.objects %TSQL.sys.procedure
%TSQL.sys.snf %TSQL.sys.types %UIMA.AnnotationStore.Annotation
%UIMA.AnnotationStore.Sofa %UIMA.AnnotationStore.Type %UnitTest.Result.TestAssert
%UnitTest.Result.TestCase %UnitTest.Result.TestInstance %UnitTest.Result.TestMethod
%UnitTest.Result.TestSuite %WebStress.Calls %WebStress.Control
%WebStress.Errors %WebStress.Iterations %WebStress.Machines.ApplicationServers
%WebStress.Machines.Generators %WebStress.Machines.WebServers %WebStress.Playback
%WebStress.Playback.Status %WebStress.Results.AppServerStats %WebStress.Results.Calls
%WebStress.Results.General %WebStress.Results.Iterations %WebStress.Results.PageSummary
%WebStress.Results.Summary %WebStress.Run %WebStress.Scripts
%WebStress.Scripts.URLS %WebStress.Scripts.URLS.Parameters %WebStress.Tables.NoDelay
%WebStress.Tables.NoResults %WebStress.Tests %WebStress.Tests.Parameters
%WebStress.Utils.Version %XML.Catalog %XML.XPATH.Result
%XSQL.Catalog.Informix.syscolumns %XSQL.Catalog.Informix.systables %XSQL.System.CacheMessageXRef
%XSQL.System.Message %XSQL.System.MessageXRef %ZEN.Mobile.RSS.Application
%ZEN.Mobile.RSS.Feed %ZEN.Mobile.RSS.Item %ZEN.Report.RenderServer
%ZEN.Report.TestReport %ZEN.Report.Version %iFind.BitIterator
%iFind.Comp %iFind.Entity %iFind.EntityI
%iFind.Index.AbstractAttribute %iFind.Index.AbstractAttributePos %iFind.Index.AbstractDominance
%iFind.Index.AbstractEntBits %iFind.Index.AbstractEntSpread %iFind.Index.AbstractEntSpreadRec
%iFind.Index.AbstractEntity %iFind.Index.AbstractPath %iFind.Index.AbstractPathVal
%iFind.Index.AbstractProximity %iFind.Index.AbstractWordPos %iFind.OriginalWord
%iFind.Stem %iFind.Transformation %iFind.Word
%iFind.WordTransformation %iKnow.Configuration %iKnow.Domain
%iKnow.KB.Acronym %iKnow.KB.Filter %iKnow.KB.Knowledgebase
%iKnow.KB.Label %iKnow.KB.Lexrep %iKnow.KB.Metadata
%iKnow.KB.PreprocessFilter %iKnow.KB.Regex %iKnow.KB.Rule
%iKnow.LB.Entry %iKnow.LB.Languagebase %iKnow.Matching.MatchingProfile
%iKnow.Metrics.Metric %iKnow.Objects.Attributes %iKnow.Objects.BlackList
%iKnow.Objects.CcUnique %iKnow.Objects.CrcInSourceDetails %iKnow.Objects.CrcOccurrence
%iKnow.Objects.CrcUnique %iKnow.Objects.Dictionary %iKnow.Objects.DictionaryElement
%iKnow.Objects.DictionaryItem %iKnow.Objects.DictionaryMatch %iKnow.Objects.DictionaryTerm
%iKnow.Objects.EntityInSourceDetails %iKnow.Objects.EntityMatch %iKnow.Objects.EntityOccurrence
%iKnow.Objects.EntityUnique %iKnow.Objects.MetadataField %iKnow.Objects.MetadataValue
%iKnow.Objects.Path %iKnow.Objects.Sentence %iKnow.Objects.Source
%iKnow.Objects.VirtualCrcOccurrence %iKnow.Objects.VirtualCrcUnique %iKnow.Objects.VirtualDictionaryMatch
%iKnow.Objects.VirtualEntityOccurrence %iKnow.Objects.VirtualEntityUnique %iKnow.Objects.VirtualSentence
%iKnow.Objects.VirtualSource %iKnow.Stemming.Configuration %iKnow.Stemming.Rule
%iKnow.Tables.AbstractCustomAnnotation %iKnow.TextTransformation.HeaderTable %iKnow.TextTransformation.KeyTable
%iKnow.UserDictionary %iKnow.ont.temp.SearchResult Backup.Task
Config.Cluster Config.ComPorts Config.ConfigFile
Config.Conversions Config.Databases Config.Debug
Config.DeviceSubTypes Config.Devices Config.ECP
Config.ECPServers Config.IO Config.Journal
Config.LicenseServers Config.MagTapes Config.MapGlobals
Config.MapMirrors Config.MapPackages Config.MapRoutines
Config.MapShadows Config.MapShards Config.MirrorMember
Config.Mirrors Config.Miscellaneous Config.Monitor
Config.NLS.Locales Config.NLS.SubTables Config.NLS.Tables
Config.Namespaces Config.SQL Config.Shadows
Config.Shards Config.SqlSysDatatypes Config.SqlUserDatatypes
Config.Startup Config.Telnet Config.config
DataMove.Data DataMove.Global DataMove.Range
EMS.Connection.Data EMS.Connection.Parameters EMS.Connection.Policy
EMS.Error EMS.Instance EMS.LicenseKey
EMS.Notification EMS.Service.Base EMS.ServiceMessageData
EMS.ServiceMessageDebug INFORMATION.SCHEMA.CHECKCONSTRAINTS INFORMATION.SCHEMA.COLUMNS
INFORMATION.SCHEMA.CONSTRAINTCOLUMNUSAGE INFORMATION.SCHEMA.CONSTRAINTTABLEUSAGE INFORMATION.SCHEMA.INDEXES
INFORMATION.SCHEMA.KEYCOLUMNUSAGE INFORMATION.SCHEMA.PARAMETERS INFORMATION.SCHEMA.REFERENTIALCONSTRAINTS
INFORMATION.SCHEMA.ROUTINES INFORMATION.SCHEMA.SCHEMATA INFORMATION.SCHEMA.STATEMENTCHILDREN
INFORMATION.SCHEMA.STATEMENTLOCATIONS INFORMATION.SCHEMA.STATEMENTPRIVACTIONS INFORMATION.SCHEMA.STATEMENTPRIVOBJECTS
INFORMATION.SCHEMA.STATEMENTRELATIONS INFORMATION.SCHEMA.STATEMENTS INFORMATION.SCHEMA.TABLECONSTRAINTS
INFORMATION.SCHEMA.TABLES INFORMATION.SCHEMA.TRIGGERS INFORMATION.SCHEMA.VIEWCOLUMNUSAGE
INFORMATION.SCHEMA.VIEWS INFORMATION.SCHEMA.VIEWTABLEUSAGE Inventory.Component
Inventory.Scan Monitor.Sample OAuth2.AccessToken
OAuth2.Client OAuth2.Client.Metadata OAuth2.Server.AccessToken
OAuth2.Server.Client OAuth2.Server.Configuration OAuth2.Server.JWTid
OAuth2.Server.Metadata OAuth2.Server.Session OAuth2.ServerDefinition
PKI.CAClient PKI.CAServer PKI.CSR
PKI.Certificate SYS.DataCheck.Configuration SYS.DataCheck.LogEntry
SYS.DataCheck.Query SYS.DataCheck.RangeList SYS.DataCheck.RunParameters
SYS.DataCheck.Statistics SYS.DataCheck.System SYS.DataCheck.Workflow
SYS.Database SYS.History.Daily SYS.History.Hourly
SYS.History.PerfData SYS.History.SharedMemoryData SYS.History.SysData
SYS.Monitor.Alert SYS.Monitor.Health.Chart SYS.Monitor.Health.HealthAlert
SYS.Monitor.Health.Period SYS.Monitor.Health.Rule SYS.Monitor.Health.SensorClass
SYS.Monitor.Health.SensorObject SYS.Shadowing.Shadow Security.Applications
Security.DocDBs Security.Domains Security.Events
Security.LDAPConfigs Security.Resource Security.Resources
Security.Roles Security.SQLAdminPrivilegeSet Security.SQLPrivileges
Security.SQLRoleGrantOption Security.SSLConfigs Security.Services
Security.System Security.Users Security.X509Users
TCPTrace.Config TCPTrace.Log

Parameters

• 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 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.
• 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.
• 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.
• 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 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 super class 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.

Methods

• classmethod %BuildIndices(pIndexList As %RawString = "", pAutoPurge As %Integer = 1, pLockFlag As %Integer = 0, pJournalFlag As %Integer = 1, pStartID As %RawString = "", pEndID As %RawString = "", pIgnoreIndexList As %RawString = "") 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 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 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 journal status is not altered during BuildIndices(). The default value of this argument is 1 (TRUE).

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 $listbuild 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 %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 oif IDs to add the index entries for these new items.

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

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.

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

• 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
%GUID
• 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.
• 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 Object Concurrency Options 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 Object Concurrency Options 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, pIgnoreIndexList As %RawString = "") 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 $listbuild 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 %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 %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 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 %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 $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.

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


Copyright © 1997-2018 InterSystems Corporation, Cambridge, MA