Skip to content

Read_Block

See Also: File I/O Commands, Direct_Input, Read, Readln, Set_Channel_Position, Seqeof, Seqeol, Write, Channel command component, Sequential File I/O

Purpose

To read a block of data of a specified size from a sequential file, device, or text field and move it to a variable.

Syntax

Read_Block [Channel {channel-num}] {variable} {length}

Parameters

  • channel channelNum
    Input channel to read data from. If omitted, the channel will be that specified in the most recently executed Direct_Input, Read, Read_Block, or Readln command in which channel was specified or implied.

  • variable
    Variable is required and may be of any simple data type or UChar array. Additional variables may be on the command line, separated by spaces, without limit.

  • length
    Length is required; if omitted, it defaults to zero. Can be -1 if used with a UChar[], indicating that the remaining file should be read.

What It Does

Read_Block reads length characters into variable from the file or device named in the most recently executed Direct_Input command. Read_Block makes no distinctions among characters in the file (delimiters, embedders, spaces, tabs, discards), except the end-of-file character, which it uses to set Predefined Indicator SeqEOF to True.

Read_Block is intended for use with non-delimited files. Files delimited with commas and/or end-of-line characters can be read in with the read and Readln commands. Undelimited files may be text files or any type of data files.

You must set length and the pattern of Read_Block commands according to your prior knowledge of the structure of the data in the input file, since it cannot be inferred from delimiting characters. The maximum length is governed by the maximum number of characters that can be in variable.

Example

Read_Block sMainInfo 70

This reads a block of 70 characters into the variable called sMainInfo.

Working with UChar Arrays

Read_Block can receive the data in a UChar array. This can be used in place of a string variable and has the advantage that you don't have to worry about maximum string size and you don't have to concern yourself with embedded zeros.

If the variable receiving the data is a UChar[], it will resize the array to fit the data and copy the data into the array. You can use SizeOfArray to determine how many bytes were copied.

Read_Block must be passed a length. When the data is loaded into the UChar array, it will be resized to fit the data. If the length passed exceeds the data remaining in the file, the array size will be adjusted to the actual length. When using UChar arrays, you can pass the value -1 to indicate that the remaining file should be read. This is probably how this will be most commonly used.

This can be used with Set_Field_Value and Get_Field_Value, which have also been extended to support UChar arrays.

Procedure ReadFromPDFFile String sInputFile
    UChar[] PDFManual
    // read a sequential file
    Direct_Input Channel 5 ("Binary:" + sInputFile)
    If (SeqEOF) Begin
        Procedure_Return
    End
    // read entire file into UChar array
    Read_Block Channel 5 PDFManual -1
    Close_Input Channel 5
    // write this to my table
    Set_Field_Value Product.PdfManual (RefTable(Product)) to PDFManual
End_Procedure

Notes

  • Reading stops at the detection of a SeqEOF character.

  • If the length of data read is less than {length}, a shorter string will be returned.

  • It is highly recommended to always use the channel feature when doing any sequential I/O, thus making your code more reusable and ready for use with multiple I/O channels if the need arises.

  • The point in a file at which reading is done can also be changed by use of the Set_Channel_Position command.

  • Read_Block ignores all delimiters—commas, quotation marks, carriage returns (CR), line feeds (LF)—except end-of-file markers. It processes all characters the same. Specific characters can be detected and acted upon in files by direct programming.

String sFragment sEOLVal
Move (Character(10)) to sEOLVal
Repeat
    Read_Block sFragment 80
Until (pos(sEOLVal, sFragment) > 0)

  • In this example, a repeat loop causes successive blocks of 80 characters to be read into the string variable sFragment. The if command tests the values of sFragment for the presence of the end-of-line character (ASCII 10). If the end-of-line character is not present, the loop is repeated.

  • The value of length must be in the range from 1 to 4096 for global variables. The requested length is not tested against the length of a global variable. The use of global variables is discouraged for this and other reasons.

  • The input file or device must be opened with the Direct_Input command prior to using Read_Block.