Change File Pointer (QHFCHGFP) API


  Required Parameter Group:

1 Open file handle Input Char(16)
2 Move information Input Char(6)
3 Distance to move Input Binary(4)
4 New offset Output Binary(4) Unsigned
5 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

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.

Example showing how to move the file pointer


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

Message ID Error Message Text
CPF1F2D E File pointer position not valid.
CPF1F2E E Range of bytes in file in use.
CPF1F25 E File handle not valid.
CPF1F28 E Damaged file.
CPF1F4E E Move information value not valid.
CPF1F4F E Distance to move value not valid.
CPF1F41 E Severe error occurred while addressing parameter list.
CPF1F52 E Error code not valid.
CPF1F62 E Requested function failed.
CPF1F66 E Storage needed exceeds maximum limit for user profile &1.
CPF1F71 E Exception specific to file system occurred.
CPF1F72 E Internal file system error occurred.
CPF1F73 E Not authorized to use command.
CPF1F74 E Not authorized to object.
CPF1F82 E Function not supported.
CPF1F87 E Missing or damaged exit program &2.
CPF3C90 E Literal value cannot be changed.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R1

[ Back to top | Hierarchical File System APIs | APIs by category ]