For information on converting to InterSystems IRIS, see the
InterSystems IRIS Adoption Guide
and the InterSystems IRIS In-Place Conversion Guide,
both available on the WRC Distributions page (login required).
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.
%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.
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.
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.
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.
%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 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.
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)
%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.
abstract private method %OnAfterSave(insert As %Boolean) as %Status
This callback method is invoked by the %Save() method to
provide notification that the object is being saved. It is called after
the object's data has been successfully written to disk.
insert will be set to 1 if this object is being saved for the first time.
If this method returns an error then the call to %Save() will fail.
abstract private method %OnBeforeSave(insert As %Boolean) as %Status
This callback method is invoked by the %Save() method to
provide notification that the object is being saved. It is called before
any data is written to disk.
insert will be set to 1 if this object is being saved for the first time.
If this method returns an error then the call to %Save() will fail.
Inherited description: This callback method is invoked by the %ConstructClone() method to
provide notification that a clone of an object is being created. It passes in the
oref of the object that was cloned in object.
If this method returns an error then the object will not be created.
This callback method is invoked by the %Reload() method to
provide notification that the object specified by oid was reloaded.
%Reload() is invoked by %Open when the object identified by the OID
is already in memory.
If this method returns an error then the object will not be opened.
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.
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.
%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.
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.
private method %SaveData(ByRef id As %String) 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.
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.
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.
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).
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.
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.
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.
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.
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.
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 ! } }
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.
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.
