home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / GLEN / QLIB43.ZIP / DISK.DOC < prev    next >
Text File  |  1990-03-16  |  18KB  |  508 lines
  1.     DISK / FILE routines look for specified files on your disk, or report
  2.     disk status.  Several QLIB disk/file subroutines return the following
  3.     MS-DOS error codes:
  4.  
  5.         oops% = 2          file not found
  6.         oops% = 3          path not found
  7.         oops% = 4          too many open files
  8.         oops% = 5          access denied (file may be read-only
  9.                                            or a subdirectory)
  10.  
  11.     BIOS error codes, returned by DriveReady, are:
  12.  
  13.         oops% = 2          disk not readable (not formatted, or wrong type)
  14.         oops% = 128        drive not ready
  15.  
  16.  
  17.     File attributes may be combined.  Each bit of the file attribute
  18.     means:
  19.  
  20.         0 = normal files
  21.         1 = read-only
  22.         2 = hidden files
  23.         4 = system files
  24.         8 = volume label (only one per disk - may not be
  25.                           reliable)
  26.        16 = subdirectories
  27.        32 = archive bit set
  28.  
  29.      Thus a file attribute of 17 is a hidden subdirectory (16 + 1)
  30.  
  31.  
  32.      Subroutine: CopyFile(FromFile$, ToFile$, oops%)
  33.  
  34.           Copies a file from FromFile$ to ToFile$, and returns an error
  35.      code if something went wrong.  FromFile$ and ToFile$ may not include
  36.      any wildcard characters (such as * and ?).  CopyFile will destroy any
  37.      previously-existing file named ToFile$ before copying the file.
  38.      Oops% = -1 if an error in the "To" file was encountered; other error
  39.      codes apply to the "From" file.
  40.  
  41.      Example:
  42.           FromFile$ = "b:\qlib.lib"
  43.           ToFile$ = "c:\qb4\qlib.lib"
  44.           CALL CopyFile(FromFile$, ToFile$, oops%)
  45.  
  46.  
  47.  
  48.      Subroutine: DriveReady(drv$, oops%)
  49.  
  50.           DriveReady is used to determine if a floppy disk drive has a usable
  51.      disk and is ready for use.  DriveReady returns BIOS error codes, or
  52.      oops% = 0 if the drive is ready.  Oops% = -1 if drv$ is an invalid
  53.      drive specification.
  54.  
  55.      Example:
  56.           drv$ = "a:"
  57.           CALL DriveReady(drv$, oops)
  58.           IF oops% <> 0 THEN PRINT "Drive " + drv$ + "not ready or bad disk"
  59.  
  60.  
  61.  
  62.      Subroutine: DriveSpace(drv$, total&, free&, oops%)
  63.  
  64.           Returns the amount of total and free space left on a given disk
  65.      drive.  The drive string may be any legal disk drive, or "@" (AT sign)
  66.      for the default drive, and must be at least one character long.  An
  67.      illegal drive or other error will cause oops% to be returned as -1.
  68.      Note that total& and free& are LONG integers.  See "QLIB and QB3" in
  69.      APPENDIX.DOC to use this subroutine.  Works with logical devices up
  70.      to 2,147 Megabytes.
  71.  
  72.      Example:
  73.           drv$="C:"
  74.            .
  75.            .
  76.           CALL DriveSpace(drv$, total&, free&, oops%)
  77.           IF oops% = -1 THEN
  78.                   PRINT "Invalid drive specification"
  79.                   ELSE
  80.                   PRINT "Free space on drive "; drv$; " is"; free&; "bytes."
  81.                   PRINT "Total space on drive "; drv$; " is"; total&; "bytes."
  82.           END IF
  83.  
  84.  
  85.  
  86.      Subroutine: Exist(filename$, oops%)
  87.  
  88.           Tells you if a given file already exists.  Returns an error code
  89.      if it doesn't, or -1 if it does.  Requires an ASCIIZ filename without      
  90.      wildcards.
  91.  
  92.      Example:
  93.          filename$="TEST.TXT" + CHR$(0)
  94.       CALL Exist(filename$, oops%)
  95.          IF oops% = -1 THEN PRINT "File already exists"
  96.          IF oops% = 0 THEN PRINT "Path exists"
  97.                                   ' Filename$ = "d:\path" + CHR$(0)
  98.          IF oops% = 2 THEN PRINT "Path found, file not found"
  99.          IF oops% = 3 THEN PRINT "Path or file not found"
  100.  
  101. QLIB's file Input/Output subroutines provide fast, flexible file handling,
  102. replacing QB's clumsy functions.  Below is a summary of QLIB's file I/O
  103. subroutines:
  104.  
  105.      FileOpen  Open a file for input, output or random access
  106.      FileCreate     Make a new file and open it for I/O
  107.      FileClose Close a file opened by FileOpen
  108.      FileRead  Read from a file opened by FileOpen directly
  109.                to an array
  110.      FileWrite Write data to a file directly from an array
  111.      FileBegin Reset the MS-DOS file pointer to the beginning of
  112.                the file
  113.      FileEnd   Sets the MS-DOS file pointer to end of the file,
  114.                to append data to the file
  115.      FileSetPTR     sets the file pointer for an open file to a specified
  116.                byte position in the file
  117.      FileMovPTR     moves the file pointer forward or backward in the file
  118.  
  119. QLIB's file I/O subroutines return an error code (oops%) which is zero if
  120. no error occurred, or returns an MS-DOS error code if something went wrong.
  121.  
  122.  
  123.  
  124.      Subroutine: FileBegin(handle%, oops%)
  125.  
  126.       Sets the MS-DOS file pointer to the beginning of a file opened by
  127.      FileOpen. Handle% is the file handle returned by FileOpen.
  128.  
  129.      Example:
  130.       CALL FileBegin(handle%, oops%)
  131.  
  132.  
  133.  
  134.      Subroutine: FileClose(handle%, oops%)
  135.  
  136.       Closes a file opened by FileOpen.  Handle% is the file handle returned
  137.      by FileOpen.  Returns an MS-DOS error code.
  138.  
  139.      Example:
  140.       CALL FileClose(handle%, oops%)
  141.  
  142.  
  143.  
  144.      Subroutine: FileCreate(file$, handle%, oops%)
  145.  
  146.        Creates a new file and returns a handle for subsequent writing.
  147.      If the file already exists, it will be truncated to zero bytes by
  148.      FileCreate.
  149.  
  150.      Example:
  151.        file$ = "anyold.dat" +CHR$(0)
  152.        CALL FileOpen(file$, handle%, oops%)
  153.                       ' first try to open an existing file
  154.        IF oops% = 2 THEN
  155.            CALL FileCreate(file$, handle%, oops%)
  156.                       ' create a new file if "anyold.dat"
  157.                       ' is not found
  158.  
  159.  
  160.  
  161.      Subroutine: FileEnd(handle%, oops%)
  162.  
  163.       Sets the MS-DOS file pointer at the end of the file.  Subsequent
  164.      FileWrite calls will add new data to the end of the file.
  165.  
  166.      Example:
  167.        file$ = "anyfile.dat" + CHR$(0)
  168.        acode = 1              ' I want to add new data to this file
  169.        CALL FileOpen(a$, acode%, handle%, oops%)
  170.        CALL FileEnd(handle%, oops%)
  171.  
  172.  
  173.      Subroutine: FileMovPTR(handle%, bytes0&, bytes1&, oops) (QB4+)
  174.  
  175.        Moves the file pointer from its present position forward or
  176.      backward in the file.  The file must have been opened by FileOpen
  177.      or FileCreate.  Bytes0& is the number of bytes to move the pointer,
  178.      and bytes1& is the resulting pointer location in the file.  Note that
  179.      bytes0& and bytes1& are LONG integers.
  180.  
  181.      Example:
  182.       CALL FileMovPTR(handle%, bytes0&, bytes1&, oops%)
  183.  
  184.  
  185.  
  186.      Subroutine: FileOpen(file$, acode%, handle%, oops%)
  187.  
  188.       FileOpen opens an existing file for input, output or random I/O.
  189.      If acode% = 0, access is input, if acode% = 1, access is output, and if
  190.      acode% = 2 then access may be either input or output.  File$ is an
  191.      ASCIIZ (zero-terminated) file name.  Handle% is the file handle returned
  192.      by FileOpen for use with subsequent input to or output from the file.
  193.      When a file is opened by FileOpen, the MS-DOS file pointer is positioned
  194.      at the start of the file.     Use FileEnd to position the pointer at the
  195.      end of the file, for appending the file.
  196.  
  197.      Example:
  198.         File$ = "anyold.fil" + CHR$(0)
  199.         acode% = 2            ' I want to both read from the file
  200.                          ' and write new data to the file
  201.                          ' without closing and re-opening it
  202.         CALL FileOpen(file$, acode%, handle%, oops%)
  203.  
  204.  
  205.      Subroutine: FileRead(handle%, aSEG%, aPTR%, bytes0%, bytes1%, oops%)
  206.  
  207.       Reads bytes0% bytes of data from a file opened by FileOpen and
  208.      loads the data into an array beginning at the address pointed to
  209.      by aSEG% and aPTR%.  bytes1% is the number of bytes actually read
  210.      into the array.  Unless FileRead encounters the end of the file,
  211.      bytes1% should be the same as bytes0%.
  212.  
  213.      Example:
  214.       DIM a(99)          ' an integer array of 100 elements
  215.       bytes0% = 200      ' each integer is 2 bytes
  216.       file$ = "anyold.dat" + CHR$(0)
  217.       CALL FileOpen(file$, handle%, oops%)
  218.       aSEG% = VARSEG(a(0))    ' start at beginning of file
  219.       aPTR% = VARPTR(a(0))
  220.       CALL FileRead(handle%, aSEG%, aPTR%, bytes0%, bytes1%, oops%)
  221.  
  222.  
  223.  
  224.      Subroutine: FileSetPTR(handle%, bytes0&, bytes1&, oops%)
  225.  
  226.       Sets the current location of the file pointer for a file opened
  227.      by FileOpen or FileCreate.  Bytes0& is the desired position and bytes1&
  228.      is returned by FileSetPTR.  Note that bytes0& and bytes1& and LONG
  229.      integers.
  230.  
  231.      Example:
  232.       CALL FileSetPTR(handle%, bytes0&, bytes1&, oops%)
  233.  
  234.  
  235.  
  236.      Subroutine: FileWrite(handle%, aSEG%, aPTR%, bytes0%, bytes1%, oops%)
  237.  
  238.       Similar to FileRead, above, but writes to the file from the array.
  239.  
  240.      Subroutine: GetDRIVE(drv%)
  241.  
  242.          Returns the ASCII character code of the default drive.
  243.  
  244.      Example:
  245.          CALL GetDRIVE(drv%)
  246.          drive$ = CHR$(drv%)+":"
  247.          PRINT "The default drive is "; drive$
  248.  
  249.  
  250.  
  251.      Subroutine: GetSUB(d$, sub$, sublen%)
  252.  
  253.          Gets the current directory on disk d$.  The subdirectory string must
  254.      be 64 characters long.  Note that the returned string will NOT be started
  255.      by a backslash "\" character - you should add one if appropriate.  To get
  256.      the current directory on the default drive, set d$ = "@".  If d$ specifies
  257.      an invalid drive, sublen% will be returned -1.  NOTE: d$ must be at least
  258.      one character long.
  259.  
  260.      Example:
  261.          sub$ = SPACE$(64)
  262.          d$ = "C"
  263.          CALL GetSUB(d$, sub$, sublen%)
  264.          IF sublen% = -1 THEN
  265.               PRINT d$ + " is not a valid drive"
  266.               ELSE
  267.               sub$ = "\" + LEFT$(sub$, sublen%)
  268.          END IF
  269.  
  270.  
  271.  
  272.  
  273.     Subroutine: FindFirstMatch(file$, fAttr%, oops%)
  274.     Subroutine: FindNextMatch(oops%)
  275.     Subroutine: FindFileName(filename$, flen%)
  276.     Subroutine: FindFileAttr(fAttr%)
  277.     Subroutine: FindFileDate(month%, day%, year%)
  278.     Subroutine: FindFileTime(hour%, min%, sec%)
  279.     Subroutine: FindFileSize(lowword%, highword%)
  280.  
  281.          This group of subroutines may be used to search for files which match
  282.     a specified file name.  The specified file name may include drive and
  283.     path, and may also include the * and ? wildcards.  These subroutines may
  284.     be used to duplicate the DOS DIR command.
  285.  
  286.     A search attribute (fAttr%) may also be specified.  File attributes are
  287.     listed on the first page of this file.
  288.  
  289.     fAttr% may include more than one type of file.  For example, if
  290.     fAttr% = 2 + 8, FindFirst/NextMatch will search for hidden and system
  291.     files as well as normal files (normal files will always be found).
  292.     The actual file attribute of the matched file will be returned by
  293.     FindFileAttr.  Files returned may have a combination of attributes; for
  294.     example, if a file attribute returned by FindFileAttr is 18 ( = 2 + 16),
  295.     this file is a hidden directory.
  296.  
  297.  
  298.     The file size returned by FindFileSize is in two parts.  Use the following
  299.     code to determine the file size:
  300.  
  301.     CALL FindFileSize(lowword%, highword%)  ' assumes file matched with
  302.                                             ' FindFirst/NextMatch, oops% <> 0
  303. (QB4+)
  304.     size& = CLNG(lowword%)
  305.     IF lowword% < 0 THEN size& = size& + 65536&
  306.     size& = size& + highword% * 65536&
  307.  
  308. (QB2, QB3)
  309.     size# = CDBL(lowword%)
  310.     IF lowword% < 0 THEN size# = size# + 65536#
  311.     size# = size# + highword% * 65536#
  312.  
  313.     see examples on the next page
  314.  
  315.  
  316.     Example 1:
  317.          filename$ = SPACE$(12)             ' filename$ must be initialized
  318.                                             ' as a 12-byte (or longer) string
  319.                                             ' or the namelen% will be returned
  320.                                             ' as -1
  321.          FileSpec$ = "\qb4\*.bas"+CHR$(0)   ' FileSpec$ must end in CHR$(0)
  322.          fAttr% = 0                         ' search only for normal files
  323.          CALL FindFirstMatch(FileSpec$, fAttr%, oops%)
  324.          IF oops% = -1 THEN PRINT "FileSpec$ is a nul string"
  325.          IF oops% THEN PRINT "No matching files"
  326.          WHILE oops% = 0
  327.               CALL FindFileName(filename$, namelen%)
  328.               IF namelen% = -1 THEN PRINT "filename$ shorter than 12 bytes"
  329.               PRINT LEFT$(filename$, namelen%)
  330.               CALL FindNextMatch(oops%)
  331.          WEND
  332.          REM  FindFileName, FindFileAttr, FindFileDate, FindFileTime and
  333.          REM  FindFileSize will return usable results only after a successful
  334.          REM  (oops% = 0) call to FindFirstMatch or FindNextMatch.
  335.  
  336.     Example 2:
  337.          REM  In this example, we will print all subdirectories one
  338.          REM  level down from the root directory
  339.          fAttr% = 16
  340.          FileSpec$ = "\*.*"+CHR$(0)
  341.          CALL FindFirstMatch(FileSpec$, fAttr%, oops%)
  342.          IF oops% THEN PRINT "No files or subdirectories"
  343.          WHILE oops% = 0
  344.               CALL FindFileAttr(fAttr%)
  345.               IF fAttr% AND 16 THEN
  346.                    CALL FindFileName(filename$, namelen%)
  347.                    PRINT LEFT$(filename$, namelen%)
  348.               END IF
  349.               CALL FindNextMatch(oops%)
  350.          WEND
  351.  
  352.  
  353.  
  354.     Subroutine: GetFileAttr(file$ + CHR$(0), attr%, oops%)
  355.  
  356.          Returns the attribute of file$.  File$ must be an ASCIIZ
  357.     (zero-terminated) string without the * or ? wildcards.  File
  358.     attributes are listed on the first page of this file.  Oops%
  359.     is an MS-DOS error code if something went wrong, or oops% = -1
  360.     if no problems were encountered.
  361.  
  362.     Example:
  363.          file$ = "c:\qb4\qlib.lib" + CHR$(0)
  364.          CALL GetFileAttr(file$, attr%, oops%)
  365.  
  366.  
  367.  
  368.     Subroutine: KillFile(file$ + CHR$(0), oops%)
  369.  
  370.          KillFile deletes file$ from a disk with error trapping, avoiding
  371.     QB's ON ERROR.  Note that the file name string passed to the subroutine
  372.     is an ASCIIZ (zero-terminated) string.
  373.  
  374.     Oops% codes are:
  375.  
  376.         0 = no error
  377.         1 = file name is a nul string
  378.         2 = file not found
  379.         3 = path not found
  380.         5 = file is read-only
  381.        19 = disk is write-protected
  382.  
  383.     Example:
  384.          file$ = "oldfile.dat" + CHR$(0)
  385.          CALL KillFile(file$, oops%)
  386.  
  387.  
  388.  
  389.     Subroutine: KillSUB(sub$ + CHR$(0), oops%)
  390.  
  391.          KillSUB deletes subdirectory sub$ from a disk with error trapping,
  392.     avoiding QB's ON ERROR.  Note that the directory name string passed to
  393.     the subroutine is an ASCIIZ (zero-terminated) string.  The subdirectory
  394.     must be empty before it is deleted.
  395.  
  396.     Oops% codes are:
  397.  
  398.         0 = no error
  399.         1 = subdirectory name is a nul string
  400.         3 = path not found
  401.         5 = usually means files are still in the directory, or it may
  402.             mean the subdirectory is read-only
  403.        19 = disk is write-protected
  404.  
  405.     Example:
  406.          sub$ = "C:\123" + CHR$(0)
  407.          CALL KillSUB(sub$, oops%)
  408.  
  409.  
  410.  
  411.     Subroutine: MakeSUB(sub$ + CHR$(0), oops)
  412.  
  413.       Creates a new subdirectory.  Oops% is an MS-DOS error code returned
  414.     by MakeSUB.  If oops% = 0 then no error was detected.
  415.  
  416.     Example:
  417.       sub$ = "\qb4\qlib"     ' make a new subdirectory for QLIB
  418.       CALL MakeSUB(sub$ + CHR$(0), oops%)
  419.  
  420.  
  421.  
  422.     Subroutine: Rename(old$, new$, oops)
  423.  
  424.          Changes filename old$ to new$, returning an MS-DOS error code.
  425.     Similar to QuickBASIC's NAME function, but does not require ON ERROR
  426.     to trap errors.  Note that both old$ and new$ must be zero-terminated
  427.     ASCIIZ strings.  You may use Rename to move a file from one directory
  428.     to another on the same disk.
  429.  
  430.     Example:
  431.          old$ = "demo.bas" + CHR$(0)
  432.          new$ = "demo.bak" + CHR$(0)
  433.          CALL Rename(old$, new$, oops)
  434.  
  435.  
  436.  
  437.     Subroutine: SetDRIVE(d$)
  438.  
  439.          Sets d$ as the default drive.  D$ may be any valid disk drive or 
  440.     other logical device (such as a RAMdisk).
  441.  
  442.     Example:
  443.          d$ = "a:"           ' the drive specifier d$ may be upper or lower
  444.                              ' case and need not include the colon.
  445.          CALL SetDRIVE(d$)   ' drive A: is now the default drive
  446.  
  447.  
  448.  
  449.     Subroutine: SetFileAttr(file$ + CHR$(0), attr%, oops%)
  450.  
  451.          Changes the file attribute of file$.  File attributes are
  452.     described on the first page of this file.  Oops% returned by this
  453.     subroutine is an MS-DOS error code (see first page of this file).
  454.     If all O.K. then oops% = -1.
  455.  
  456.     Example:  I want to make my QLIB.LIB file read-only
  457.  
  458.          REM  I start by getting the present attribute
  459.          file$ = "QLIB.LIB" + CHR$(0)
  460.          CALL GetFileAttr(file$, attr%, oops%)
  461.          IF oops% <> -1 THEN
  462.                 REM  Uh oh, something went wrong
  463.                   .
  464.                   .
  465.                   .
  466.          END IF
  467.  
  468.          REM  now I'll add the Read-only bit to the attribute
  469.          attr% = attr% OR 1
  470.          CALL SetFileAttr(file$, attr%, oops%)
  471.  
  472.  
  473.  
  474.      Subroutine: SetFileDate(file$, month%, day%, year%, hour%, min%, sec%)
  475.  
  476.           Sets file time/date stamp.  The filename must be an ASCIIZ (zero-
  477.      terminated) string.  The year may be either a four digit or two digit
  478.      number  (e.g., either 1986 or just 86).  DOS will round the seconds
  479.      value off to the next lower even number.  If there is a problem with
  480.      the  filename, or if the file is read-only, the month will be returned
  481.      as -1.  Note that midnight is 24:00.  If hour%, minute% and second% are
  482.      all 0, then the file's time will not be displayed in a directory list.
  483.  
  484.      Example:
  485.           file$ = "anyfile.dat" + CHR$(0)
  486.           CALL SetFileDate(file$, month%, day%, year%, hour%, min%, sec%)
  487.  
  488.  
  489.  
  490.  
  491.     Subroutine: SetSUB(sub$ + CHR$(0), oops%)
  492.  
  493.          Changes the default subdirectory to sub$.  Oops% is an error
  494.     code returned to QuickBASIC.
  495.  
  496.     SetSUB's error codes:
  497.  
  498.          oops% = 0         no error
  499.                  1         subdirectory name is a nul string
  500.                  3         path not found
  501.  
  502.     Note that sub$ is an ASCIIZ (zero-terminated) string.
  503.  
  504.     Example:
  505.          directory$ = "\qb4\library" + CHR$(0)
  506.          CALL SetSUB(directory$, oops%)
  507.  
  508.