Change File Pointer (QHFCHGFP) API

The Change File Pointer (QHFCHGFP) API moves the file pointer a specified number of bytes forward or backward. (The file pointer is the current read/write position in the file.) This file pointer is used by the Read from Stream File (QHFRDSF) and Write to Stream File (QHFWRTSF) APIs. You can also use the QHFCHGFP API to determine the size of a file by moving the pointer to the end of the file.

Authorities and Locks

None.

Required Parameter Group

Open file handle

INPUT; CHAR(16)

The handle returned when the file was opened with the Open Stream File (QHFOPNSF) API.

Move information

INPUT; CHAR(6)

Additional information specifying the action to take. The 6 characters of this parameter are:

1

The pointer's starting location. The pointer is moved the distance you specify from this place. For example, specifying 0 here and 5 in the distance to move parameter moves the pointer to a new position 5 bytes from the start of the file. Valid values for the starting location are: 0 The beginning of the file. 1 The pointer's current location. 2 The end of the file. If the distance to move is zero, the new offset parameter returns the file's size.

2-6

Reserved. These characters must be set to blanks.

Distance to move

INPUT; BINARY(4)

The distance to move the pointer from the starting location, in bytes. A negative value parameter moves the pointer backward in the file. A positive value moves it forward.

The file pointer can be set to any location that can be supported by a 4-byte unsigned value. An error is returned only if the application tries to move the pointer to a negative position or an offset larger than the maximum value that can be stored in a 4-byte unsigned binary number.

Setting the file pointer beyond the end of the file is allowed, but it does not change the file's size. To change the file's size, see Set Stream File Size (QHFSETSZ) API or Write to Stream File (QHFWRTSF) API.

For brief examples of how the move information and the distance to move work together, see How to Move the File Pointer.

New offset

OUTPUT; BINARY(4) UNSIGNED

The new position of the pointer.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

How to Move the File Pointer

The file pointer represents a position or offset within a file where the next read or write is to take place. It does not actually point to a byte in the file; rather, it points to the gap between bytes. The diagram below represents a 10-byte file as a series of boxes. Each box represents a byte of data in the file.

Examples

1. To move the file pointer to the beginning of the file, set the start location in the move information parameter to zero (the beginning of the file). Set the distance to move to zero, too.
   
   
2. To move the file pointer to offset 3 (that is, pointing to the gap between bytes 3 and 4), set the start location in the move information parameter to zero (the beginning of the file). Set the distance to move to 3.
   
   
3. To move the file pointer to the end of the file, set the start location in the move information parameter to 2 (the end of the file). Set the distance to move to zero. The new offset parameter returns the file's size.

Error Messages