%Stream.Object

abstract stream class %Stream.Object extends %Library.RegisteredObject

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 Caché streams are used to create large (greater than 32K) object attributes.

Property Inventory

Method Inventory

Parameters

parameter DEFAULTCONCURRENCY = $zu(115,10);

Properties

property %Location as %String (MAXLEN = 1024);
%Location is place where stream data is stored. For global streams this will be a global reference. For file streams it may be a directory. This is not the location of this specific stream, but the root location of what may be multiple streams.
Property methods: %LocationDisplayToLogical(), %LocationGet(), %LocationIsValid(), %LocationLogicalToDisplay(), %LocationLogicalToOdbc(), %LocationNormalize()
property AtEnd as %Boolean [ InitialExpression = 1 ];
The AtEnd property is set to true (1) when, during a read, a stream has reached the end of its data source.
Property methods: AtEndDisplayToLogical(), AtEndGet(), AtEndIsValid(), AtEndLogicalToDisplay(), AtEndNormalize(), AtEndSet()
property Id as %String;
Id is the unique identifier for a stream within the %Location.
Property methods: IdDisplayToLogical(), IdGet(), IdIsValid(), IdLogicalToDisplay(), IdLogicalToOdbc(), IdNormalize(), IdSet()
property LastModified as %TimeStamp [ Calculated ];
LastModified is a read-only property containing the %TimeStamp of the last modification to this stream. If the stream is null then it will report "".
Property methods: LastModifiedDisplayToLogical(), LastModifiedIsValid(), LastModifiedLogicalToDisplay(), LastModifiedNormalize(), LastModifiedOdbcToLogical()
property Size as %Integer [ Calculated ];
Size is a read-only property containing the current size of the stream (in bytes for a binary stream and characters for a character stream).

If a specific stream implementation cannot determine the size of the stream then Size will be equal to -1.
VMS does not support moving to a position in a file or providing the current position in a file. On VMS if a BOM is included at the start of the file it may be included in the size calculated.

Property methods: SizeDisplayToLogical(), SizeIsValid(), SizeLogicalToDisplay(), SizeNormalize()

Methods

classmethod %CheckUnique(idxlist As %List = "") as %Status
final classmethod %Delete(oid As %ObjectIdentity = "", concurrency As %Integer) 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 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.

classmethod %DeleteExtent(concurrency As %Integer, ByRef deletecount, ByRef instancecount) 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 About Concurrency for more details on the optional concurrency argument.

Returns a %Status value indicating success or failure.

final classmethod %DeleteId(id As %String, concurrency As %Integer) 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 and Id value instead of an OID value to find an object. Refer to About Concurrency for more details on the optional concurrency argument.

classmethod %Exists(soid As %ObjectIdentity) as %Boolean
Checks to see if the object identified by the OID oid exists in the extent.

Returns %Boolean TRUE is 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.

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.

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.

method %IsNull() as %Boolean
Returns true if this is a "NULL" stream; that is, a stream which has never been written to and saved and has no stream attributes. This is used by the Caché ODBC server.
classmethod %KillExtent() as %Status
classmethod %LOBPrefetch(soid As %ObjectIdentity, prefetchsize As %Integer, ByRef data As %String) as %Integer
Given a soid if the length is <= prefetchsize then return the data in data. The return value is 0 meaning the stream is over this size, 1 for character stream 2 for binary stream. 3 for non-NULL empty Stream (Size=0)
method %LocationSet(val As %String) as %Status
method %LockStream()
%LockStream() Obtain a shared lock on the current stream object. %Locked is set to 1 if the stream was successfully locked. If the stream cannot be locked then %Locked is set to 0. No lock is attempted unless %GetLockReference returns a non-null value. If a lock is attempted but cannot be acquired (lock timeout expires) then this method will throw an exception. The caller is expected to catch the exception and process it appropriately. Throws %Exception.AbstractException, most often a StatusException.
classmethod %ObjectIsNull(soid As %ObjectIdentity) as %Boolean
Return true if this stream oid is a null stream and false if the stream is not null
classmethod %ObjectSize(soid As %ObjectIdentity) as %Integer
Returns the size of the stream pointed to by soid in the most efficient way possible.
method %Oid() as %ObjectIdentity
Returns the OID of this object.
final classmethod %Open(soid As %ObjectIdentity, concurrency As %Integer, 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: 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 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, 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 and 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.

method %ReleaseLock(locktype) as %Status
Releases a lock for the current instance.

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.
Fails if the locktype parameter is not one of the values described above.

Returns a %Status value indicating success or failure.

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.

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() saves the object and generates a new OID for 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 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 %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.

method %UnlockStream(immediate As %Boolean = 0)
%UnlockStream() Release the shared lock on the current stream object. If the immediate argument is 1 then the lock is released using the "I" flag.
method Clear() as %Status
Clear the contents of this Stream from permanent storage. This will remove the permanent stream storage and any temporary stream and initialise the stream to its initial state that it starts in, including removing all the stream attributes.

Returns a %Status value indicating success or failure.

method CopyFrom(source As %Stream.Object) as %Status
Copies the contents of source into this Stream.

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.

method CopyFromAndSave(source As %Stream.Object) as %Status
Copy the stream from source into the current stream ignoring anything already in the current stream and save the result to the permanent location. This is used to optimise the copying of say a %GlobalCharacterStream to another %GlobalCharacterStream to avoid copying into temporary storage first and then moving this to the permanent storage when SaveStream() is called.

Note that any locking or transaction handling must be done by the caller.

method FindAt(position As %Integer, target As %CacheString, ByRef tmpstr As %CacheString = "", caseinsensitive As %Boolean = 0) as %Integer
Find the first occurrence of target in the stream starting the search at position. It returns the position at this match starting at the beginning of the stream. If it does not find the target string then return -1. If position=-1 then start searching from the current location and just return the offset from the last search, useful for searching through the entire file. If you are doing this you should pass in tmpstr by reference in every call which is used as a temporary location to store information being read so the next call will start where the last one left off. If you pass caseinsensitive=1 then the search will be case insensitive rather than the default case sensitive search.
method Flush() as %Status
Flush any output in the stream not already saved.
method GetStreamId() as %String
Returns an full id value (including class name) with which the Stream implementation has stored the stream.
method InputFromDevice(ByRef len As %Integer = 0, timeout As %Integer = 20) as %Status
Input len characters from the current device into the stream. This is equivalent to doing a series of reads and calling Write() for each of them but it may be optimised by the subclasses. On return len will be the number of characters still to read in (if no timeout has occured this should be 0).
classmethod IsCharacter() as %String
Return true if this is a character stream and false if it is a binary stream.
method IsNull() as %Boolean
Returns true if this is a "NULL" stream; that is, a stream which has never been written to and saved and has no stream attributes. This is used by the Caché ODBC server.
method LastModifiedGet() as %TimeStamp
method MoveTo(position As %Integer) as %Boolean
Move to this position in the stream. If this suceeds then return true, else return false. Note this implementation is not efficient because it searches from the start of the stream, it can be improved upon in specific subclasses. Note that moving to position 1 will be at the start of the stream, position 2 will be at the second character of the stream, etc.
method MoveToEnd() as %Status
Move to the end of the stream so the next Write will be appended to the end. This allows you to read from a stream, then MoveToEnd() and append new data, where just calling Write() after a read will clear the stream before writing new data.

Returns a %Status value indicating success or failure.

method OutputToDevice(ByRef len As %Integer = -1) as %Status
Write out len characters of the stream to the current device starting from the current position. This method is optimised for performance by the various sub classes. If len is omitted or set to -1 then it will write out the entire stream starting at the beginning.
method OutputToDeviceAt(position As %Integer, ByRef length As %Integer) as %Status
Output the stream to the current device starting at position of length length. The length if passed is the number of characters to output, if not passed it will output from position to the end of the stream.
method Read(ByRef len As %Integer = 32656, ByRef sc As %Status) as %CacheString
Reads up to len characters from the current position in the stream. The current position is advanced by the number of characters read. Upon exit, len is set to the actual number of characters read. If a read occurs when the stream position is at the end of the stream, len will be set to -1 and Read() will return a null string (""). If no len is passed in, ie. 'Read()' then it is up to the Read implementation as to how much data to return. Some stream classes use this to optimize the amount of data returned to align this with the underlying storage of the stream.

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.

method ReadLine(ByRef len As %Integer = 32000, ByRef sc As %Status, ByRef eol As %Boolean) as %CacheString
Read a line from the stream. This will look for the line terminator in the stream and once it finds the terminator it will return the string minus the terminator character/s. If it reaches the end of the stream before it finds a terminator it will return the data it has so far, and if you specify a maximum size in len it will only read up to this number of characters. On exit len will contain the actual number of characters read. The byref argument sc will return a %Status if any error occured during the read and the byref argument eol is true if it found the line terminator and false otherwise. So for example you can read in a stream a line at a time and output the results to the current device with: 
While 'stream.AtEnd { Write stream.ReadLine(,.sc,.eol) If $$$ISERR(sc) { Write "ERROR" Quit } If eol { Write ! } }
method ReadLineIntoStream(ByRef sc As %Status) as %Stream.Object
method ReadSQL(start As %Integer = 1, end As %Integer = -1) as %String
SQL specific method for reading stream data
method Rewind() as %Status
Go back to the start of the stream.
method SerializeToSyncSet(ss As %SYNC.SyncSet, iPtr As %Integer, property As %String) as %Status
SerializeToSyncSet copies the stream value from the current object to the sync set global. When the sync set is imported into another system the stream value will be copied from the global back to a stream of the container property's current type.
method SizeGet() as %Integer
classmethod StreamOIDIsNull(soid As %ObjectIdentity) as %Boolean
Return true if this stream oid is a null stream and false if the stream is not null
method SyncStreamIn(ss As %SYNC.SyncSet, iPtr As %Integer, property As %String) as %Status
SyncStreamIn copies the stream value from the sync set global into the current object.
method Write(data As %CacheString) as %Status
Appends the string data to the stream and advances the current stream position by the number of characters in data.

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.

method WriteLine(data As %CacheString = "") as %Status
Appends the string data along with a line terminator to the stream and advances the current stream position by the number of characters in data plus the line terminator.

Returns a %Status value indicating success or failure.

Inherited Members

Inherited Methods

Subclasses