Difference between revisions of "DosProtectSetFilePtr"

From EDM2
Jump to: navigation, search
(Created page with "==Description== Moves the read or write pointer according to the type of move specified. ==Syntax== <PRE> #define INCL_DOSFILEMGR #include <os2.h> HFILE hFile; ...")
 
m
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Description==
 
 
Moves the read or write pointer according to the type of move specified.
 
Moves the read or write pointer according to the type of move specified.
  
 
==Syntax==
 
==Syntax==
<PRE>
+
DosProtectSetFilePtr(hFile, ib, method, ibActual, fhFileHandleLockID)
#define INCL_DOSFILEMGR
+
#include <os2.h>
+
  
HFILE    hFile;              /*  The handle returned by a previous DosOpen function. */
 
LONG      ib;                  /*  The signed distance (offset) to move, in bytes. */
 
ULONG    method;              /*  The method of moving. */
 
PULONG    ibActual;            /*  Address of the new pointer location. */
 
FHLOCK    fhFileHandleLockID;  /*  The filehandle lockid returned by a previous DosProtectOpen. */
 
APIRET    ulrc;                /*  Return Code. */
 
 
ulrc = DosProtectSetFilePtr(hFile, ib, method, ibActual, fhFileHandleLockID);
 
 
</PRE>
 
 
==Parameters==
 
==Parameters==
; hFile (HFILE) - input : The handle returned by a previous DosOpen function.  
+
;hFile (HFILE) - input : The handle returned by a previous DosOpen function.
 +
;ib (LONG) - input : The signed distance (offset) to move, in bytes.
 +
;method (ULONG) - input : The method of moving.
 +
:This field specifies the location in the file at which the read/write pointer starts before adding the ib offset. The values and their meanings are as shown in the following list:
 +
::FILE_BEGIN Move the pointer from the beginning of the file.
 +
::FILE_CURRENT Move the pointer from the current location of the read/write pointer.
 +
::FILE_END Move the pointer from the end of the file. Use this method to determine a file's size.
 +
;ibActual (PULONG) - output : Address of the new pointer location.
 +
;fhFileHandleLockID (FHLOCK) - input : The filehandle lockid returned by a previous [[DosProtectOpen]].
  
; ib (LONG) - input : The signed distance (offset) to move, in bytes.
 
 
; method (ULONG) - input : The method of moving.
 
 
This field specifies the location in the file at which the read/write pointer starts before adding the ib offset. The values and their meanings are as shown in the following list:
 
 
    FILE_BEGIN
 
    Move the pointer from the beginning of the file.
 
 
    FILE_CURRENT
 
    Move the pointer from the current location of the read/write pointer.
 
 
    FILE_END
 
    Move the pointer from the end of the file. Use this method to determine a file's size.
 
 
; ibActual (PULONG) - output : Address of the new pointer location.
 
 
; fhFileHandleLockID (FHLOCK) - input : The filehandle lockid returned by a previous DosProtectOpen.
 
 
==Return Code==
 
==Return Code==
ulrc (APIRET) - returns
+
;ulrc (APIRET) - returns:DosProtectSetFilePtr returns one of the following values:
 
+
* 0 NO_ERROR
DosProtectSetFilePtr returns one of the following values:
+
* 1 ERROR_INVALID_FUNCTION
 
+
* 6 ERROR_INVALID_HANDLE
* 0   NO_ERROR  
+
* 132 ERROR_SEEK_ON_DEVICE
* 1       ERROR_INVALID_FUNCTION  
+
* 131 ERROR_NEGATIVE_SEEK
* 6       ERROR_INVALID_HANDLE  
+
* 130 ERROR_DIRECT_ACCESS_HANDLE
* 132       ERROR_SEEK_ON_DEVICE  
+
* 131       ERROR_NEGATIVE_SEEK  
+
* 130       ERROR_DIRECT_ACCESS_HANDLE
+
  
 
==Remarks==
 
==Remarks==
Line 142: Line 116:
 
   return NO_ERROR;
 
   return NO_ERROR;
 
}
 
}
 +
</PRE>
  
</PRE>
 
 
==Related Functions==
 
==Related Functions==
* [[OS2 API:CPI:DosProtectOpen|CPI:DosProtectOpen]]
+
* [[DosProtectOpen]]
* [[OS2 API:CPI:DosProtectRead|CPI:DosProtectRead]]
+
* [[DosProtectRead]]
* [[OS2 API:CPI:DosProtectSetFileSize|CPI:DosProtectSetFileSize]]
+
* [[DosProtectSetFileSize]]
* [[OS2 API:CPI:DosProtectWrite|CPI:DosProtectWrite]]  
+
* [[DosProtectWrite]]  
 
+
  
[[Category:The OS/2 API Project]]
+
[[Category:Dos]]

Latest revision as of 06:49, 1 December 2019

Moves the read or write pointer according to the type of move specified.

Syntax

DosProtectSetFilePtr(hFile, ib, method, ibActual, fhFileHandleLockID)

Parameters

hFile (HFILE) - input 
The handle returned by a previous DosOpen function.
ib (LONG) - input 
The signed distance (offset) to move, in bytes.
method (ULONG) - input 
The method of moving.
This field specifies the location in the file at which the read/write pointer starts before adding the ib offset. The values and their meanings are as shown in the following list:
FILE_BEGIN Move the pointer from the beginning of the file.
FILE_CURRENT Move the pointer from the current location of the read/write pointer.
FILE_END Move the pointer from the end of the file. Use this method to determine a file's size.
ibActual (PULONG) - output 
Address of the new pointer location.
fhFileHandleLockID (FHLOCK) - input 
The filehandle lockid returned by a previous DosProtectOpen.

Return Code

ulrc (APIRET) - returns
DosProtectSetFilePtr returns one of the following values:
  • 0 NO_ERROR
  • 1 ERROR_INVALID_FUNCTION
  • 6 ERROR_INVALID_HANDLE
  • 132 ERROR_SEEK_ON_DEVICE
  • 131 ERROR_NEGATIVE_SEEK
  • 130 ERROR_DIRECT_ACCESS_HANDLE

Remarks

The read/write pointer in a file is a signed 32-bit number. A negative value for ib moves the pointer backward in the file; a positive value moves it forward. DosProtectSetFilePtr cannot be used to move to a negative position in the file.

DosProtectSetFilePtr cannot be used for a character device or pipe.

Example Code

This example opens or creates and opens a file named "DOSPROT.DAT", writes a string to it, returns the file pointer to the beginning of the file, reads it, and finally closes it using DosProtect functions.

#define INCL_DOSFILEMGR          /* File Manager values */
#define INCL_DOSERRORS           /* DOS Error values    */
#include <os2.h>
#include <stdio.h>
#include <string.h>

int main(VOID) {
   HFILE  hfFileHandle   = 0L;
   ULONG  ulAction       = 0;
   ULONG  ulBytesRead    = 0;
   ULONG  ulWrote        = 0;
   ULONG  ulLocal        = 0;
   UCHAR  uchFileName[20]  = "dosprot.dat",
          uchFileData[100] = " ";
   FHLOCK FileHandleLock = 0;        /* File handle lock   */
   APIRET rc             = NO_ERROR; /* Return code */

   /* Open the file test.dat.  Make it read/write, open it */
   /* if it already exists and create it if it is new.     */
   rc = DosProtectOpen(uchFileName,             /* File path name          */
                &hfFileHandle,                  /* File handle             */
                &ulAction,                      /* Action taken            */
                100L,                           /* File primary allocation */
                FILE_ARCHIVED | FILE_NORMAL,    /* File attribute          */
                OPEN_ACTION_CREATE_IF_NEW |
                OPEN_ACTION_OPEN_IF_EXISTS,     /* Open function type      */
                OPEN_FLAGS_NOINHERIT |
                OPEN_SHARE_DENYNONE  |
                OPEN_ACCESS_READWRITE,          /* Open mode of the file   */
                0L,                             /* No extended attribute   */
                &FileHandleLock);               /* File handle lock id     */
   if (rc != NO_ERROR) {
      printf("DosProtectOpen error: return code = %u\n", rc);
      return 1;
   } else {
     printf ("DosProtectOpen: Action taken = %u\n", ulAction);
   } /* endif */

   /* Write a string to the file */
   strcpy (uchFileData, "testing...\n3...\n2...\n1\n");

   rc = DosProtectWrite (hfFileHandle,       /* File handle                  */
                  (PVOID) uchFileData,       /* String to be written         */
                  sizeof (uchFileData),      /* Size of string to be written */
                  &ulWrote,                  /* Bytes actually written       */
                  FileHandleLock);           /* File handle lock id          */
   if (rc != NO_ERROR) {
      printf("DosProtectWrite error: return code = %u\n", rc);
      return 1;
   } else {
      printf ("DosProtectWrite: Bytes written = %u\n", ulWrote);
   } /* endif */

   /* Move the file pointer back to the beginning of the file */
   rc = DosProtectSetFilePtr (hfFileHandle,    /* File Handle          */
                       0L,                     /* Offset               */
                       FILE_BEGIN,             /* Move from BOF        */
                       &ulLocal,               /* New location address */
                       FileHandleLock);        /* File handle lock id  */
   if (rc != NO_ERROR) {
      printf("DosSetFilePtr error: return code = %u\n", rc);
      return 1;
   }

   /* Read the first 100 bytes of the file */
   rc = DosProtectRead (hfFileHandle,         /* File Handle                 */
                 uchFileData,                 /* String to be read           */
                 100L,                        /* Length of string to be read */
                 &ulBytesRead,                /* Bytes actually read         */
                 FileHandleLock);             /* File handle lock id         */
   if (rc != NO_ERROR) {
      printf("DosProtectRead error: return code = %u\n", rc);
      return 1;
   } else {
      printf("DosProtectRead: Bytes read = %u\n%s\n", ulBytesRead, uchFileData);
   } /* endif */

   rc = DosProtectClose(hfFileHandle, FileHandleLock);   /* Close the file */
   if (rc != NO_ERROR) {
      printf("DosProtectClose error: return code = %u\n", rc);
      return 1;
    }
   return NO_ERROR;
}

Related Functions