IntroductionMTB StatementsFile SystemCompilerApplicationsReference GuideIndex

Move File Read/Write Pointer (LSEEK)

Syntax: DOSMS(AX-value,BX-value,CX-value,DX-value) EXCP=statement-label
Entry: 
  AX-value = "@4200@"    (move from beginning of file)

  (or)

  AX-value = "@4201@"    (move from current pointer location)

  (or)

  AX-value = "@4202@"    (move from end of file)

  BX-value = file handle (from previous open)
  CX-value = most significant portion of offset (in hex)
  DX-value = least significant portion of offset (in hex)
Return: 
  If the function call is successful, the DX and AX fields will
  contain the file pointer's new location (in hex). Values less
  than or equal to 65,535 (64K bytes) will be stored in the field
  AX. If the pointer value exceeds 65,536, the DX-value will
  contain the larger portion and the AX value will contain the
  smaller portion.

  If an exception occurs, byte 2 of the AX field will contain the
  DOS error code (in hex).
Discussion: The DOSMS function call can be used to move the read/write pointer in a DOS file. This function is also known as LSEEK. This call requires that the AX-value be set according to the type of move desired. The first byte of AX will always be hex 42, while the second byte is set according to the following chart:

Value Type of move
00 Move relative to the beginning of the file
01 Move relative to the current position of the file pointer
02 Move from the end of the file.

For example, to move the pointer relative to the beginning of the file, the AX-value should equal "@4200@".

The BX-value should contain the file's handle. This value is established when the file is opened.

The CX and DX values should contain the offset value (in hex). The offset is the positive number of bytes the pointer is to be moved. The DX-value contains the least significant portion of the offset, while the CX-value contains tthe most significant portion.

After the call is executed, the file pointer will be re- positioned in the DOS file. Its new position is a function of the type of move specified, the offset specified, and the original location of the file pointer.

For example, to move the pointer 100 bytes forward from its current location, you would:

  1. Set the AX-value to "@4201@" (move relative to current position)
  2. Set the BX-value to the file's handle
  3. Set the CX-value to null (not used in this example)
  4. Set the DX-value to "@0064@" (the hex equivalent of 100)
  5. Execute the DOSMS function call

Notes:

  1. If the offset value exceeds 65,536 (64K bytes), the CX-value may be used to contain the larger portion. Otherwise, CX remains null and DX is used to set the offset value.
  2. If you move the pointer past the end of the file, it will be positioned at the new location, logically extending the length of the file to the new position.
  3. If you position the pointer within the file (i.e., not past the end of file) and then write zero bytes to the file, the file will be truncated and the remaining data will be lost. The new end of file will be the position of the pointer before the zero-byte write.

DOS function calls/pseudo calls