Stream Interface Classes

InterSystems IRIS allocates a fixed amount of space to hold the results of string operations. If a string expression exceeds the amount of space allocated, a <MAXSTRING> error results; see string length limit.

If you need to pass a value whose length exceeds this limit, or you need a property whose value might exceed this limit, you use a stream. A stream is an object that can contain a single value whose size is larger than the string size limit. (Internally InterSystems IRIS creates and uses a temporary global to avoid the memory limitation.)

You can use stream fields with InterSystems SQL, with some restrictions. For details and a more complete introduction, see Defining and Using Classes; also see the InterSystems Class Reference for these classes.

Note:

You cannot use ObjectScript stream fields with Python.

Stream Classes

The main InterSystems IRIS stream classes use a common stream interface defined by the %Stream.ObjectOpens in a new tab class. You typically use streams as properties of other objects, and you save those objects. Stream data may be stored in either an external file or an InterSystems IRIS global, depending on the class you choose:

The %Stream.FileCharacterOpens in a new tab and %Stream.FileBinaryOpens in a new tab classes are used for streams written to external files.
(Binary streams contain the same kind of data as type %BinaryOpens in a new tab, and can hold large binary objects such as pictures. Character streams contain the same kind of data as type %StringOpens in a new tab, and are intended for storing large amounts of text.)
The %Stream.GlobalCharacterOpens in a new tab and %Stream.GlobalBinaryOpens in a new tab classes are used for streams stored in globals.

To work with a stream object, you use its methods. For example, you use the Write() method of these classes to add data to a stream, and you use Read() to read data from it. The stream interface includes other methods such as Rewind() and MoveTo().

Example

For example, the following code creates a global character stream and writes some data into it:

 Set mystream=##class(%Stream.GlobalCharacter).%New()
 Do mystream.Write("here is some text to store in the stream ")
 Do mystream.Write("here is some more text")
 Write "this stream has this many characters: ",mystream.Size,!
 Write "this stream has the following contents: ",!
 Write mystream.Read()

Collection Classes

OREFs