Working with Streams

Some commonly used methods include the following:

• Read() — Read a specified number of characters starting at the current position in the stream.

• Write() — Append data to the stream, starting at the current position. Overwrites existing data if the position is not set to the end of the stream.

• Rewind() — Move to the beginning of the stream.

• MoveTo() — Move to a given position in the stream.

• MoveToEnd() — Move to the end of the stream.

• CopyFrom() — Copy the contents of a source stream into this stream.

• NewFileName() — Specify a filename for a %Stream.FileCharacterOpens in a new tab or %Stream.FileBinaryOpens in a new tab property.

Commonly used properties include the following:

• AtEnd — Set to true when a Read encounters the end of the data source.

• Id — The unique identifier for an instance of a stream within the extent specified by %Location.

• Size — The current size of the stream (in bytes or characters, depending on the type of stream).

For detailed information on individual stream methods and properties, see the InterSystems Class Reference entries for the classes listed at the beginning of this topic.

When you use a stream class as an object property, the stream is instantiated implicitly when you instantiate the containing object.

When you use a stream class as a standalone object, use the %New() method to instantiate the stream.

At the core of the stream interface are the methods Read(), Write(), and Rewind() and the properties AtEnd and Size.

The following example reads data from the Person.Memo stream and writes it to the console, 100 characters at a time. The value of len is passed by reference, and is reset to 100 before each Read. The Read method attempts to read the number of characters specified by len, and then sets it to the actual number of characters read:

  Do person.Memo.Rewind()
  While (person.Memo.AtEnd = 0) {
    Set len = 100
    Write person.Memo.Read(.len)
  }

Similarly, you can write data into the stream:

  Do person.Memo.Write("This is some text. ")
  Do person.Memo.Write("This is some more text.")

All streams contain a CopyFrom() method which allows one stream to fill itself from another stream. This can be used, for example, to copy data from a file into a stream property. In this case, one uses the %Library.FileOpens in a new tab class, which is a wrapper around operating system commands and allows you to open a file as a stream. In this case, the code is:

  // open a text file using a %Library.File stream
  Set file = ##class(%File).%New("\data\textfile.txt")
  Do file.Open("RU") // same flags as the OPEN command

  // Open a Person object containing a Memo stream
  // and copy the file into Memo
  Set person = ##class(Person).%New()
  Do person.Memo.CopyFrom(file)

  Do person.%Save() // save the person object
  Set person = ""   // close the person object
  Set file = ""     // close the file

You can also copy data into a stream with the Set command:

  Set person2.Memo = person1.Memo

where the Memo property of the Person class holds an OREF for a stream and this command copies the contents of person1.Memo into person2.Memo.

Apart from the temporary stream classes (whose data cannot be saved), streams have both a temporary and a permanent storage location. All inserts go into the temporary storage area, which is only made permanent when you save the stream. If you start inserting into a stream, then decide that you want to abandon the insert, the data stored in the permanent location is not altered.

If you create a stream, start inserting, then do some reading, you can call MoveToEnd() and then continue appending to the temporary stream data. When you save the stream, the data is moved to the permanent storage location.

For example:

    Set test = ##class(Test).%OpenId(5)
    Do test.text.MoveToEnd()
    Do test.text.Write("append text")
    Do test.%Save()

Here, the stream is saved to permanent storage when the test object is saved.

The stream interface includes the FindAt() method, which you can use to find the location of a given literal value. This method has the following arguments:

method FindAt(position As %Integer, target, ByRef tmpstr, caseinsensitive As %Boolean = 0) as %Integer

Where:

• position is the position at which to start searching.

• target is the literal value to search for.

• tmpstr, which is passed by reference, returns information that can be used in the next call to FindAt(). Use this when you want to search the same stream repeatedly, starting from the last position where the target was found. In this scenario, specify position as –1 and pass tmpstr by reference in every call. Then each successive call to FindAt() will start where the last call left off.

• caseinsensitive specifies whether to perform a case-insensitive search. By default, the method does not consider case.

The method returns the position at this match starting at the beginning of the stream. If it does not find a match, it returns -1.

When you use a stream class as an object property, the stream data is saved when you save the containing object.

When you use a stream class as a standalone object, use the %Save() method to save the stream data. (Note that for the temporary stream classes — %Stream.TmpCharacterOpens in a new tab and %Stream.TmpBinaryOpens in a new tab — this method returns immediately and does not save any data.)

Stream properties are manipulated via a transient object that is created by the object that owns the stream property. Streams act as literal values (think of them as large strings). Two object instances cannot refer to the same stream.

In the following class definition, the Person class has a Memo property that is a stream property:

Class testPkg.Person Extends %Persistent
{
Property Name As %String;

Property Memo As %Stream.GlobalCharacter;
}

The following ObjectScript fragment creates a new person object, implicitly instantiating the Memo stream. Then it writes some text to the stream.

    // create object and stream
    Set p = ##class(testPkg.Person).%New()
    Set p.Name = "Mo"
    Do p.Memo.Write("This is part one of a long memo. ")
    Do p.Memo.Write("This is part two of a long memo. ")
    Do p.Memo.Write("This is part three of a long memo. ")
    Do p.Memo.Write("This is part four of a long memo. ")
    Do p.%Save()
    Set id = p.%Id() // remember ID for later
    Set p = ""

The following code fragment opens the person object and then writes the contents of the stream. Note that when you open an object, the current position of any stream properties is set to the beginning of the stream. This code uses the Rewind() method for illustrative purposes.

    // read object and stream
    Set p = ##class(testPkg.Person).%OpenId(id)
    Do p.Memo.Rewind() // not required first time

    // write contents of stream to console, 100 characters at a time
    While (p.Memo.AtEnd = 0) {
        Set len = 100
        Write p.Memo.Read(.len)
    }
    Set p = ""

You can use embedded SQL to read a stream as follows:

1. Use embedded SQL to select the OID (Object ID) of the stream:

     &sql(SELECT Memo INTO :memo FROM Person WHERE Person.ID = 12345)
   
   

   

   This fetches the OID of the stream and places it into the memo host variable.

2. Then open the stream and process it as usual.

To write a stream via embedded SQL, you have several options. For the value to insert, you can use an object reference (OREF) of a stream, the string version of such an OREF, or a string literal.

The following examples show all these techniques. For these examples, assume that you have a table named Test.ClassWStream which has a column named Prop1, which expects a stream value.

The following example uses an object reference:

///use an OREF
ClassMethod Insert1()
{
    set oref=##class(%Stream.GlobalCharacter).%New()
    do oref.Write("Technique 1")

    //do the insert; this time use an actual OREF
    &sql(INSERT INTO Test.ClassWStreams (Prop1) VALUES (:oref))
}

The next example uses a string version of an object reference:

///use a string version of an OREF
ClassMethod Insert2()
{
    set oref=##class(%Stream.GlobalCharacter).%New()
    do oref.Write("Technique 2")

    //next line converts OREF to a string OREF
    set string=oref_""

    //do the insert
    &sql(INSERT INTO Test.ClassWStreams (Prop1) VALUES (:string))
}

The last example inserts a string literal into the stream Prop1:

///insert a string literal into the stream column
ClassMethod Insert3()
{
    set literal="Technique 3"

    //do the insert; use a string
    &sql(INSERT INTO Test.ClassWStreams (Prop1) VALUES (:literal))
}