Availability:
     Level T    , 'r'

  Quick Help:
     Read File, r[FileId],[VolumeNum],[CopyNum],[ByteOffset],[Length],[OutputFmt]

  Description:
    This command reads the specified file and sends it to the host over the serial port
    interface using the YMODEM transfer protocol. This protocol is supported by most terminal
    programs, like Windows HyperTerminal. The File Volume, File ID and copy number are
    entered to select the file. In addition the user can select ASCII-HEX or ASCII format for
    the output data.

  Input Parameters:

    0 - File ID Number.
    
        This parameter contains the File ID number to specify the file.
        Please refer to the following list of File IDs to select the value of this parameter.
        File IDs
    
          Type:    Unsigned 16-bit value
    
          Range:   0 to 0xFFFF
    
          Default: None
    
    1 - File Volume Number.
    
        This parameter specifies the File Volume where the file is read from.
        Please refer to the following list of File Volume numbers to select the value of this parameter.
        File Volume numbers
    
          Type:    Unsigned 16-bit value
    
          Range:   0 to 0xFFFF
    
          Default: 3 (System Disc Volume)
    
    2 - Copy Number.
    
        This parameter specifies the copy number of the file to read.
    
          Type:    Unsigned 16-bit value
    
          Range:   0 to 0xFFFF
    
          Default: 0
    
    3 - File Offset.
    
        This parameter specifies the byte offset in the file where the read starts.
    
          Type:    Unsigned 32-bit value
    
          Range:   0 to 0xFFFFFFFF
    
          Default: 0
    
    4 - Transfer Length.
    
        This parameter specifies the number of consecutive bytes of the data to transfer.
    
          Type:    Unsigned 32-bit value
    
          Range:   0 to 0xFFFFFFFF
    
          Default: 0xFFFFFFFF (whole file)
    
    5 - Output Format.
    
        This parameter specifies the format of output data.
    
             Bit [3:0]   - This bit fileds selects the binary file transfer protocol.
                1 - YMODEM protocol
    
             Bit [7:4]   - Reserved for future use.
    
             Bit [8]     - When set, this bit selects ASCII-HEX output format.
    
             Bit [9]     - When set, this bit selects ASCII output format.
    
             Bit [15:10] - Reserved for future use.
    
          Type:    Unsigned 16-bit value
    
          Range:   0 to 0xFFFF
    
          Default: 1 (transfer file using YMODEM protocol)
    
  Output Data:


    If an error occurred, the following information will be displayed.
    
          "DiagError aaaaaaaa"
    
       where
    
          aaaaaaaa is the Diagnostic Error Code
    
    If no error occurred, then the output of this command will be displayed as follows.
    
          "File Volume b"
          "File ID ccc"
          "File Copy Number d"
          "File Descriptor eeeeeeee"
          "File Size ffffffff"
          "Byte Offset gggggggg"
          "Bytes to read hhhhhhhh"
    
       where
    
          b        is the File Volume
    
          ccc      is the File ID
    
          d        is the File Copy Number
    
          eeeeeeee is the File Descriptor
    
          ffffffff is the size of the file in bytes
    
          gggggggg is the byte offset within the file where the data is located
    
          hhhhhhhh is the number of bytes of the data to read
    
    If the binary output format was selected by specifying desired file transfer protocol
    in bit 0 through 3 of the input parameter 5, then the following will be displayed
    when the drive is ready to send the file to the host.
    
          "Drive is ready to send FILE_b_ccc_d file."
    
       where
    
          b        is the File Volume
    
          ccc      is the File ID
    
          d        is the File Copy Number
    
    If bit 8 of the input parameter 5 is set then file data will be displayed in ASCII-HEX format
    as shown below.
    
    Offset number 0x00000000 is used here.
    
          +- starting byte offsets of each lines
          |
          Offset   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    <- byte offsets within lines
          00000000 FF FF FF FF 39 53 5A 30 31 4E 4D 51 30 30 30 30    <- file data of the first line
          00000010 43 38 33 33 34 47 31 50 FF FF FF FF FF FF FF FF
          00000020 FF FF 02 01 50 00 C5 00 02 90 5C 94 2D 07 FF FF
          .
          . repeats for the number of lines to display whole data
          .
          nnnnnnnn FF FF FF FF FF FF FF FF FF FF FF FF FF FF 00 51    <- file data of the last line
    
       where
    
          nnnnnnnn indicates the starting offset of the each line.
    
    If bit 9 of the input parameter 5 is set then file data will be displayed in ASCII format
    as shown below.
    This mode is especially useful for displaying text files.
    
          +- starting byte offsets of each lines
          |
          Offset   0123456789ABCDEF    <- byte offsets within lines
          00000000 ....9SZ01NMQ0000    <- file data of the first line
          00000010 C8334G1P........
          00000020 ....P.....\.-...
          .
          . repeats for the number of lines to display whole data
          .
          nnnnnnnn ...............Q    <- file data of the last line
    
       where
    
          nnnnnnnn indicates the starting offset of the each line.
    
    If both of bit 9 and bit 8 of the input parameter 5 are set then file data will be displayed
    in ASCII-HEX format along with ASCII format as well as like followings.
    
          +- starting byte offsets of each lines
          |
          Offset   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 0123456789ABCDEF   <- byte offsets within lines
          00000000 FF FF FF FF 39 53 5A 30 31 4E 4D 51 30 30 30 30 ....9SZ01NMQ0000   <- file data of the first line
          00000010 43 38 33 33 34 47 31 50 FF FF FF FF FF FF FF FF C8334G1P........
          00000020 FF FF 02 01 50 00 C5 00 02 90 5C 94 2D 07 FF FF ....P.....\.-...
          .
          . repeats for the number of lines to display whole data
          .
          nnnnnnnn FF FF FF FF FF FF FF FF FF FF FF FF FF FF 00 51 ...............Q   <- file data of the last line
    
       where
    
          nnnnnnnn indicates the starting offset of the each line.
    
  Examples:

    Example #1:
    To read the Primary Defects super file from the System Disc volume and send it to the
    host using the YMODEM protocol

       F3 T>r1b

    Example #2:
    To read the Primary Defects super file from the System Disc volume and send it to the
    host using the YMODEM protocol at 115200 bps baud rate.

       F3 T>B115200
       User should change the baud rate setting to 115200 bps in the terminal program.
       F3 T>r1b

    Example #3:
    To read the CAP file from the Flash volume and send it to the host using the YMODEM
    protocol

       F3 T>r208,9

    Example #4:
    To read the CAP file from the System Disc volume and display it in the ASCII-HEX
    output format

       F3 T>r208,,,,,100

    Example #5:
    To read the CAP file from the System Disc volume and display it in the ASCII output
    format

       F3 T>r208,,,,,200

    Example #6:
    To read the CAP file from the System Disc volume and display it in the ASCII-HEX and
    the ASCII output format

       F3 T>r208,,,,,300

  Revision History:

    0001.0000   Initial revision.