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.
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.
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.
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.
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.
%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.
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
This is a Set accessor method for the %Location property.
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.
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.
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.
%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.
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.
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.
%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.
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.
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.
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).
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
This is a Get accessor method for the LastModified property.
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.
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.
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 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
This is a Get accessor method for the Size property.
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.
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.