Working with Stream Objects in InterSystems IRIS

Introduction

In modern applications, especially those involving large data, documents, logs, or multimedia, handling large or unstructured content efficiently becomes essential. InterSystems IRIS offers a robust and scalable way to manage such data using stream objects.

Stream objects allow developers to work with large text or binary data without being constrained by string size limits or memory inefficiencies. In this article, we’ll explore how to create, read, write, store, and manipulate stream objects within IRIS using ObjectScript.

What Are Stream Objects in IRIS?

InterSystems IRIS provides built-in stream classes under the %Stream package to represent sequences of characters or bytes that can be read or written incrementally. These streams are particularly useful when working with:

• Text documents (logs, reports, etc.)
• Binary files (images, PDFs)
• Large API payloads (file uploads/downloads)
• Persistent class properties exceeding string limits (~3.6MB)

Types of Streams

Creating and Writing to a Stream

Here’s how to create and write to a global character stream:

Set stream = ##class(%Stream.GlobalCharacter).%New() Do stream.Write("This is line one.") Do stream.WriteLine("This is line two.") The .Write() method appends text to the stream, while .WriteLine() adds a newline at the end.

Reading from a Stream

After writing to a stream, you can read from it using .Read() or .ReadLine():

Do stream.Rewind() Set line1 = stream.ReadLine() Set line2 = stream.ReadLine() Write line1, !, line2

Always call .Rewind() before reading if you’ve already written to the stream — this resets the internal pointer to the beginning.

Saving a Stream to a File

Stream objects can be saved to files directly:

Set sc = stream.OutputToFile("/tmp/output.txt") If $$$ISERR(sc) { Write "Error saving file" } Similarly, you can read from a file into a stream:

Set fileStream = ##class(%Stream.FileCharacter).%New() Set fileStream.Filename = "/tmp/input.txt" Set sc = fileStream.CopyTo(stream) ; Copy contents into another stream

Storing Stream Objects in Persistent Classes

Streams integrate easily with persistent objects. You can define a stream as a property in your data model:

Class MyApp.Report Extends (%Persistent) { Property Title As %String; Property Content As %Stream.GlobalCharacter; } You can now save large content as part of your data model:

Set report = ##class(MyApp.Report).%New() Set report.Title = "October Report" Set report.Content = ##class(%Stream.GlobalCharacter).%New() Do report.Content.Write("Full report content goes here...") Do report.%Save()

Binary Streams

For non-text data (e.g., images or attachments), use %Stream.GlobalBinary:

Set binStream = ##class(%Stream.GlobalBinary).%New() Do binStream.Write($Char(255, 216, 255)) ; Sample binary data (JPEG header) Do binStream.OutputToFile("/tmp/sample.jpg")

Common Use Cases for Stream Objects

• REST API File Uploads/Downloads
  Handle large multipart file uploads using stream input/output in custom REST services.
• PDF or Log Storage
  Store application logs or reports in a database without hitting string size limits.
• Data Archiving
  Save binary backups or exports as BLOBs in the database.
• Dynamic File Generation
  Generate files in-memory using streams before sending them over HTTP or saving them to disk.

Tips & Best Practices

• Always rewind before reading a stream you’ve just written.
• Use stream copying for efficient memory handling: source.CopyTo(destination).
• For binary data, never use character streams — it may corrupt content.
• Monitor .Size to track stream length.
• Use %JSONExportToStream() for serializing objects directly into streams (e.g., for REST responses).

Example: Export Object as JSON Stream

Set obj = ##class(MyApp.Report).%OpenId(1) Set jsonStream = ##class(%Stream.GlobalCharacter).%New() Do obj.%JSONExportToStream(.jsonStream) Do jsonStream.OutputToFile("/tmp/export.json")

Conclusion

Stream objects are an essential tool in every InterSystems IRIS developer’s toolbox. They provide a flexible, scalable, and efficient way to handle large or unstructured data within applications — whether you’re storing logs, manipulating files, or transmitting large payloads.

By understanding how to create, manipulate, and persist streams, you unlock a new level of data handling power within your IRIS environment.