Working with Persistent Objects

Rollback

The %Save() method automatically saves all the objects in its SaveSet as a single transaction. If any of these objects fail to save, then the entire transaction is rolled back. In this rollback, InterSystems IRIS does the following:

1. It reverts assigned IDs.

2. It recovers removed IDs.

3. It recovers modified bits.

4. It invokes the %OnRollBack() callback method, if implemented, for any object that had been successfully serialized.

   InterSystems IRIS does not invoke this method for an object that has not been successfully serialized, that is, an object that is not valid.

Saving Objects and Transactions

As noted previously, the %Save() method automatically saves all the objects in its SaveSet as a single transaction. If any of these objects fail to save, then the entire transaction is rolled back.

If you wish to save two or more unrelated objects as a single transaction, however, you must enclose the calls to %Save() within an explicit transaction: that is, you must start the transaction using the TSTART command and end it with the TCOMMIT command.

For example:

 // start a transaction
 TSTART

 // save first object
 Set sc = obj1.%Save()

 // save second object (if first was save)
 If ($$$ISOK(sc)) {
     Set sc = obj2.%Save()
 }

 // if both saves are ok, commit the transaction
 If ($$$ISOK(sc)) {
     TCOMMIT
 }

There are two things to note about this example:

1. The %Save() method knows if it is being called within an enclosing transaction (because the system variable, $TLEVEL, will be greater than 0).

2. If any of the %Save() methods within the transaction fails, the entire transaction is rolled back (the TROLLBACK command is invoked). This means that an application must test every call to %Save() within a explicit transaction and if one fails, skip calling %Save() on the other objects and skip invoking the final TCOMMIT command.

Testing for Object Existence with ObjectScript

The %ExistsId() class method checks a specified ID; it returns a true value (1) if the specified object is present in the database and false (0) otherwise. It is available to all classes that inherit from %PersistentOpens in a new tab. For example:

 Write ##class(Sample.Person).%ExistsId(1),!   // should be 1 
 Write ##class(Sample.Person).%ExistsId(-1),!  // should be 0

Here, the first line should return 1 because Sample.Person inherits from %PersistentOpens in a new tab and the SAMPLES database provides data for this class.

You can also use the %Exists() method, which requires an OID rather than an ID. An OID is a permanent identifier unique to the database that includes both the ID and the class name of the object. For more details, see Identifiers for Saved Objects: ID and OID.

Testing for Object Existence with SQL

To test for the existence of a saved object with SQL, use a SELECT statement that selects a row whose %ID field matches the given ID. (The identity property of a saved object is projected as the %ID field.)

For example, using embedded SQL:

 &sql(SELECT %ID FROM Sample.Person WHERE %ID = '1')
 Write SQLCODE,!  // should be 0: success

 &sql(SELECT %ID FROM Sample.Person WHERE %ID = '-1')
 Write SQLCODE,!  // should be 100: not found

Here, the first case should result in an SQLCODE of 0 (meaning success) because Sample.Person inherits from %PersistentOpens in a new tab and the SAMPLES database provides data for this class.

The second case should result in an SQLCODE of 100, which means that the statement successfully executed but returned no data. This is expected because the system never automatically generates an ID value less than zero.

For more information on embedded SQL, see the chapter “Embedded SQL” in Using InterSystems SQL. For more information on SQLCODE, see “SQLCODE Values and Error Messages” in the InterSystems IRIS Error Reference.

Multiple Calls to %OpenId()

If %OpenId() is called multiple times within an InterSystems IRIS process for the same ID and the same object, only one object instance is created in memory. All subsequent calls to %OpenId() return a reference to the object already loaded into memory.

For example, consider this class featuring multiple %OpenId() calls to the same object:

Class User.TestOpenId Extends %RegisteredObject
{

ClassMethod Main()
{
   set A = ##class(Sample.Person).%OpenId(1)
   write "A: ", A.Name

   set A.Name = "David"
   write !, "A after set: ", A.Name

   set B = ##class(Sample.Person).%OpenId(1)
   write !, "B: ", B.Name

   do ..Sub()

   job ..JobSub()
   hang 1
   write !, "D in JobSub: ", ^JobSubD
   kill ^JobSubD

   kill A, B
   set E = ##class(Sample.Person).%OpenId(1)
   write !, "E:", E.Name
}

ClassMethod Sub()
{
   set C = ##class(Sample.Person).%OpenId(1)
   write !, "C in Sub: ", C.Name
}

ClassMethod JobSub()
{
   set D = ##class(Sample.Person).%OpenId(1)
   set ^JobSubD = D.Name
}

}

Calling the Main() method produces these results:

1. The initial %OpenId() call loads the instance object into memory. The A variable references this object and you can modify the loaded object through this variable.

      set A = ##class(Sample.Person).%OpenId(1)
      write "A: ", A.Name
   

   

   A: Uhles,Norbert F.

      set A.Name = "David"
      write !, "A after set: ", A.Name
   

   

   A after set: David

2. The second %OpenId() call does not reload the object from the database and does not overwrite the changes made using variable A. Instead, variable B references the same object as variable A.

      set B = ##class(Sample.Person).%OpenId(1)
      write !, "B: ", B.Name
   

   

   B: David

3. The third %OpenId() call, in the Sub() method, also references the previously loaded object. This method is part of the same InterSystems IRIS process as the Main() method. Variable C references the same object as variables A and B, even though those variables are not available within the scope of this method. At the end of the Sub() method, the process returns back to the Main() method, the variable C is destroyed, and variables A and B are back in scope.

      do ..Sub()
   

   

   ClassMethod Sub()
   {
      set C = ##class(Sample.Person).%OpenId(1)
      write !, "C in Sub: ", C.Name
   }

   

   C in Sub: David

4. The fourth %OpenId() call, in the JobSub() method, is run in a separate InterSystems IRIS process by using the JOB command. This new process loads a new instance object into memory, and variable D references this new object.

      job ..JobSub()
      hang 1
      write !, "D in JobSub: ", ^JobSubD
      kill ^JobSubD
   

   

   ClassMethod JobSub()
   {
      set D = ##class(Sample.Person).%OpenId(1)
      set ^JobSubD = D.Name
   }

   

   D in JobSub: Uhles,Norbert F.

5. The fifth %OpenId() call occurs after deleting all variables (A and B) that reference the loaded object in the original process, thereby removing that object from memory. As with the previous %OpenId() call, this call also loads a new instance object into memory, and variable E references this object.

      kill A, B
      set E = ##class(Sample.Person).%OpenId(1)
      write !, "E:", E.Name

   

   E: Uhles,Norbert F.

To force a reload of an object being loaded multiple times, you can use the %Reload() method. Reloading the object reverts any changes made to the object that were not saved. Any previously assigned variables reference the reloaded version. For example:

 set A = ##class(Sample.Person).%OpenId(1)
 write "A: ", A.Name // A: Uhles,Norbert F.
 
 set A.Name = "David"
 write !, "A after set: ", A.Name // David
 
 set B = ##class(Sample.Person).%OpenId(1)
 write !, "B before reload: ", B.Name // David

 do B.%Reload()
 write !, "B after reload: ", B.Name // Uhles,Norbert F.
 write !, "A after reload: ", A.Name // Uhles,Norbert F.

Concurrency

The %OpenId() method takes an optional concurrency argument as input. This argument specifies the concurrency level (type of locks) that should be used to open the object instance.

If the %OpenId() method is unable to acquire a lock on an object, it fails.

To raise or lower the current concurrency setting for an object, reopen it with %OpenId() and specify a different concurrency level. For example,

 set person = ##class(Sample.Person).%OpenId(6,0)

opens person with a concurrency of 0 and the following effectively upgrades the concurrency to 4:

 set person = ##class(Sample.Person).%OpenId(6,4)

Specifying a concurrency level of 3 (shared, retained lock) or 4 (shared, exclusive lock) forces a reload of the object when opening it. For more information on the possible object concurrency levels, see Object Concurrency Options.

The %DeleteId() Method

The %DeleteId() method deletes an object that is stored within a database, including any stream data associated with the object. This method is as follows:

classmethod %DeleteId(id As %String, concurrency As %Integer = -1) as %Status

Where:

• id is the of the object to open.

  In these examples, the ID is an integer. The next chapter describes how you can define a class so that the ID is instead based on a unique property of the object.

• concurrency is the concurrency level (locking) used when deleting the object.

For example:

 Set sc = ##class(MyApp.MyClass).%DeleteId(id)

%DeleteId() returns a %StatusOpens in a new tab value indicating whether the object was deleted or not.

%DeleteId() calls the %OnDelete() callback method (if present) before deleting the object. %OnDelete() returns a %StatusOpens in a new tab value; if %OnDelete() returns an error value, then the object will not be deleted, the current transaction is rolled back, and %DeleteId() returns an error value.

%DeleteId() calls the %OnAfterDelete() callback method (if present) after deleting the object. This call occurs immediately after %DeleteData() is called, provided that %DeleteData() does not return an error. If %OnAfterDelete() returns an error, then the current transaction is rolled back, and %DeleteId() returns an error value.

Lastly, %DeleteId() calls the %OnDeleteFinally() callback method, if present. This callback method is called after the transaction has completed and the status of the deletion has been finalized.

Note that the %DeleteId() method has no effect on any object instances in memory.

You can also use the %Delete() method, which requires an OID rather than an ID. An OID is a permanent identifier unique to the database that includes both the ID and the class name of the object. For more details, see Identifiers for Saved Objects: ID and OID.

The %DeleteExtent() Method

The %DeleteExtent() method deletes every object (and subclass of object) within its extent. Specifically it iterates through the entire extent and invokes the %DeleteId() method on each instance.

The %KillExtent() Method

The %KillExtent() method directly deletes the globals that store an extent of objects (not including data associated with streams). It does not invoke the %DeleteId() method and performs no referential integrity actions. This method is simply intended to serve as a help to developers during the development process. (It is similar to the TRUNCATE TABLE command found in older relational database products.) If you need to delete every object in an extent, including associated stream data, use %DeleteExtent() instead.

Why Specify Concurrency?

The following scenario demonstrates why it is important to control concurrency appropriately when you read or write objects. Consider the following scenario:

1. Process A opens an object without specifying the concurrency.

   SAMPLES>set person = ##class(Sample.Person).%OpenId(5)
    
   SAMPLES>write person
   1@Sample.Person

   

2. Process B opens the same object with the concurrency value of 4.

   SAMPLES>set person = ##class(Sample.Person).%OpenId(5, 4)
    
   SAMPLES>write person
   1@Sample.Person

   

3. Process A modifies a property of the object and attempts to save it using %Save() and receives an error status.

   SAMPLES>do person.FavoriteColors.Insert("Green")
   
   SAMPLES>set status = person.%Save()
    
   SAMPLES>do $system.Status.DisplayError(status)
    
   ERROR #5803: Failed to acquire exclusive lock on instance of 'Sample.Person'

   

This is an example of concurrent operations without adequate concurrency control. For example, if process A could possibly save the object back to the disk, it must open the object with concurrency 4 to ensure it can save the object without conflict with other processes. (These values are discussed later in this chapter.) In this case, Process B would then be denied access (failed with a concurrency violation) or would have to wait until Process A releases the object.

Concurrency Values

This section describes the possible concurrency values. First, note the following details:

• Atomic writes are guaranteed when concurrency is greater than 0.

• InterSystems IRIS acquires and releases locks during operations such as saving and deleting objects; the details depend upon the concurrency value, what constraints are present, lock escalation status, and the storage structure.

• In all cases, when an object is removed from memory, any locks for it are removed.

The possible concurrency values are as follows; each value has a name, also shown in the list.

Concurrency and Swizzled Objects

An object referenced by a property is swizzled on access using the default concurrency defined by the swizzled object’s class. If the default is not defined for the class, the object is swizzled using the default concurrency mode of the process. The swizzled object does not use the concurrency value of the object that swizzles it.

If the object being swizzled is already in memory, then swizzling does not actually open the object — it simply references the existing in-memory object; in that case, the current state of the object is maintained and the concurrency is unchanged.

There are two ways to override this default behavior:

• Upgrade the concurrency on the swizzled object with a call to the %Open() method that specifies the new concurrency. For example:

   Do person.Spouse.%OpenId(person.Spouse.%Id(),4,.status) 

  

  where the first argument to %OpenId()Opens in a new tab specifies the ID, the second specifies the new concurrency, and the third (passed by reference) receives the status of the method.

• Set the default concurrency mode for the process before swizzling the object. For example:

   Set olddefault = $system.OBJ.SetConcurrencyMode(4) 

  

  This method takes the new concurrency mode as its argument and returns the previous concurrency mode.

  When you no longer need a different concurrency mode, reset the default concurrency mode as follows:

   Do $system.OBJ.SetConcurrencyMode(olddefault)