Inheritance diagram for Object:

[legend]

Collaboration diagram for Object:

[legend]

Public Member Functions
_.Library.Status	AcquireLock (locktype)
	Acquires a lock for the current instance. More...

_.Library.Status	OnAfterSave (_.Library.Boolean insert)
	This callback method is invoked by the <METHOD>Save</METHOD> method to. More...

_.Library.Status	OnBeforeSave (_.Library.Boolean insert)
	This callback method is invoked by the <METHOD>Save</METHOD> method to. More...

_.Library.Status	OnClose ()
	This callback method is invoked by the <METHOD>Close</METHOD> method to. More...

_.Library.Status	OnOpen ()
	This callback method is invoked by the <METHOD>Open</METHOD> method to. More...

_.Library.Status	OnReload ()
	This callback method is invoked by the <METHOD>Reload</METHOD> method to. More...

_.Library.Status	OnRollBack ()
	This callback method is invoked by the <METHOD>Save</METHOD> method to. More...

_.Library.Status	Clear ()
	Clear the contents of this Stream from permanent storage. More...

_.Library.Status	CopyFrom (_.Stream.Object source)
	Copies the contents of source into this Stream. More...

_.Library.Status	CopyFromAndSave (_.Stream.Object source)
	Copy the stream from source into the current stream ignoring anything already in the current stream. More...

_.Library.Integer	FindAt (_.Library.Integer position, _.Library.RawString target, _.Library.RawString tmpstr, _.Library.Boolean caseinsensitive)
	Find the first occurrence of target in the stream, starting the search at position. More...

_.Library.Status	Flush ()
	Flush any output in the stream not already saved.

_.Library.String	GetStreamId ()
	Returns an full id value (including class name) with which the Stream implementation has stored. More...

_.Library.Status	InputFromDevice (_.Library.Integer len, _.Library.Integer timeout)
	Input len characters from the current device into the stream. More...

_.Library.Boolean	IsNull ()
	Returns true if this is a "NULL" stream; that is, a stream which has never. More...

_.Library.Boolean	MoveTo (_.Library.Integer position)
	Move to this position in the stream. More...

_.Library.Status	MoveToEnd ()
	Move to the end of the stream so the next <METHDO>Write</METHOD> will be appended to the end. More...

_.Library.Status	OutputToDevice (_.Library.Integer len)
	Write out len characters of the stream to the current device starting from the current position. More...

_.Library.Status	OutputToDeviceAt (_.Library.Integer position, _.Library.Integer length)
	Output the stream to the current device starting at position of length. More...

_.Library.RawString	Read (_.Library.Integer len, _.Library.Status sc)
	Reads up to len characters from the current position. More...

_.Library.RawString	ReadLine (_.Library.Integer len, _.Library.Status sc, _.Library.Boolean eol)
	Read a line from the stream. More...

_.Library.String	ReadSQL (_.Library.Integer start, _.Library.Integer end)
	SQL specific method for reading stream data.

_.Library.Status	Rewind ()
	Go back to the start of the stream.

_.Library.Status	SerializeToSyncSet (_.SYNC.SyncSet ss, _.Library.Integer iPtr, _.Library.String property)
	SerializeToSyncSet copies the stream value from the current object to the sync set global. More...

_.Library.Status	SyncStreamIn (_.SYNC.SyncSet ss, _.Library.Integer iPtr, _.Library.String property)
	SyncStreamIn copies the stream value from the sync set global into the current object.

_.Library.Status	Write (_.Library.RawString data)
	Appends the string data to the stream and advances the. More...

_.Library.Status	WriteLine (_.Library.RawString data)
	Appends the string data along with a line terminator to the stream and advances the. More...

Public Member Functions inherited from RegisteredObject
_.Library.Status	OnAddToSaveSet (_.Library.Integer depth, _.Library.Integer insert, _.Library.Integer callcount)
	This callback method is invoked when the current object is added to the SaveSet,. More...

_.Library.Status	OnConstructClone (_.Library.RegisteredObject object, _.Library.Boolean deep, _.Library.String cloned)
	This callback method is invoked by the <METHOD>ConstructClone</METHOD> method to. More...

_.Library.Status	OnNew ()
	This callback method is invoked by the <METHOD>New</METHOD> method to. More...

_.Library.Status	OnValidateObject ()
	This callback method is invoked by the <METHOD>ValidateObject</METHOD> method to. More...

Static Public Member Functions
_.Library.String	GetLockReference (_.Library.String pLocation, _.Library.String pId)
	Returns the global reference used to lock the current stream object. More...

_.Library.Status	OnDelete (_.Library.ObjectIdentity oid)
	This callback method is invoked by the <METHOD>Delete</METHOD> method to. More...

_.Library.String	IsCharacter ()
	Return true if this is a character stream and false if it is a binary stream.

_.Library.Boolean	StreamOIDIsNull (_.Library.ObjectIdentity soid)
	Return true if this stream oid is a null stream and false if the stream is not null.

Public Attributes
	AtEnd
	The AtEnd property is set to true (1) when, during a read,. More...

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

	LastModified
	LastModified is a read-only property containing the <class>TimeStamp</class> of More...

	Size
	Size is a read-only property containing the current size of the stream (in bytes More...

Static Public Attributes
	DEFAULTCONCURRENCY = None

Static Public Attributes inherited from RegisteredObject
	CAPTION = None
	Optional name used by the Form Wizard for a class when generating forms. More...

	JAVATYPE = None
	The Java type to be used when exported.

	PROPERTYVALIDATION = None
	This parameter controls the default validation behavior for the object. More...

Private Member Functions
_.Library.Status	GetSwizzleObject (_.Library.Integer force, _.Library.ObjectIdentity oid)
	<METHOD>GetSwizzleObject</METHOD> is used to obtain a state of the object that can More...

_.Library.String	Id ()
	Returns the persistent object Id, if there is one, of this object. More...

_.Library.Boolean	IsNull ()
	Returns true if this is a "NULL" stream; that is, a stream which has never. More...

	LockStream ()
	LockStream() More...

_.Library.ObjectIdentity	Oid ()
	Returns the OID of this object.

_.Library.Status	ReleaseLock (locktype)
	Releases a lock for the current instance. More...

_.Library.Status	Reload ()
	Reload is an instance method that re-reads an object from disk into the More...

_.Library.Status	RollBack ()
	This method is called by <METHOD>Save</METHOD> when a transaction is rolled back. More...

_.Library.Status	Save (_.Library.Integer related)
	Stores an in-memory version of an object to disk. More...

	UnlockStream (_.Library.Boolean immediate)
	UnlockStream() More...

Static Private Member Functions
_.Library.Status	Delete (_.Library.ObjectIdentity oid, _.Library.Integer concurrency)
	Deletes the stored version of the object with OID oid from the database. More...

_.Library.Status	DeleteExtent (_.Library.Integer concurrency, deletecount, instancecount)
	Delete all instances of this class from its extent. More...

_.Library.Status	DeleteId (_.Library.String id, _.Library.Integer concurrency)
	Deletes the stored version of the object with ID id from the database. More...

_.Library.Boolean	Exists (_.Library.ObjectIdentity soid)
	Checks to see if the object identified by the OID oid exists in the extent. More...

_.Library.Boolean	ExistsId (_.Library.String id)
	Checks to see if the object identified by the ID id exists in the extent. More...

_.Library.Integer	LOBPrefetch (_.Library.ObjectIdentity soid, _.Library.Integer prefetchsize, _.Library.String data)
	Given a soid if the length is <= prefetchsize then return the data. More...

_.Library.Boolean	ObjectIsNull (_.Library.ObjectIdentity soid)
	Return true if this stream oid is a null stream and false if the stream is not null.

_.Library.Integer	ObjectSize (_.Library.ObjectIdentity soid)
	Returns the size of the stream pointed to by soid in the most efficient way possible.

_.Library.ObjectHandle	Open (_.Library.ObjectIdentity soid, _.Library.Integer concurrency, _.Library.Status sc)
	Loads an object from the database into memory and returns an OREF referring to the object. More...

_.Library.ObjectHandle	OpenId (_.Library.String id, _.Library.Integer concurrency, _.Library.Status sc)
	Loads an object from the database into memory and returns an OREF referring to the object. More...

Detailed Description

For information on this class, see Working with Streams.

The <CLASS>Stream.Object</CLASS> 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.

Member Function Documentation

◆ AcquireLock()

_.Library.Status AcquireLock ( locktype )

Acquires a lock for the current instance.

<p>The <var>locktype</var> argument specifies the type of lock to acquire.
It can take the following values:
<table cols=2>
<tr>
<td width="33%" valign="top">"e": <i>Exclusive</i></td>
<td valign="top">
An exclusive lock will prevent any other process from acquiring any type of lock
on this object.
</td>
</tr>

<tr>
<td width="33%" valign="top">"s": <i>Shared</i></td>
<td valign="top">
A shared lock will allow other processes to acquire shared locks but will
prevent other processes from acquiring an exclusive lock.
</table>
</td>
</tr>

Fails if the locktype parameter is not one of the values described above.

<p>Returns a <CLASS>%Status</CLASS> value indicating success or failure.

◆ Delete()

_.Library.Status Delete	(	_.Library.ObjectIdentity	oid,
		_.Library.Integer	concurrency
	)

staticprivate

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 Object Concurrency Options for more details on the optional concurrency argument.

Returns a <CLASS>Status</CLASS> value indicating success or failure.

Internally, <METHOD>Delete</METHOD> initiates a transaction and then invokes the storage interface method <METHOD>DeleteData</METHOD>. If <METHOD>DeleteData</METHOD> succeeds, the transaction is committed, otherwise it is rolled back.

◆ DeleteExtent()

_.Library.Status DeleteExtent	(	_.Library.Integer	concurrency,
			deletecount,
			instancecount
	)

staticprivate

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, <METHOD>DeleteExtent</METHOD> iterates over the set of instances in the collection and invokes the <METHOD>Delete</METHOD> method.

Refer to Object Concurrency Options for more details on the optional concurrency argument.

Returns a <CLASS>Status</CLASS> value indicating success or failure.

◆ DeleteId()

_.Library.Status DeleteId	(	_.Library.String	id,
		_.Library.Integer	concurrency
	)

staticprivate

Deletes the stored version of the object with ID id from the database.

<p><METHOD>%DeleteId</METHOD> is identical in operation to the <METHOD>%Delete</METHOD> method except 
that it uses and Id value instead of an OID value to find an object.

Refer to <a href="/csp/docbook/DocBook.UI.Page.cls?KEY=GOBJ_concurrency" target="_blank">Object Concurrency Options</a> for more details 
on the optional <var>concurrency</var> argument.

◆ Exists()

_.Library.Boolean Exists ( _.Library.ObjectIdentity soid )

staticprivate

Checks to see if the object identified by the OID oid exists in the extent.

<p>Returns <CLASS>%Boolean</CLASS> TRUE is it exists, FALSE if it does not.

Reimplemented in TmpCharacter, and FileBinary.

◆ ExistsId()

_.Library.Boolean ExistsId ( _.Library.String id )

staticprivate

Checks to see if the object identified by the ID id exists in the extent.

<p>Returns <CLASS>%Boolean</CLASS> TRUE is it exists, FALSE if it does not.

◆ GetLockReference()

_.Library.String GetLockReference	(	_.Library.String	pLocation,
		_.Library.String	pId
	)

static

Returns the global reference used to lock the current stream object.

Throws Exception.AbstractException

Reimplemented in TmpCharacter, and DynamicCharacter.

◆ GetSwizzleObject()

_.Library.Status GetSwizzleObject	(	_.Library.Integer	force,
		_.Library.ObjectIdentity	oid
	)

private

<METHOD>GetSwizzleObject</METHOD> 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 <CLASS>Status</CLASS> value indicating success or failure.

◆ Id()

_.Library.String Id ( )

private

Returns the persistent object Id, if there is one, of this object.

Returns a null string if there is no object Id.

Reimplemented in AbstractStream.

◆ IsNull() [1/2]

_.Library.Boolean IsNull ( )

private

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 InterSystems IRIS ODBC server.

Reimplemented in TmpCharacter, TmpCharacter, NullCharacter, NullBinary, FileBinary, DynamicCharacter, DynamicCharacter, AbstractStream, and AbstractStream.

◆ LOBPrefetch()

_.Library.Integer LOBPrefetch	(	_.Library.ObjectIdentity	soid,
		_.Library.Integer	prefetchsize,
		_.Library.String	data
	)

staticprivate

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()

LockStream ( )

private

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.

Reimplemented in GlobalStreamAdaptor.

◆ OnAfterSave()

_.Library.Status OnAfterSave ( _.Library.Boolean insert )

This callback method is invoked by the <METHOD>Save</METHOD> 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 <METHOD>Save</METHOD> will fail.

◆ OnBeforeSave()

_.Library.Status OnBeforeSave ( _.Library.Boolean insert )

This callback method is invoked by the <METHOD>Save</METHOD> 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 <METHOD>Save</METHOD> will fail.

◆ OnClose()

_.Library.Status OnClose ( )

This callback method is invoked by the <METHOD>Close</METHOD> method to.

provide notification that the current object is being closed.

The return value of this method is ignored.

Reimplemented from RegisteredObject.

Reimplemented in TmpCharacter, FileBinary, DynamicCharacter, Routine, GlobalStreamAdaptor, FileStreamAdaptor, File, and AbstractStream.

◆ OnDelete()

_.Library.Status OnDelete ( _.Library.ObjectIdentity oid )

static

This callback method is invoked by the <METHOD>Delete</METHOD> method to.

provide notification that the object specified by oid is being deleted.

If this method returns an error then the object will not be deleted.

◆ OnOpen()

_.Library.Status OnOpen ( )

This callback method is invoked by the <METHOD>Open</METHOD> method to.

provide notification that the object specified by oid is being opened.

If this method returns an error then the object will not be opened.

◆ OnReload()

_.Library.Status OnReload ( )

This callback method is invoked by the <METHOD>Reload</METHOD> method to.

provide notification that the object specified by oid was reloaded. <method>Reload</method> 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.

◆ OnRollBack()

_.Library.Status OnRollBack ( )

This callback method is invoked by the <METHOD>Save</METHOD> method to.

provide notification that a save transaction is being rolled back.

If this method returns an error then the rollback operation will be aborted.

Reimplemented in TmpCharacter, DynamicCharacter, and GlobalStreamAdaptor.

◆ Open()

_.Library.ObjectHandle Open	(	_.Library.ObjectIdentity	soid,
		_.Library.Integer	concurrency,
		_.Library.Status	sc
	)

staticprivate

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 <METHOD>Open</METHOD> does the following: it assumes the class name is the same as the object class on which <METHOD>Open</METHOD> was called.

If a version of the specified object is already in memory, then <METHOD>Open</METHOD> increments the object's reference count and returns the OREF value referring to this version. <METHOD>Open</METHOD> 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.

<METHOD>Open</METHOD> 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()

_.Library.ObjectHandle OpenId	(	_.Library.String	id,
		_.Library.Integer	concurrency,
		_.Library.Status	sc
	)

staticprivate

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.

<METHOD>OpenId</METHOD> is identical in operation to the <METHOD>Open</METHOD> 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.

<METHOD>OpenId</METHOD> 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.

◆ ReleaseLock()

_.Library.Status ReleaseLock ( locktype )

private

Releases a lock for the current instance.

<p>The <var>locktype</var> argument specifies the type of lock to release.
It can take the following values:
<table cols=2>
<tr>
<td width="33%" valign="top">"e": <i>Exclusive</i></td>
<td valign="top">
An exclusive lock will prevent any other process from acquiring any type of lock
on this object.
</td>
</tr>

<tr>
<td width="33%" valign="top">"s": <i>Shared</i></td>
<td valign="top">
A shared lock will allow other processes to acquire shared locks but will
prevent other processes from acquiring an exclusive lock.
</table>
</td>
</tr>

Fails if the locktype parameter is not one of the values described above.

<p>Returns a <CLASS>%Status</CLASS> value indicating success or failure.

◆ Reload()

_.Library.Status Reload ( )

private

Reload is an instance method that re-reads an object from disk into the

current instance. Calling Reload is similar to calling <METHOD>Close</METHOD> and then <METHOD>Open</METHOD>, but it uses the same OREF.

After Reload is called, there are no swizzled references for the object, and <METHOD>IsModified</METHOD> 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 <METHOD>Id</METHOD> of the current object. Finally, the modified bit for each property is cleared.

◆ RollBack()

_.Library.Status RollBack ( )

private

This method is called by <METHOD>Save</METHOD> when a transaction is rolled back.

It will invoke a user-supplied <METHOD>OnRollBack</METHOD> method if it exists.

Returns a <CLASS>Status</CLASS> value indicating success or failure.

◆ Save()

_.Library.Status Save ( _.Library.Integer related )

private

Stores an in-memory version of an object to disk.

If the object was stored

previously (and thus, already has an OID), <METHOD>Save</METHOD> updates the on-disk version. Otherwise, <METHOD>Save</METHOD> saves the object and generates a new OID for it.

The related argument specifies how <METHOD>Save</METHOD> 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 (<METHOD>IsModified</METHOD> returns true) will actually be saved to the database, including the object upon which <METHOD>Save</METHOD> was initially called.

<METHOD>Save</METHOD> automatically detects and handles circular references between objects. For example, <METHOD>Save</METHOD> 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 <METHOD>Save</METHOD> will fail.

By default <METHOD>Save</METHOD> automatically manages transactions. You can enable and disable automatic transaction support using the $$SetTransactionMode^apiOBJ() routine.

When <METHOD>Save</METHOD> 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, <METHOD>Save</METHOD> will issue a TCOMMIT command to commit the transaction and write the data to the database. If <METHOD>Save</METHOD> 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 <CLASS>Storage.Persistent</CLASS> 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 <METHOD>RollBack</METHOD> method on each object involved with the transaction. The order in which the <METHOD>RollBack</METHOD> methods are called is undefined. <METHOD>RollBack</METHOD> will call a user-written <METHOD>OnRollback</METHOD> method if it is present.

Returns a <CLASS>Status</CLASS> value indicating success or failure.

◆ UnlockStream()

UnlockStream ( _.Library.Boolean immediate )

private

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.

◆ Clear()

_.Library.Status Clear ( )

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 <CLASS>Status</CLASS> value indicating success or failure.

Reimplemented in AbstractDocument, ChunkedWriter, Routine, File, and LibraryStream.

◆ CopyFrom()

_.Library.Status CopyFrom ( _.Stream.Object source )

Copies the contents of source into this Stream.

Does not call <METHOD>Rewind</METHOD> on this Stream before copying.

For example, you can copy oldstream into a new stream:

Set newstream=##class(GlobalCharacterStream).New() Do newstream.CopyFrom(oldstream)

Returns a <CLASS>Status</CLASS> value indicating success or failure.

Reimplemented in TmpCharacter, and DynamicCharacter.

◆ CopyFromAndSave()

_.Library.Status CopyFromAndSave ( _.Stream.Object source )

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 <CLASS>GlobalCharacterStream</CLASS> to another <CLASS>GlobalCharacterStream</CLASS> to avoid copying into temporary storage first and then moving this to the permanent storage when <METHOD>SaveStream</METHOD> is called.

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

Reimplemented in GlobalCharacter.

◆ FindAt()

_.Library.Integer FindAt	(	_.Library.Integer	position,
		_.Library.RawString	target,
		_.Library.RawString	tmpstr,
		_.Library.Boolean	caseinsensitive
	)

Find the first occurrence of target in the stream, starting the search at position.

The method returns the

position of this match, counting from the beginning of the stream, and leaves the stream positioned at an indeterminate location. If it does not find the target string, it returns -1.

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.

◆ GetStreamId()

_.Library.String GetStreamId ( )

Returns an full id value (including class name) with which the Stream implementation has stored.

the stream.

Reimplemented in AbstractStream.

◆ InputFromDevice()

_.Library.Status InputFromDevice	(	_.Library.Integer	len,
		_.Library.Integer	timeout
	)

Input len characters from the current device into the stream.

This is equivalent to doing a series of

reads and calling <METHOD>Write</METHOD> 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).

Reimplemented in LibraryStream.

◆ IsNull() [2/2]

_.Library.Boolean IsNull ( )

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 InterSystems IRIS ODBC server.

Reimplemented in TmpCharacter, TmpCharacter, NullCharacter, NullBinary, FileBinary, DynamicCharacter, DynamicCharacter, AbstractStream, and AbstractStream.

◆ MoveTo()

_.Library.Boolean MoveTo ( _.Library.Integer position )

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.

Reimplemented in DynamicCharacter, and LibraryStream.

◆ MoveToEnd()

_.Library.Status MoveToEnd ( )

Move to the end of the stream so the next <METHDO>Write</METHOD> will be appended to the end.

This allows you to read from a stream, then MoveToEnd() and append new data, where just calling <METHOD>Write</METHOD> after a read will clear the stream before writing new data.

Returns a <CLASS>Status</CLASS> value indicating success or failure.

Reimplemented in AbstractDocument, TmpCharacter, NullCharacter, NullBinary, FileBinary, DynamicCharacter, Routine, GlobalStreamAdaptor, FileStreamAdaptor, AbstractStream, and LibraryStream.

◆ OutputToDevice()

_.Library.Status OutputToDevice ( _.Library.Integer len )

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.

Reimplemented in TmpCharacter, FileBinary, DynamicCharacter, DynamicBinary, and LibraryStream.

◆ OutputToDeviceAt()

_.Library.Status OutputToDeviceAt	(	_.Library.Integer	position,
		_.Library.Integer	length
	)

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.

Reimplemented in LibraryStream.

◆ Read()

_.Library.RawString Read	(	_.Library.Integer	len,
		_.Library.Status	sc
	)

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 <method>Read</method> will return a null string (""). If no len is passed in, ie. '<method>Read</method>()' 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 <method>Rewind</method> if you want to read a stream from the beginning again. Calling <method>Read</method> after <method>Write</method> implicitly ends the <method>Write</method> 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.

Reimplemented in AbstractDocument, TmpCharacter, NullCharacter, NullBinary, FileBinary, DynamicCharacter, and LibraryStream.

◆ ReadLine()

_.Library.RawString ReadLine	(	_.Library.Integer	len,
		_.Library.Status	sc,
		_.Library.Boolean	eol
	)

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 <method>Status</method> 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 ! } }

Reimplemented in AbstractDocument, TmpCharacter, NullCharacter, NullBinary, DynamicCharacter, and LibraryStream.

◆ SerializeToSyncSet()

_.Library.Status SerializeToSyncSet	(	_.SYNC.SyncSet	ss,
		_.Library.Integer	iPtr,
		_.Library.String	property
	)

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.

◆ Write()

_.Library.Status Write ( _.Library.RawString data )

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 <CLASS>Status</CLASS> value indicating success or failure.

Reimplemented in TmpCharacter, FileBinary, and LibraryStream.

◆ WriteLine()

_.Library.Status WriteLine ( _.Library.RawString data )

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 <CLASS>Status</CLASS> value indicating success or failure.

Reimplemented in TmpCharacter, FileBinary, and LibraryStream.

Member Data Documentation

◆ DEFAULTCONCURRENCY

DEFAULTCONCURRENCY = None

static

For information on this class, see Working with Streams.

The <CLASS>Stream.Object</CLASS> 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.

◆ AtEnd

AtEnd

The AtEnd property is set to true (1) when, during a read,.

a stream has reached the end of its data source.

◆ Id

Id

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

Reimplemented in AbstractStream.

◆ LastModified

LastModified

LastModified is a read-only property containing the <class>TimeStamp</class> of

the last modification to this stream. If the stream is null then it will report "".

◆ Size

Size

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.

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Static Private Member Functions

Detailed Description

Member Function Documentation

◆ AcquireLock()

◆ Delete()

◆ DeleteExtent()

◆ DeleteId()

◆ Exists()

◆ ExistsId()

◆ GetLockReference()

◆ GetSwizzleObject()

◆ Id()

◆ IsNull() [1/2]

◆ LOBPrefetch()

◆ LockStream()

◆ OnAfterSave()

◆ OnBeforeSave()

◆ OnClose()

◆ OnDelete()

◆ OnOpen()

◆ OnReload()

◆ OnRollBack()

◆ Open()

◆ OpenId()

◆ ReleaseLock()

◆ Reload()

◆ RollBack()

◆ Save()

◆ UnlockStream()

◆ Clear()

◆ CopyFrom()

◆ CopyFromAndSave()

◆ FindAt()

◆ GetStreamId()

◆ InputFromDevice()

◆ IsNull() [2/2]

◆ MoveTo()

◆ MoveToEnd()

◆ OutputToDevice()

◆ OutputToDeviceAt()

◆ Read()

◆ ReadLine()

◆ SerializeToSyncSet()

◆ Write()

◆ WriteLine()

Member Data Documentation

◆ DEFAULTCONCURRENCY

◆ AtEnd

◆ Id

◆ LastModified

◆ Size