Rapid-Q Documentation by William Yu (c)1999 | Chapter 7

# 7. Introduction to streams

  Rapid-Q supports file streams instead of the standard OPEN command used in BASIC. It has the same functionality, but is called differently. What's great about streams is that it's unlimited in size, and you can copy to and from different streams (ie. File to Memory).
  7.1 File streams
  File streams are used to create, read and write to files. All streams are opened as binary, with no locking capabilities (ie. all files you open are shared). Please familiarize yourself with these file modes:

           fmCreate    - Create file (read/write), truncate if file exists
           fmOpenRead  - Open file for reading only
           fmOpenWrite - Open file for writing only
           fmOpenReadWrite - Open file for reading & writing

  To open a file you need to pass the filename, and provide one of the above file modes.

           DIM File AS QFileStream

           File.Open("Test.txt", fmOpenRead)

  This will open Test.txt for reading only. To read data, you use the methods ReadNum and ReadStr. See RAPIDQ.INC for valid numbers.

           PRINT File.ReadNum(Num_SINGLE)   '-- Read 4 bytes as a SINGLE number
           PRINT File.ReadStr(1024)         '-- Read 1024 bytes

  Another approach is to store the value into a variable, you can use the generic Read and Write routines.

           File.Read(A&)          '-- Read a long value and store in A&
           File.Write(B#)         '-- Write a double value B#

           '-- or similarily, with more work:
           A& = File.ReadNum(Num_LONG)
           File.WriteNum(B#, Num_DOUBLE)

  After you're done with the file, make sure you close the handle. You can then reuse your file stream and open up another file. To test if you've reached the end of the file, you can either compare File.Position with File.Size or see if File.EOF is true (-1). So long as File.Position is less than File.Size, you haven't reached the end of the file. There are actually 2 ways to test if a file exists:

           IF FileExists("Test.txt") <> FALSE THEN
             File.Open("Test.txt", fmOpenRead)
           END IF

  However, it's better just to cut this down to:

           IF File.Open("Test.txt", fmOpenRead) = FALSE THEN
              ShowMessage("Could not open file")
           END IF

  File.Open will return a non-zero number if the file was successfully opened, 0 otherwise.
  7.2 Memory streams
  A memory stream is created whenever you DIM it. It's similar to file streams, all the methods are the same, such as ReadNum, WriteNum, etc... The only difference is that memory streams are stored in memory, which can grow/shrink with no upper bounds. It's even possible to store arrays of numbers in memory stream (see ARRAYS.BAS example). Memory streams serve many purposes, let your imagination take over. One useful purpose might be to store temporary data, such as copying a file to a memory stream and manipulating the data that way. So how can I copy from one stream to another? Quite easily, you can copy between different streams (ie. File to Memory) or of the same kind (ie. Memory to Memory).

          DIM File AS QFileStream
          File.Open("test.txt", fmOpenRead)

          DIM Memory AS QMemoryStream
          Memory.CopyFrom(File, File.Size)  '-- Copy everything

  As you can see, we've just copied the entire contents of our file "test.txt" to our memory stream. Now you can manipulate your memory stream without affecting the file.
  7.3 Saving/Loading UDTs and Arrays
  Saving and loading UDTs is as simple as passing the UDT to QFileStream or QMemoryStream.

          TYPE TTest
              S AS STRING*8
              N AS INTEGER
          END TYPE

          DIM Test AS TTest
          DIM File AS QFileStream

          File.Open("test.txt", fmCreate)
          File.WriteUDT(Test)
          File.Close

  In the above example, 12 bytes was saved to the file test.txt. 8 bytes for the fixed string S, and 4 bytes for N. To retrieve the UDT, use the method ReadUDT.

          File.Open("test.txt", fmOpenRead)
          File.ReadUDT(Test)

  Saving/Loading arrays is equally easy.

          DIM A(1 TO 100) AS LONG
          DIM File AS QFileStream

          File.Open("test.txt", fmCreate)
          File.SaveArray(A(1), 100)
          File.Close

  The first parameter of SaveArray is the starting array element to save, this could be any value from 1 to 100 in the above example. The next parameter specifies how many elements of the array to save. In this case we choose to save all 1..100 elements. Similarly, we can use LoadArray to retrieve our data:

          File.Open("test.txt", fmOpenRead)
          File.LoadArray(A(1), 100)

  Streams are very popular in most high level languages for file/memory manipulation, but does take some time to get used to, especially if you're a die-hard BASIC user.

  Prev Chapter | Contents | Next Chapter