Read file

Purpose: Read file into a string variable.

 read-file <file> | ( file-id <file id> ) \
     to <content> \
     [ position <position> ] \
     [ length <length> ] \
     [ status <status> ]

Without file-id

This is a simple method of reading a file. File named <file> is opened, data read, and file is closed.

<file> can be a full path name, or a path relative to the application home directory (see directories).

Data read is stored into string <content>. Note that file can be binary or text and <content> may have null-bytes.

If "position" and "length" clauses are not specified, read-file reads the entire <file> into <content>.

If "position" clause is used, then reading starts at byte <position>, otherwise it starts at the beginning of the file. Position of zero (0) represents the beginning of the file.

If "length" clause is used, then <length> number of bytes is read, otherwise the rest of the file is read. If <length> is 0, <content> is empty string and <status> is 0.

If "status" clause is used, then the number of bytes read is stored to <status>, unless error occurred, in which case <status> is negative and has the error code. The error code can be GG_ERR_POSITION (if <position> is negative, outside the file, or file does not support it), GG_ERR_READ (if <length> is negative or there is an error reading file) or GG_ERR_OPEN if file is not open.

With file-id

This method uses a <file id> that was created with open-file. You can then read (and write) file using this <file id> and the file stays open until close-file is called, or the request ends (i.e. Gliimly will automatically close any such open files).

Data read is stored into string <content>. Note that file can be binary or text and <content> may have null-bytes.

If "position" clause is used, then data is read starting from byte <position> (with position of 0 being the first byte), otherwise reading starts from the current file position determined by the previous reads/writes or as set by using "set" clause in file-position. Note that after each read or write, the file position is advanced by the number of bytes read or written.

If "length" clause is used, then <length> number of bytes is read, otherwise the rest of the file is read. If <length> is 0, <content> is empty string and <status> is 0.

Note that when you reach the end of file and no more bytes can be read, <status> is 0.

If "status" clause is used, then the number of bytes read is stored to <status>, unless error occurred, in which case <status> has the error code. The error code can be GG_ERR_POSITION (if <position> is negative, outside the file, or file does not support it), GG_ERR_READ (if <length> is negative or there is an error reading file) or GG_ERR_OPEN if file is not open.

Examples

To read the entire file and create both the variable that holds its content and the status variable:

 read-file "/home/user/some_file" to file_content status st
 if-true st greater-than 0
     @Read:
     @<hr/>
     p-web file_content
     @<hr/>
 else-if
     @Could not read (<<pf-out "%ld", st>>)
 end-if

To read 10 bytes starting at position 20 (with position 0 being the first byte):

 read-file "/home/user/some_file" to file_content position 20 length 10

See open-file for an example with "file-id" clause.