uread command

A file on the host system is represented as an unformatted string of bytes without internal subdividers or markers. READ and WRITE commands provide sequential access to files by advancing a pointer within the file. Subsequent READ or WRITE commands advance this internal pointer from the current position in the file. The user may specify the exact location within a file to be read by positioning the file pointer at the preferred location before executing the command.

See ulseek() function for additional information.

Format

UREAD var FROM FileHandle FOR n THEN statement(s) ELSE statement(s)

Description

The uread command reads the file currently opened to the file variable FileHandle for the number of bytes specified by n or until an EOF mark is reached. The n variable indicates the number of contiguous bytes to be read from the current file pointer position. The resulting string value is assigned to the var variable. If an error occurs, the ELSE clause executes and the uerror() command returns the appropriate error code. The file pointer is advanced by the number of bytes read.

• If the uread command is used before opening the file for reading, an error results, the ELSE clause executes, and the uerror() command returns the appropriate error code.
• If any data is successfully read, the ELSE clause is not taken. In that case, the uerror() command returns the number of bytes read.
• If an EOF is encountered, the value returned by the uerror() command is less than the requested amount.
• If no EOF is encountered, the value returned by the uerror() command is equal to the requested amount.
• If no data is successfully read due to an EOF being encountered immediately, the ELSE clause is taken, no data is returned, and the uerror() command returns the Windows error message 38: ERROR_HANDLE_EOF.
• If errors other than EOF occur during the uread command, the ELSE clause is taken, no data is returned, and the uerror() command returns the appropriate error code.

Example(s)

UOPEN "C:\TEST.TXT" TO HANDLE ELSE STOP
10 UREAD ITEM FROM HANDLE FOR 500 THEN
     PRINT UERROR( )
  END ELSE
     PRINT "ERROR CODE = ": UERROR( )
     GOTO EOJ:
  END
  GOTO 10
If TEST.TXT is 943 bytes the output is:
  500
  443  
  ERROR CODE = 38

The following example prints the first 50 bytes of the \books\chap5.txt file. If less than 50 bytes are present, the bytes available are printed. A null string is returned if the file pointer is positioned at the end of the file. Line feed characters embedded in the file are also printed.

FILENAME="c:\books\chap5.txt"
  UOPEN FILENAME FOR READ TO FILEDES ELSE
     PRINT "Unable to open ":FILENAME
     STOP
  END
  UREAD VAR1 FROM FILEDES FOR 50 ELSE GOTO EOJ:
  PRINT VAR1

After execution of the following example, the string TESTDATA2 is equal to TESTDATA1. The \books\chap6.txt file was created using the ucreate statement, which opened the file for writing only.

 TESTDATA1 = "THIS IS TEST DATA"
FILENAME="c:\books\chap6.txt"
  UCREATE FILENAME TO FILEDES2 ELSE
     PRINT "Unable to create and open ":FILENAME
     STOP
  END
  * Write out DATA and CLOSE
  UWRITE TESTDATA1 ON FILEDES2 ELSE
     PRINT "Write to ":FILENAME:" failed"
  END
  UCLOSE FILEDES2 ELSE
     PRINT "UCLOSE failed on ":FILENAME
  END
  *
  UOPEN FILENAME TO FILEDES3 ELSE STOP
  UREAD TESTDATA2 FROM FILEDES3 FOR 17 ELSE GO TO EOJ:

See also

O/S interoperability commands and functions, uclose command

ucreate command, udelete command

uerror() function, uexecute command

ulock command, ulseek() function

umessage command, uopen command

ureadline() function, usystem() function

uwaitfor command, uwrite command