DP Tool Club 19

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

/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / prg / bas / asilib11 / disk.doc < prev next >

Wrap

Text File | 1994-10-22 | 22KB | 623 lines

************************ ASILIB DISK/FILE SUBROUTINES ********************** DISK / FILE routines look for specified files on your disk, or report disk status. Several ASILIB disk/file subroutines return the following error codes: 1 = file name is a nul string 2 = file not found 3 = path not found 4 = too many open files 5 = access denied (file may be read-only or a subdirectory, or subdirectory not empty) 6 = handle invalid 8 = insufficient memory 15 = invalid drive 19 = disk is write-protected &HFFFF = input past end of file File attributes may be combined. Each bit of a file attribute means: 0 = normal files 1 = read-only 2 = hidden files 4 = system files 8 = volume label (only one per disk - may not be reliable) 16 = subdirectories 32 = archive bit set Thus a file attribute of 18 is a hidden subdirectory (16 OR 2) ASILIB's Input/Output subroutines provide fast, flexible file handling. These subroutines return an error code if something went wrong. Summary of ASILIB's file I/O subroutines: FOpen Open an existing file FCreate Make a new file and open it for output FClose Close a file opened by FOpen or FCreate FGet Read from a file opened by FOpen to an array FGetSTR Read an ASCII string from a file opened by FOpen FPut Write data to a file directly from an array FPutCHR Write one byte to a file FPutSTR Write an ASCII string to a file FPutCRLF Write CR+LF to a file FSeek moves the file pointer forward or backward in the file FFlush flushes the ASILIB and DOS output file buffers ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ DISKWP: determines if a floppy disk is write-protected Parameters: drive$, errcode Drive$ is of the form "A:filename.ext" or "b:"; either upper case or lower case may be used. Errcode = 0 if the disk in drive is OK; errcode = 1 if invalid drive, 3 if disk is write-protected, and errcode = 128 if drive not ready. Restrictions: Supports physical drives A: and B: only. Example: REM check to see if drive A: is ready call sub "diskwp", "A:", errcode REM error handling code... if errcode > 0 then . . . ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ DOTBAK: changes the file extension of an existing file to .BAK Parameters: Filename$, errcode Dotbak deletes a previous .BAK file of this name and renames the input filename.ext to filename.bak. Errcode returns a DOS error code: if errcode = 5, the existing .BAK file is probably read-only. All other errors refer to the name change operation. Example: REM I'm going to make a new file "MYDATA.DAT" so I want save the old REM version as a .BAK file call sub "dotbak", "mydata.dat", errcode REM check for errors if errcode > 0 then REM etc. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ DRIVESPACE: determine space on specified drive Parameters: drv$, total&, free&, errcode Returns the amount of total and free space left on a given disk drive. The drive string may be any legal disk drive, or "@" (AT sign) for the default drive. An illegal drive or other error will cause errcode to be returned as -1. Note that total& and free& are LONG integers; requires ASIC's Extended Math option. Works with logical devices up to 2,147 Megabytes. Example: drv$="C:" . . call sub "drivespace", drv$, total&, free&, errcode if errcode = -1 then print "Invalid drive specification" else print "Free space on drive "; print drv$; print " is"; print free&; print "bytes." print "Total space on drive "; print drv$; print " is"; print total&; print "bytes." end if ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FCLOSE: Close a file opened by FOpen or FCreate. Parameters: handle, errcode Handle is a valid file handle returned by a successful call to FOpen or FCreate. After a successful call to FClose, all output buffers will be flushed, the file will be closed and the handle will no longer be valid. Errcode is an MS-DOS error code returned by FClose if something went wrong. If errcode = 0, no error. Restrictions: An invalid handle will result in the error code &hex06. Example: call sub "FClose", (handle, errcode) ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FCOPY: copy a file Parameters: sourcename, copyname, errcode Both filenames must be ASCII strings. Drive and path need not be fully specified; filenames may not include * or ? wildcards. Requires 64k DOS memory available. Returns errcode=0 if no problems were encountered, errcode=-1 if insufficient DOS memory is available, or other MS-DOS error code if a file handling error occurred. Example: REM I want to copy ASILIB.LIB to drive a: call sub "fcopy", "asilib.lib", "a:asilib.lib", errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FCOUNT: counts the number of files matching an ASCIIZ filespec string. The filespec string may include the '*' and '?' wildcards. Parameters: Filename$, fileattribute, count Filename$ is a normal ASIC string with filename specifications, fileattribute is the type of file you want to find: i. e., normal, hidden, system; file attributes are listed at the beginning of this file. Count is the number of files matching the filespec$ specifications with the appropriate attributes. Example: REM I want to know how many .ASI files are in this directory fileattributes = 0 REM Nornal files only filename$ = "*.asi" call sub "fcount", filename$, fileattributes, count ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FCREATE: Create a new file, returning a handle for subsequent access. Parameters: filename$, handle, errcode Filename$ is the name of the file you want created. If a file of the same name already exists, the previous contents of the file will be lost and the file will be truncated to zero bytes. Handle is the file handle returned by FCreate. Errcode is an MS-DOS error code if something went wrong, or 0 if everything is cool. Example: REM first try to open an existing file, write-only access mode REM if that fails then create a new file with that name file$ = "anyold.dat" mode = 1 call sub "fopen", file$, mode, handle, errcode if errcode = 2 then call sub "fcreate", file$, handle, errcode endif ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FEXIST: Determine if a file exists. Parameters: filename$, errcode Tells you if a given file already exists and can be opened for Read access. Returns an error code if it doesn't; errcode = -1 if it does exist. Filename$ must not include any "?" or "*" wildcard characters. Example: filename$ = "asilib.lib" call sub "fexist", filename$, errcode IF errcode = -1 THEN PRINT "File already exists" IF errcode = 0 THEN PRINT "Path exists" REM Filename$ = "d:\path" IF errcode = 2 THEN PRINT "Path found, file not found" IF errcode = 3 THEN PRINT "Path or file not found" ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FFLUSH: Flush the ASILIB and DOS file buffers for specified file. Parameters: filehandle, errcode Flushes the ASILIB and DOS file output buffers associated with filehandle, returning with an MS-DOS error code if there was a problem. The file must have been opened with ASILIB's FOpen or FCreate subroutines. Flushing the file buffer protects against unintended system failures such as power outages. Any data written to the file before calling FFlush will be safely written to the disk. Example: f$ = "anyold.fil" call sub "fcreate", f$, handle, errcode REM program writes data to the file . . . call sub "fflush", handle, errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FGET: read data from a file opened by FOPEN Parameters: handle, datasegment, dataoffset, databytes, errcode FGET reads from the current file pointer and copies the data to datasegment:dataoffset in RAM. Databytes may be as large as 65535, but if it's greater than 32767 you must use a long integer (databytes&) to represent the number. Note that long integers require ASIC's extended math option. The data segment may either be the segment address returned by ASILIB's AllocDOS or FLoad subroutines, or for data initilaized by ASIC, the segment address may be found with ASILIB's ASICDS subroutine. Example: REM read 100 bytes from "anyold.dat" and copy to a(1) through a(50) REM note that a() is a normal integer array, 2 bytes per array element dim a(1000) accessmode=0 call sub "fopen", "anold.dat",accessmode,handle,errcode REM check for FOPEN errors if errcode > 0 then . . . endif REM get a(1) address call sub "asicds",datasegment dataoffset=varptr(a(1)) call sub "fget",handle, datasegment, dataoffset, 100, errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FGETCHR: read next byte from a file opened by FOPEN Parameters: handle, byte, errcode FGETCHR reads one byte (character) from the current file pointer. Example: REM read the first byte from "anyold.dat" & call it I. accessmode=0 call sub "fopen", "anyold.dat",accessmode,handle,errcode REM check for FOPEN errors if errcode > 0 then . . . endif call sub "fgetchr",handle, I, errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FGETPOS: Get file pointer position. Parameters: handle, pos&, errcode Returns position pos& of the DOS file pointer for the file associated with handle. Errcode = 0 if no error. Assumes the file was opened with FOPEN or FCREATE. Requires ASIC's extended math option. Example: REM determine where the file pointer is for file associated with handle call sub "fgetpos", handle, pos&, errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FGETSTR: read an ASCII string from a file buffer Parameters: file handle, inputstring$, errcode Given a valid file handle, FGETSTR will read the next string from the associated disk file. Strings may be terminated with either &hex0D or &hex0D+&hex0A. After reading each string, FGetStr positions the buffer pointer to read the next string. String length should be less than the buffer size. See FOPEN. If you try to read beyond the end of the file, errcode = 255. Restrictions: ASIC strings are limited to 80 characters, but you may use an array of integers as your string space if you need longer strings. ASILIB will not care whether you use an ASIC string or an array of integers; ASIC DOES care. Example: REM I want to read a text file and print it on the screen REM I used this program to test FGETSTR. REM This is an example of using an array of integers instead of REM an ASIC string. In this case each string in the input file REM may be as long as (1000*2) characters. dim a(1000) File$ = "common.inc" REM read-only access mode = 0 call sub "fopen", file$, mode, handle, errcode if errcode > 0 then print errcode end endif for i=0 to 49 j=i+1 call sub "fgetstr",handle,a(1),errcode if errcode = 255 then endoffile: call sub "tprintce",a(1),j,1,23 next i endoffile: call sub "tprintce","here's the end",j,1,30 call sub "fclose",handle,errcode call sub "getkey",keycode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FLOAD: Read a file, loading into far memory Parameters: filename$, fseg, bytes&, errcode FLoad reads a specified file (filename$) into far memory, returning the segment address (fseg) of the memory block where the file was loaded, as well as the size of the file (bytes&). If an error occurs when reading the file, errcode is an MS-DOS error code and both fseg and bytes& are invalid. If no error occurred, errcode = 0. To release the far memory allocated by this function, use FreeDOS. See DATA.DOC. The complete segment:offset address of the memory block is fseg:0. Note that FLoad requires ASIC's extended math option. Example: filename$ = "\ramfont\italics.fnt" call sub "fload", filename$, fseg, bytes&, errcode if errcode > 0 then REM error handling code . . . ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FOPEN: Open an existing file for buffered input or output Parameters: file$, mode, handle, errcode File$ is the name of the file you want opened. Mode is the access mode: 0 = read only 1 = write only 2 = read/write access Handle is the file handle returned by FOPEN for later access to the file. FOPEN returns a non-zero MS-DOS error code in errcode if someting went wrong. When a file is opened by FOpen, the MS-DOS file pointer is positioned at the start of the file. Use FSEEK to position the pointer at the end of the file, for appending the file. Example: File$ = "anyold.fil" REM read-only access mode = 0 call sub "fopen", file$, mode, handle, errcode REM check for errors ... IF errcode > 0 THEN ... ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FPUT: write specified data to output file buffer Parameters: handle, dataseg, dataoffset, bytes, errcode Handle is the file handle returned by ASILIB's FOPEN or FCREATE subroutines. Dataseg is the segment address of the data you want to write to the file. Dataoffset is the offset portion of the data's address. Bytes is the number of bytes of data you want written, and errcode is an MS-DOS error code. Errcode = 0 if there were no problems. The data segment may either be the segment address returned by ASILIB's AllocDOS or FLoad subroutines, or for data initilaized by ASIC, the segment address may be found with ASILIB's ASICDS subroutine. Restrictions: Limited to 32767 bytes per call. You may call FPUT more than one time if you have more data to write. Example: REM I want to save a text-mode screen as a disk file REM I'll use FCREATE to open the file and FPUT to write the screen REM to the file. For this example, I'll assume the screen is 25 rows REM and 80 columns and is color. file$ = "screen.dat" call sub "fcreate", file$, handle, errcode if errcode = 0 then call sub "fput", handle, &hexB800, 0, 4000, errcode endif ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FPUTCHR: write one byte to output file buffer Parameters: handle, byte, errcode Handle is the file handle returned by ASILIB's FOPEN or FCREATE subroutines. Byte is the byte you want to write to the output buffer, and errcode is an MS-DOS error code. Errcode = 0 if there were no problems. Example: call sub "fcreate", file$, handle, errcode if errcode = 0 then call sub "fputchr", handle, byte, errcode endif ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FPUTCRLF: add carriage return/line feed bytes to a file Parameters: handle, errcode Handle is a handle returned by FOPEN or FCREATE; if opened by FOPEN, the file must have been opened with Write or Read/Write access. Errcode is returned by FPUTCRLF to the calling program; if errcode = 0, no error was detected, otherwise, errcode is an MS-DOS error code. The carriage return/line feed pair of bytes is the standard DOS file "next line" signal; use FPUTCRLF after calling FPUTSTR if you want the next FPUTSTR to be written on the next line. Example: REM I'm adding two lines to a file string1 = "This is the first line" string2 = "This is the second line" call sub "fputstr", handle, string1, errcode call sub "fputcrlf", handle, errcode call sub "fputstr", handle, string2, errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FPUTSTR: write a string to output file buffer Parameters: handle, outputstring$, errcode Outputstring$ is the string you want written to the file. Handle is the file handle returned to the calling program by FOPEN or FCREATE. Errcode is an MS-DOS error code returned by FPUTSTR if something went wrong. If no error, errcode = 0. Restrictions: FPUTSTR does not add a CF/LF to the end of the string. See FPUTCRLF. Example: REM write outputstring$ to the output file and add a carriage return/ REM line feed pair to the end of the string. call sub "fputstr", handle, outputstring$, errcode call sub "fputcrlf", handle, errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FSEEK: Move DOS file pointer forward or backward in file Parameters: handle, offset&, method, errcode Moves the file pointer from its present position forward or backward in the file. The file must have been opened by FOpen or FCreate. Offset& is the number of bytes to move the pointer. Errcode is an MS-DOS error code. Note that FSEEK requires ASIC's extended math option. The method parameter is: 0 if offset& is absoute offset from start of file 1 if offset& is signed offset from current file pointer 2 if offset& is signed offset from end of file Example: REM I want to skip forward 200 bytes offset& = 200& method=1 call sub "fseek", handle, offset&, method, errcode ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ FSIZE: Determine size of file opened by FOPEN Parameters: handle, filesize&, errcode Handle is a valid handle returned by ASILIB's FOPEN subroutine. Filesize& is the size of the file, returned by FSize. Errcode is an MS-DOS error code indicating any problems. If errcode = 0, no error. FSize requires ASIC's extended math option. Example: call sub "fopen", (file$, mode, handle, errcode) if errcode > 0 then . . . REM error control stuff call sub "fsize", (handle, filesize&, errcode) if errcode > 0 then . . . REM more error control stuff