CD Actual 15

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual 15 / CDACTUAL15.iso / cdactual / program / pascal / FLASHPAC.ZIP / CH5_1.DOC < prev next >

Wrap

Text File | 1991-03-15 | 18.3 KB | 785 lines

..pgno01 ..foot60A5-## ..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 VOID FPENTRY CloseFile( INT2 Handle ); 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 VOID FPENTRY CreateFile( CHAR *Path, INT2 Attr, INT2 *Handle ); 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 VOID FPENTRY DosFindFirst( CHAR *Path, INT2 Attr, TFindRec FindRec ); 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 VOID FPENTRY DosFindNext( TFindRec FindRec ); 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 INT2 FPENTRY GetDrive( VOID ); ■ 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 VOID FPENTRY GetDTA( UINT2 Segment, Offset ); 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 INT4 FPENTRY GetFileSize( INT Handle ); 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 INT2 FPENTRY GetNDrvs( VOID ); ■ 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 VOID FPENTRY OpenFile( CHAR *Path, INT2 Attr, INT2 *Handle ); 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 VOID FPENTRY ReadFile( INT2 Handle, INT2 NBytes, CHAR *Buffer, UINT2 *RBytes ); 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 VOID FPENTRY ResetDisk( VOID ); ■ 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 VOID FPENTRY ResetErrCodes( VOID ); ■ 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 VOID FPENTRY RestInt24( VOID ); ■ 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 VOID FPENTRY SetDTA( UINT2 Segment, UINT2 Offset ); 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 VOID FPENTRY SetInt24( VOID ); ■ 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 VOID FPENTRY WriteFile( INT2 Handle, INT2 NBytes, CHAR *Buffer, UINT2 *WBytes ); 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