Shareware Overload/ShartewareOverload.cdr/progm/flash-c1.zip/CH5_1.DOC

Text File | 1990-02-11 | 19KB | 788 lines

..pgno01
..foot63A5-##
..head02L──────────────────────────────────────────────────────────────────────
..head04L──────────────────────────────────────────────────────────────────────
..head03LGlobal Structures

typedef TFindRec = {
                   UINT2 Attr;
                   UINT2 Time;
                   UINT2 Date;
                   UINT4 Size;
                   UCHAR Name[13];
                   } TFindRec;



Global Variable Declarations
──────────────────────────────────────────────────────────────────────
INT2 DosErrNo         the error code for function result errors.

INT2 CErrCode         the error code for critical errors.

INT2 CErrType         contains the type of device for the critical
                      error.
                         0 = Block device
                         1 = Character device

INT2 CErrDrive        contains the number of the disk drive where the
                      critical error occurred.  If the critical error
                      is not a disk drive the value will then remain
                      as -1.

CHAR CErrDevice[9]    contains the name of the device in error.
..page
..head03ACloseFile
■ Description

  Closes a file and flushes all file buffers for a file.

■ Summary

   Procedure CloseFile( Handle : Integer );

   Handle     the handle number of a file that was opened using the
              OpenFile operation.


■ Remarks

  If an error occurred DosErrNo will contain one of the following
  error codes.

     DosErrNo     Description
     ──────── ───────────────────
        6     Invalid file handle


■ Example

  #include <fpclib.h>

  main()
  {
     INT Handle;

     OpenFile( "Temp.Fil", READ_ONLY, &Handle );
             .
             .
             .
     CloseFile( Handle );
  }

  This example will close the file that is associate with the handle
  number returned in the OpenFile function.  If the close operation
  was successful DosErrNo will contain a zero, provided the variable
  was reset to zero after the last I/O error.  If an error occurred
  DosErrNo should contain the value 6.
..page
..head03ACreateFile
■ Description

  Opens an existing file or creates a new file if it does not exist.


■ Summary

  Procedure CreateFile(     Path   : String;
                            Attr   : Integer;
                        Var Handle : Integer );

  Path        the path and filename of the file to be opened or
              created.

  Attr        mode to set the file's attribute to.

  Handle      returns an integer that this file is assoicated with for
              access.


■ Remarks

  This operation will open a new or existing file for read/write
  access. CreateFile assumes that the file is opened as an output file
  and will set the length of any existing file to zero.  If any errors
  occur DosErrNo will have the error code.

  DosErrNo    Description
  ──────── ───────────────────
     3     Path not found
     4     No handle available
     5     Access denied
     6     Invalid file handle


■ See Also

  OpenFile
..page
■ Example

  #include <fpclib.h>

  main()
  {
     CreateFile( "NewFile", 32, &Handle );
             .
             .
             .
  }

  If "Newfile" exists in the current directory then CreateFile will
  open the file for output and assign a length of zero to the file.
  If "Newfile" does not exist then a new file will be created.  The
  variable Handle will return an integer that is associated with the
  file "Newfile". DosErrNo will contain zero if the CreateFile
  operation was successful.
..page
..head03ADosFindFirst
■ Description

  Find the first file that matches the given filespec and attributes.


■ Summary

  Procedure DosFindFirst(    Path    : String;
                             Attr    : Integer;
                         Var FindRec : TFindRec );

  Path        the path and filename of the file to search for.

  Attr        attributes of the files to include in the file search

  FindRec     the result of the search is returned in a variable of
              TFindRec. (See Global Structures page 5-1).


■ Remarks

  This operation will search for the specified file.  The characters *
  and ? may be used for the filespec.  If any errors occur DosErrNo
  will have the error code.

  DosErrNo    Description
  ──────── ───────────────────
     2     Directory not found
     3     Path not found
    18     No more files

  The search attibute values may be one or any combination of values.
  (e.g. to search for a hidden system file use value 6).

  Bit(s)   Value   Description
  ──────   ─────   ───────────
   0         1     read-only
   1         2     hidden
   2         4     system
   3         8     volumne label
   4        16     directory
   5        32     archive
   6-15            reserved


■ See Also

  DosFindNext
..page
■ Example

  #include <fpclib.h>

  main()
  {
      TFindRec Rec;

      DosFindFirst( "*.PAS", 32, &Rec );
  }

  This example will find the first occurrance of a file in the current
  directory that has the extension of "PAS".
..page
..head03ADosFindNext
■ Description

  Returns the next file entry that matches the filespec and attributes
  used in a previous call to DosFindFirst.


■ Summary

  Procedure DosFindNext( Var FindRec : TFindRec );

  FindRec     the result of the search is returned in the variable of
              TFindRec. (See Global Structures page 5-1).


■ Remarks

  DosFindNext must be called after DosFindFirst and before any other
  calls that transfer data into the DTA at the time of the call to
  DosFindFirst.

  DosErrNo    Description
  ──────── ──────────────────
     18    No more files


■ See Also

  DosFindFirst


■ Example

  #include <fpclib.h>

  main()
  {
     TFindRec Rec;

     DosFindFirst( "*.PAS", 32, &Rec );
     while ( !DosErrorNo ) {
        printf( "%s", Rec.Name );
        DosFindNext( &Rec );
     }
  }

  This example will find the all occurrances of files in the current
  directory that have the extension of "PAS".
..page
..head03AFSeek
■ Description

  Change the logical read/write position of the file pointer.


■ Summary

  UINT4 FSeek( INT Handle, INT Orgin, INT4 Offset );

  Handle      file handle that was assigned to a file using either the
              OpenFile or CreateFile operaton.

  Orgin       gives the starting location to use when moving the file
              pointer.

              Method           Description
              ────── ────────────────────────────────
               0     beginning of file
               1     current location of file pointer
               2     EOF location

  Offset      gives the number of bytes to move the file pointer.


■ Remarks

  This operation will move the file pointer for the specified number
  of bytes given.  On return this function reports the number of bytes
  the file pointer is from the beginning of the file.  If any errors
  occur DosErrNo will have the error code.

  DosErrNo Description
  ──────── ───────────────────
      1    Invalid method code
      6    Invalid file handle
..page
■ Example

  #include <fpclib.h>

  main()
  {
     INT  handle;
     INT4 offset;

     Openfile( "file.dat", 2, &handle );

      if ( !DosErrNo )
        offset = FSeek( handle, 2, 0L );
  }

  Executing FSeek with an offset of zero, and the seek beginning at
  the end of the file, the variable Offset will contain a long integer
  of the file size in bytes.  FSeek always returns the number of bytes
  the file pointer is located from the beginning of the file.
..page
..head03AGetDrive
■ Description

  Reports the current default disk drive


■ Summary

  Function GetDrive : Integer;


■ Remarks

  GetDrive returns an integer to indicate which disk drive is the
  current default drive where:

     Drive A = 1
     Drive B = 2
     Drive C = 3


■ Example

  #include <fpclib.h>

  main()
  {
     printf( "Current Drive is %c", GetDrive()+65 );
  }

  The write statement will display the letter of the drive that is the
  current default drive.
..page
..head03AGetDTA
■ Description

  Returns the current disk transfer area


■ Summary

  Procedure GetDTA( Var Segment, Offset : Word );

  Segment     returns the segment of the current DTA.

  Offset      returns the offset of the current DTA.


■ Example

  #include <fpclib.h>

  main()
  {
     UINT Segment,Offset;

     GetDTA( Segment, Offset );
     printf("DTA Segment = %4X  DTA Offset = %4X", Segment, Offset );
  }

  After the call to GetDTA the integer variables segment and offset
  will contain the Segment:Offset address for the current disk
  transfer area.
..page
..head03AGetFileSize
■ Description

  Report the number of bytes in a disk file.


■ Summary

  Function GetFileSize( INT Handle ) : LongInt;

  Handle      gives a file handle that was assigned to a file using
              the OpenFile or CreateFile operaton.


■ Remarks

  GetFileSize reports the number of bytes in the file associated with
  the handle number.


■ Example

  #include <fpclib.h>

  main()
  {
     INT   handle;
     UINT4 offset;

     Openfile( "file.dat", 2, &handle );
     printf( "Total bytes in file.dat = %u ", GetFileSize( handle ) );
  }

  In this example the printf statement will display the total number
  of bytes in the file "file.dat".
..page
..head03AGetNDrvs
■ Description

  Report the number of disk drives.


■ Summary

  Function GetNDrvs : Integer;


■ Remarks

  GetNDrvs reports the total number of diskette and fixed disk drives
  installed for the current system.


■ Example

  #include <fpclib.h>

  main()
  {
     printf("Number of disk drives installed = %u ", GetNDrvs() );
  }

  In this example the printf statement will display the numeric value
  for the current number of disk drives currently installed on the
  system.
..page
..head03AOpenFile
■ Description

  Open the file given in the string passed.


■ Summary

  Procedure OpenFile(    Path   : String;
                         Attr   : Integer;
                     Var Handle : Integer )

  Path        the path and filename of the file to open.

  Attr        the type of access to be allowed for this file.

                 Access Code Description
                 ─────────── ──────────────────
                      0      Read Only access
                      1      Write Only access
                      2      Read/write access

  Handle      returns an integer that represents the file handle that
              is associated with the file given in Path.  The file
              handle is to be used when any operations on the file are
              to take place.

■ Remarks

  If an error occurred DosErrNo will contain one of the following
  error codes.

  DosErrNo Description
  ──────── ───────────────────
     2     File not found
     4     No handle available
     5     access denied
    12     invalid access code


■ See Also

  CreateFile
..page
■ Example

  #include <fpclib.h>

  main()
  {
     INT handle;

     OpenFile( "file.dat", 0, &handle );

  }

  On return from opening the file, if DosErrNo contains a zero, handle
  will contain the integer of the file handle for the file 'File.dat'.
  The file is opened for read only access.
..page
..head03AReadFile
■ Description

  Read a file or device for a specified number of bytes.


■ Summary

  Procedure ReadFile(    Handle : Integer;
                         NBytes : Integer;
                     Var Buffer          ;
                     Var RBytes : Word    );

  Handle      file handle associated with the appropriate file or
              device for the read operation to act on.

  NBytes      number of bytes to read from the file or device.

  Buffer      buffer area to place the data read.

  RBytes      returns the number of bytes actually read from the file
              or device.  If RBytes is zero then an attempt was made
              to read from the end of a file.


■ Remarks

  If an error occurred DosErrNo will contain one of the following
  error codes.

  DosErrNo Description
  ──────── ───────────────────
     5     Access denied
     6     Invalid handle


■ Example

  #include <fpclib.h>

  main()
  {
     CHAR Buffer[128];
     UINT handle,NBytes,RBytes;

     OpenFile( "file.dat", 0, &handle );
     FSeek( handle, 0, 0 );
     ReadFile( handle, 128, Buffer, &RBytes );
  }

  Assuming no errors, 128 bytes will be read from the file and placed
  into the variable Buffer.  On return from ReadFile the variable
  RBytes will contain the actual number of bytes that were read from
  the file.
..page
..head03AResetDisk
■ Description

  Resets the disk and flushes all file buffers.


■ Summary

  Procedure ResetDisk;


■ Remarks

  This routine does not close any files.  To ensure that the length of
  a file is recorded properly in the file directory you should first
  close the file before using this routine.
..page
..head03AResetErrCodes
■ Description

  Resets global variables that indicate device errors to their initial
  settings.


■ Summary

  Procedure ResetErrCodes;


■ Remarks

  The following variables are set as followings:

     DosErrNo   =  0
     CErrCode   =  0
     CErrType   = -1
     CErrDrive  = -1
     CErrDevice = ''

■ See Also

  SetInt24
..page
..head03ARestInt24
■ Description

  Uninstalls or restores the programs critical interrupt error
  handler.


■ Summary

  Procedure RestInt24;


■ See Also

  SetInt24


■ Remarks

  This procedure will uninstall the critical interrupt error handler
  that was installed with the SetInt24 procedure.  This procedure uses
  the SegInt24 and OfsInt24 variables to restore the interrupt handler
  in use before the interrupt handler was installed.
..page
..head03ASetDTA
■ Description

  Set the file attribute for the file specified.


■ Summary

  Procedure SetDTA( Segment, Offset : Word );

  Segment     segment address for the new DTA.

  Offset      offset within the segment for the new DTA.


■ Example

  #include <dos.h>
  #include <fpclib.h>

  main()
  {
     CHAR Buffer[4096];

     SetDTA( FP_SEG( Buffer ), FP_OFF( Buffer ) );
  }

  The new DTA will point to the data variable Buffer and all the
  information associated with the Disk Transfer Area will be placed in
  the data variable Buffer until the DTA address is changed.
..page
..head03ASetInt24
■ Description

  Initializes the critical error handler routine and its global
  variables for use with your system.


■ Summary

  Procedure SetInt24;


■ Remarks

  Only one call needs to be made to this routine for a program that
  wants to use the critical error handler routine.  In the event of a
  critical error, the variables DosErrNo, CErrCode, CErrType,
  CErrDrive and CErrDevice are set to the appropiate values.  Refer to
  the global variable section at the beginning of this chapter for a
  description of each variable name.

  The following are the I/O error values that are set in the CErrCode
  global variable.  These codes match the same codes DOS function 59h
  (Get Extended Error Code) return.  Notice that all values are
  hexadecimal.

  Error
  Code        Description
  ───── ──────────────────────────────-
   13   Write-protect error
   14   Unknown unit
   15   Disk drive not ready
   16   Unknown command
   17   Data error (bad CRC)
   18   A bad request structure length
   19   Data seek error
   1A   Unknown media type
   1B   Disk sector not found
   1C   Printer is out of paper
   1D   Write fault
   1E   Read fault
   1F   General failure


■ See Also

  ResetErrCodes, RestInt24
..page
■ Example

  #include <fpclib.h>

  main()
  {
     INT handle;

     SetInt24();

     CreateFile( "a:file.dat", 0, &handle );

     if ( !DosErrNo ) {
        printf( "DosErrNo   = %d\n", DosErrNo   );
        printf( "CErrCode   = %d\n", CErrCode   );
        printf( "CErrType   = %d\n", CErrType   );
        printf( "CErrDrive  = %d\n", CErrDrive  );
        printf( "CErrDevice = %d\n", CErrDevice );
     }
     else {
        printf( "file opened ok..." );
        CloseFile( handle );
     }
  }

  If this program was executed with the A: drive door open, a critical
  error would occur.  On return from CreateFile the critical error
  variables should be set to the following values:

     DosErrNo   = 3             Path not found
     CErrCode   = 21            Disk drive not ready
     CErrType   = 0             0=Block    1=Character
     CErrDrive  = 0             Drive A=0, B=1, C=2, etc
     CErrDevice = DISKETTE      Device name
..page
..head03AWriteFile
■ Description

  Write to a file or device for a specified number of bytes.


■ Summary

  Procedure WriteFile(     Handle : Integer;
                           NBytes : Integer;
                       Var Buffer          ;
                       Var WBytes : Integer );

  Handle      the file handle that is associated with the appropriate
              file or device for the read operation to act on.

  NBytes      number of bytes to write to the file or device.

  Buffer      this is the data area that contains the data that is to
              be written to the file or device.

  WBytes      returns the actual number of bytes that were written out
              to the file or device.


■ Remarks

  DosErrNo will contain one of the following error codes when an error
  occurs.

  DosErrNo    Description
  ──────── ───────────────────
     5     Access denied
     6     Invalid handle
    20     insufficent disk space


■ Example

  #include <fpclib.h>
  main()
  {
     CHAR  Buffer[128];
     INT   handle, WBytes;

     CreateFile( "file.dat", 2, &handle );
     memset( Buffer, 'A', 128 );
     WriteFile( handle, 128, Buffer, &WBytes );
     CloseFile( handle );
  }

  This example will create a file and write out 128 A's to the new
  file.  WBytes on return should contain the value 128.
..page