Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
1	8	58

Properties
%Location	AtEnd	Id	LastModified	Size

Methods
%%OIDGet	%AddToSaveSet	%CheckUnique	%ClassIsLatestVersion
%ClassName	%ConstructClone	%Delete	%DeleteExtent
%DeleteId	%DispatchClassMethod	%DispatchGetModified	%DispatchGetProperty
%DispatchMethod	%DispatchSetModified	%DispatchSetMultidimProperty	%DispatchSetProperty
%Exists	%ExistsId	%Extends	%GetParameter
%GetSwizzleObject	%Id	%IsA	%IsModified
%KillExtent	%LocationSet	%LockStream	%New
%NormalizeObject	%ObjectModified	%Oid	%Open
%OpenId	%OriginalNamespace	%PackageName	%ReleaseLock
%Reload	%RemoveFromSaveSet	%RollBack	%Save
%SerializeObject	%SetModified	%UnlockStream	%ValidateObject
Clear	CopyFrom	CopyFromAndSave	FindAt
Flush	InputFromDevice	IsCharacter	IsNull
LastModifiedGet	MoveTo	MoveToEnd	OutputToDevice
OutputToDeviceAt	Read	ReadLine	ReadLineIntoStream
ReadSQL	Rewind	SerializeToSyncSet	SizeGet
StreamOIDIsNull	SyncStreamIn	Write	WriteLine

Subclasses
%Library.AbstractStream	%Library.BinaryStream	%Library.CharacterStream	%Library.Stream
%Stream.FileBinary	%Stream.TmpCharacter

• parameter DEFAULTCONCURRENCY = "$zu(115,10)";

• 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 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 Id as %String;

Id is the unique identifier for a stream within the %Location.

• 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 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.

• 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(oid 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.

• classmethod %KillExtent() as %Status

• 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.

• 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) as %Integer

Find the first occurance of target in the stream starting the search at position. It returns the position at this match starting at the begining of the stream. If it can 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.

• method Flush() as %Status

Flush any output in the stream not already saved.

• 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).

• method 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

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.

• 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 = 32000, 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 ("").

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

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.

• 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.