%Stream.Object
abstract stream class %Stream.Object extends %Library.RegisteredObject
For information on this class, see Working with Streams.
The %Stream.Object class provides the basic mechanism by which stream objects are stored to and retrieved from a database.A stream represents an arbitrary array of characters (or bytes) and a current position. The basic stream interface provides the ability to read data from a stream, write data to the stream, and rewind the current position to the beginning of the stream.
Within InterSystems IRIS, streams are used to create large (greater than 32K) object attributes.
Property Inventory
Method Inventory
- %CheckUnique()
- %Delete()
- %DeleteExtent()
- %DeleteId()
- %Exists()
- %ExistsId()
- %GetSwizzleObject()
- %Id()
- %IsNull()
- %KillExtent()
- %LOBPrefetch()
- %LocationSet()
- %LockStream()
- %ObjectIsNull()
- %ObjectSize()
- %Oid()
- %Open()
- %OpenId()
- %ReleaseLock()
- %Reload()
- %RollBack()
- %Save()
- %UnlockStream()
- Clear()
- CopyFrom()
- CopyFromAndSave()
- FindAt()
- Flush()
- GetStreamId()
- InputFromDevice()
- IsCharacter()
- IsNull()
- LastModifiedGet()
- MoveTo()
- MoveToEnd()
- OutputToDevice()
- OutputToDeviceAt()
- Read()
- ReadLine()
- ReadLineIntoStream()
- ReadSQL()
- Rewind()
- SerializeToSyncSet()
- SizeGet()
- StreamOIDIsNull()
- SyncStreamIn()
- Write()
- WriteLine()
Parameters
Properties
If a specific stream implementation cannot determine the size of the stream then
Size will be equal to -1.
Methods
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.
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.
Returns a %Status value indicating success or failure.
%DeleteId() is identical in operation to the %Delete() method except that it uses and Id value instead of an OID value to find an object. Refer to Object Concurrency Options for more details on the optional concurrency argument.
Returns %Boolean TRUE is 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 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.
%OpenId() is identical in operation to the %Open() method except that it uses and 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.
The locktype argument specifies the type of lock to release. It can take the following values:
| "e": Exclusive | An exclusive lock will prevent any other process from acquiring any type of lock on this object. |
| "s": Shared | A shared lock will allow other processes to acquire shared locks but will prevent other processes from acquiring an exclusive lock. |
Returns a %Status value indicating success or failure.
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:
| 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 allocate the OID needed by this object. |
| 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 being 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.
For example, you can copy oldstream into a new stream:
Set newstream=##class(%GlobalCharacterStream).%New() Do newstream.CopyFrom(oldstream)
Returns a %Status value indicating success or failure.
Note that any locking or transaction handling must be done by the caller.
If position=-1 then it starts searching from the location found in the previous search and returns the offset from the last search. This is useful for searching through the entire file. If you are doing this, you should pass in tmpstr by reference in every call. This is used to store the last buffer read, so the next call will start where the last one left off. If caseinsensitive=1 then the search will be case insensitive, rather than the default case-sensitive search.
Returns a %Status value indicating success or failure.
You must call Rewind() if you want to read a stream from the beginning again. Calling Read() after Write() implicitly ends the Write() operation and rewinds to the start of the stream.
Returns a string up to len characters long. The byref argument sc will return a %Status if any error occurred during the read.
While 'stream.AtEnd { Write stream.ReadLine(,.sc,.eol) If $$$ISERR(sc) { Write "ERROR" Quit } If eol { Write ! } }
Note that a write operation immediately following a read or rewind will clear out the existing data in the stream.
Returns a %Status value indicating success or failure.
Returns a %Status value indicating success or failure.
Inherited Members
Inherited Methods
- %AddToSaveSet()
- %ClassIsLatestVersion()
- %ClassName()
- %ConstructClone()
- %DispatchClassMethod()
- %DispatchGetModified()
- %DispatchGetProperty()
- %DispatchMethod()
- %DispatchSetModified()
- %DispatchSetMultidimProperty()
- %DispatchSetProperty()
- %Extends()
- %GetParameter()
- %IsA()
- %IsModified()
- %New()
- %NormalizeObject()
- %ObjectModified()
- %OriginalNamespace()
- %PackageName()
- %RemoveFromSaveSet()
- %SerializeObject()
- %SetModified()
- %ValidateObject()