home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / asmutil / asmlib37.zip / DISK.DOC < prev    next >
Text File  |  1993-04-14  |  26KB  |  891 lines

  1.  
  2. ***************************** DISK & FILE *******************************
  3.  
  4. ASMLIB disk & file subroutines (C) Copyright 1992 - 1993 Douglas Herr
  5. All rights reserved
  6.  
  7. The MS-DOS file attribute byte tells you whether a file is read-only,
  8. system, a subdirectory, or may provide other information.  File attribute
  9. bits may be combined.  Each bit of the file attribute means:
  10.  
  11.         0 = normal files
  12.         1 = read-only
  13.         2 = hidden files
  14.         4 = system files
  15.         8 = volume label (only one per disk)
  16.        16 = subdirectories
  17.        32 = archive bit set
  18.  
  19.    Thus a file with an attribute of 18 is a hidden subdirectory (16 OR 2)
  20.  
  21.  
  22.  
  23.                       ASMLIB buffered file I/O system
  24.  
  25.     Several ASMLIB subroutines are available for buffered file Input or
  26.     Output.  Files to be managed by the buffered I/O system must be opened
  27.     by FOPEN or FCREATE, and must be closed by FCLOSE.  Buffered file I/O
  28.     will be much faster than unbuffered.  ASMLIB's default buffer size is
  29.     4096 bytes; this can be changed by altering FBUFFER_SIZE in FOPEN.ASM
  30.     and re-assembling.  Up to 20 files can be managed by FOPEN; this can
  31.     be changed by altering NUMBER_OF_FILES in $handle.asm and reassembling.
  32.     All ASMLIB file buffer subroutines assume DS:@data.
  33.  
  34.     To use the ASMLIB buffered I/O system excess DOS memory must be
  35.     released.  See ENDPROG in SYSTEM.DOC.
  36.  
  37.     Subroutines: FOPEN        open file & initialize buffer
  38.                  FCREATE      create file & initialize buffer
  39.                  FCLOSE       flush & close output buffer; close file
  40.                  FSEEK        move file pointer & update buffer
  41.                  FGETSTR      read a string from buffer
  42.                  FGETCHR      read a character from buffer
  43.                  FGET         read specified number of bytes from buffer
  44.                  FPUTSTR      write string to buffer
  45.                  FPUTCRLF     write CR+LF to buffer
  46.                  FPUTCHR      write character to buffer
  47.                  FPUT         write specified number of bytes to buffer
  48.  
  49.  
  50. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  51.  
  52. DISKFREE:    determines free disk space
  53. Source:      diskfree.asm
  54.  
  55. Call with:   DL = drive number (drive A: = 0, default drive = -1)
  56. Returns:     if CF = 0, DX:AX = free disk space
  57.              if CF = 1, AX = DOS error code
  58.               DiskFree does not trap "drive not ready" errors
  59. Uses:        DX, AX, flags
  60. Supports:    all DOS drives
  61. Example:
  62.  
  63. include asm.inc
  64. public  example_code
  65.  
  66. .code
  67. example_code   proc
  68.         mov    dl,0
  69.         call    diskfree
  70.         jc      disk_error
  71.  
  72.  
  73. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  74.  
  75. DISKWP:      determines if a floppy disk is write-protected
  76. Source:      diskwp.asm
  77.  
  78. Call with:   DL = floppy disk number (drive A: = 0)
  79. Returns:     AL = BIOS error code
  80.                 0 = no error
  81.                 1 = invalid disk number
  82.                 3 = disk is write-protected
  83.               128 = drive not ready
  84. Uses:        AX, flags
  85. Supports:    physical drives A: and B:
  86. Example:
  87.  
  88. include asm.inc
  89.  
  90. public  mycode
  91. extrn   diskwp:proc
  92.  
  93. .code
  94. diskwp  proc
  95.         .
  96.         .
  97.         .
  98.         mov     dl,1        ; drive B:
  99.         call    diskwp      ; can I write to this disk?
  100.         or      al,al
  101.         jz      no_problem
  102.  
  103.  
  104. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  105.  
  106. DOTBAK:      changes the file extension of an existing file to .BAK
  107. Source:      dotbak.asm (strrchr.asm)
  108.  
  109. Call with:   DS:[SI] = address of a ASCIIZ valid filename
  110.              assumes DS:@data
  111.              dotbak deletes a previous .BAK file of this name and
  112.              renames the input filename.ext to filename.bak.
  113. Returns:     if CF = 0, no error
  114.              if CF = 1, AL = DOS error code.  If AL = 5, the previous
  115.              .BAK filename is probably read-only.  All other errors refer
  116.              to the name change operation.
  117. Uses:        AX, flags
  118. Example:
  119.  
  120. extrn  dotbak:proc
  121.  
  122. .data
  123.  
  124. disk_doc  db 'DISK.DOC',0
  125.  
  126. .code
  127. ; program fragment assumes DS:@data
  128.              .
  129.              .
  130.              .
  131.              mov   si,offset DGROUP:disk_doc
  132.              call  dotbak
  133.  
  134.  
  135. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  136.  
  137. FCLOSE:      close a file managed by ASMLIB's buffered file I/O system
  138. Source:      fopen.asm ($handle.asm, dosalloc.asm)
  139.  
  140. Call with:   BX = file handle
  141.              The file must have been opened by FOPEN or FCREATE;  If the
  142.              file is not read-only, the output buffer will be written to
  143.              the disk file before closing the file.
  144. Returns:     if CF = 0, no error
  145.              if CF = 1, AX = error code
  146. Uses:        AX, flags
  147. Example:     see FOPEN
  148.  
  149.  
  150.  
  151.  
  152. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  153.  
  154. FCOPY:       copy a file
  155. FCOPYM:      copy a file using supplied memory buffer
  156. Source:      fcopy.asm
  157.  
  158. Call with:   DS:[SI] = address of source filename
  159.              ES:[DI] = address of destination filename
  160.              Both filenames must be ASCIIZ strings.  Drive and path need
  161.              not be fully specified; filenames may not include * or ?
  162.              wildcards.
  163.              FCOPY only: Requires 64k DOS memory available
  164.              FCOPYM only: AX = segment address of 64k buffer
  165. Returns:     if CF = 0, no problem
  166.              if CF = 1, AX = DOS error code (AX = -1 if insufficient memory)
  167. Uses:        AX, CF
  168. Example:
  169.  
  170. .data
  171.         db 'b:'
  172. source  db 'asmlib.lib',0         ; copy the library to b:
  173.  
  174. extrn   fcopy:proc
  175. .code
  176. ; program fragment assumes DS:@data
  177.         .
  178.         .
  179.         push    ds
  180.         pop     es
  181.         assume es:@data
  182.         lea     si,source
  183.         mov     di,si                ; DI also points to source
  184.         sub     di,2                 ; back the pointer to the 'B:'
  185.         call    fcopy
  186.         jc      oops
  187.  
  188.  
  189.  
  190. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  191.  
  192. FCOUNT:      counts the number of files matching an ASCIIZ filespec string.
  193.              The filespec string may include the '*' and '?' wildcards.
  194. Source:      fcount.asm
  195.  
  196. Call with:   DS:[DX] pointing to filespec string
  197.              CX = file attributes
  198.              assumes DS:@data
  199. Returns:     AX = number of files matching the filespec string
  200. Uses:        AX, all other registers and flags are saved
  201. Example:
  202.  
  203. .code
  204. ; program fragment assumes DS:@data
  205.         .
  206.         .
  207.         .
  208.         lea    dx,filespec      ; address of filespec string
  209.         xor    cx,cx            ; normal files only
  210.         call   fcount
  211.  
  212.  
  213. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  214.  
  215. FCREATE:     create new file and initialize output buffer
  216. Source:      fcreate.asm ($handle.asm, dosalloc.asm)
  217.  
  218. Call with:   DS:[DX] pointing to ASCIIZ filename
  219.              The file is created with write-only access.  If a file with
  220.              the same name already exists, it is truncated to zero
  221.              length by FCREATE.
  222. Returns:     if CF = 0, AX = file handle
  223.              if CF = 1, AX = error code
  224. Uses:        AX, flags
  225. Example:
  226.  
  227. include  asm.inc
  228.  
  229. public   myprog
  230. extrn    fcreate:proc
  231.  
  232. .data
  233. file_name   db 'ANYNEW.FIL',0
  234. file_handle dw 0
  235.  
  236. .code
  237. myprog   proc
  238. ; program fragment assumes DS:@data
  239.          .
  240.          .
  241.          .
  242.          lea   dx,file_name
  243.          call  fcreate
  244.          jc    something_went_wrong
  245.          mov   file_handle,ax ; save the handle
  246.          .
  247.          .
  248.          .
  249.  
  250.  
  251. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  252.  
  253. FEXIST:      determines if a file exists and can be opened with read access
  254. Source:      fexist.asm
  255.  
  256. Call with:   DS:[DX] pointing to ASCIIZ filename
  257. Returns:     if CF = 0, file exists
  258.              if CF = 1, AX = MS-DOS error code
  259. Uses:        AX, CF; all other flags and registers are saved
  260. Example:
  261.  
  262. include  asm.inc
  263.  
  264. extrn    fexist:proc
  265. .data
  266. filename db 'asmlib.doc',0
  267.  
  268. .code
  269. ; program fragment assumes DS:@data
  270.          .
  271.          .
  272.          .
  273.          lea   dx,filename
  274.          call  fexist
  275.          jnc   got_the_file      ; if CF = 0, go on
  276.          jmp   doserror          ; else go to error handling code
  277.  
  278.  
  279.  
  280. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  281.  
  282. FFLUSH:      flushes the ASMLIB and DOS output buffers for specified handle
  283. Source:      fflush.asm (fseek.asm, $handle.asm)
  284.  
  285. Call with:   BX = file handle
  286.              flushing the buffers guards against data loss in case of system
  287.              failure, such as power loss
  288. Returns:     if CF = 0, no error; function successful
  289.              if CF = 1, AX = DOS error code
  290. Uses:        AX, flags
  291. Example:
  292.  
  293. include asm.inc
  294.  
  295. extrn fflush:proc
  296.  
  297. .code
  298. ; program opens file & writes to file
  299.       .
  300.       .
  301.       .
  302. ; flush the buffers to disk
  303.       mov    bx,handle
  304.       call   fflush
  305.  
  306.  
  307.  
  308. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  309.  
  310. FGET:        read specified number of bytes from file buffer
  311. Source:      fget.asm ($handle.asm, $fget.asm)
  312.  
  313. Call with:   BX = file handle
  314.              CX = number of bytes requested (up to 4096 bytes)
  315. Returns:     if CF = 0, AX = number of bytes read
  316.                         ES:[BX] points to data in buffer
  317.              if CF = 1, AX = DOS error code
  318. Uses:        AX, BX, ES, flags
  319. Example:
  320.  
  321. include   asm.inc
  322.  
  323. extrn     fopen:proc, fget:proc
  324.  
  325. .data
  326. file_name   db 'asmlib.doc',0
  327. file_handle dw 0
  328.  
  329. .code
  330. ; program fragment assumes DS:@data
  331.           .
  332.           .
  333.           .
  334.           lea   dx,file_name
  335.           call  fopen
  336.           jc    fopen_problem
  337.           mov   file_handle,ax  ; save for later
  338.  
  339.           mov   bx,ax           ; file handle
  340.           mov   cx,8            ; I want 8 bytes
  341.           call  fget            ;  returned at ES:[BX]
  342.           jc    read_problem    ; uh oh, trouble ...
  343.           cmp   ax,cx           ; did I get what I wanted?
  344.           jne   not_enough
  345.           .
  346.           .
  347.  
  348.  
  349.  
  350.  
  351. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  352.  
  353. FGETCHR:     read a character from a file buffer
  354. Source:      fgetchr.asm ($handle.asm)
  355.  
  356. Call with:   BX = file handle
  357. Returns:     if CF = 0, AL = next character from file buffer
  358.              if CF = 1, AX = DOS error code
  359.                         AX = 0 if at end of file
  360. Uses:        AX, flags
  361. Example:
  362.  
  363. include   asm.inc
  364.  
  365. extrn     fopen:proc, fgetchr:proc
  366.  
  367. .data
  368. file_name   db 'asmlib.doc',0
  369. file_handle dw 0
  370.  
  371. .code
  372. ; program fragment assumes DS:@data
  373.           .
  374.           .
  375.           .
  376.           lea   dx,file_name
  377.           call  fopen
  378.           jc    fopen_problem
  379.           mov   file_handle,ax  ; save for later
  380.  
  381.           mov   bx,ax           ; file handle
  382.           call  fgetchr         ; character in AL
  383.           jc    read_problem
  384.  
  385.           .
  386.           .
  387.  
  388.  
  389.  
  390. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  391.  
  392. FGETSTR:     read an ASCII string from a file buffer
  393. Source:      fgetstr.asm ($handle.asm, $fget.asm)
  394.  
  395. Call with:   BX = file handle
  396.              ASCII strings may be terminated with either 0Dh or 0Dh+0Ah.
  397.              After reading each string, FGetStr positions the buffer pointer
  398.              to read the next string.  String length should be less than
  399.              the buffer size.  See FOPEN.
  400. Returns:     if CF = 0, ES:[BX] points to string in buffer
  401.                         CX = length of ASCII string
  402.                      if CX = byte length of buffer, string >= size of buffer
  403.              if CF = 1, AX = DOS error code
  404.                         AX = 0 if end of file
  405. Uses:        ES, BX, AX, CX, flags
  406. Example:
  407.  
  408. include   asm.inc
  409.  
  410. extrn     fopen:proc, fgetstr:proc
  411.  
  412. .data
  413. file_name   db 'asmlib.doc',0
  414. file_handle dw 0
  415.  
  416. .code
  417. ; program fragment assumes DS:@data
  418.           .
  419.           .
  420.           .
  421.           lea   dx,file_name
  422.           call  fopen
  423.           jc    fopen_problem
  424.           mov   file_handle,ax  ; save for later
  425.  
  426.           mov   bx,ax           ; file handle
  427.           call  fgetstr
  428.           jc    read_problem
  429.  
  430.           call  strndup         ; make a copy in near heap for later
  431.           .
  432.           .
  433.           .
  434.  
  435.  
  436.  
  437. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  438.  
  439. FILELIST:    creates a list of file names matching a filespec mask
  440. Source:      filelist.asm (fcount.asm, dosalloc.asm)
  441.  
  442. Call with:   DS:[SI] pointing to filespec mask
  443.              CX = file attribute mask
  444. Returns:     if CF = 0:
  445.                ES = base segment address of list buffer
  446.                AX = number of filenames in list
  447.                CX = list field width
  448.              if CF = 1, AX = MS-DOS error code
  449.              You should use DOS function 49h to release the file list
  450.              buffer when you're done with it.
  451. Uses:        AX, CX, ES, CF
  452. Example:
  453.  
  454. include asm.inc
  455.  
  456. public  myproc
  457.  
  458. .data
  459. filespec db '*.*',0
  460.  
  461. .code
  462. ; program fragment assumes DS:@data
  463.         .
  464.         .
  465.         .
  466.         lea    si,filespec
  467.         mov    cx,16            ; normal files and subdirectories
  468.         call   filelist
  469.         jc     cant_do_it       ; oops
  470.  
  471.  
  472.  
  473. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  474.  
  475. FINDDATE:    given a successful call to FindFirst or FindNext, returns
  476.              the file's date stamp
  477. Source:      findfile.asm
  478.  
  479. Call with:   DS:[BX] pointing to DTA buffer; assumes DS  @DATA
  480. Returns:     DX = month
  481.              AX = day
  482.              CX = year
  483. Uses:        AX, CX, DX, flags
  484. Example:
  485.  
  486. .code
  487. ; program fragment assumes DS:@data
  488.         .
  489.         .
  490.         .
  491.         lea    bx,filespec
  492.         mov    cx,0              ; normal files only
  493.         call   findfirst         ; find first matching file
  494.         jc     no_more_files
  495.         cmp    ax,-1
  496.         je     no_more_files
  497.         call   finddate
  498.  
  499.  
  500.  
  501. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  502.  
  503. FINDFIRST:   This subroutine, when used with FindNext, finds files on
  504.              a disk which match an ASCIIZ filespec string.  The filespec
  505.              string may contain the '*' and '?' wildcards.
  506. Source:      findfile.asm (heap.asm)
  507.  
  508. Call with:   DS:[BX] pointing to ASCIIZ filespec string; assumes DS:@data
  509.              CX = file attribute mask
  510.  
  511.              FindFirst allocates space for a local DTA buffer from the
  512.              near heap.  See FindNext; also see HINIT.
  513.  
  514. Returns:     AX = error code
  515.              -1 = insufficient memory in near heap (128 bytes required)
  516.              0 = no error
  517.              CF = 1 if no files match the filespec string
  518.              DS:[BX] -> DTA buffer if the subroutine is successful.  Do not
  519.              alter the 128 bytes in the DTA buffer.
  520.              The name of the file is an ASCIIZ string at 30[BX]
  521.              The file attribute is a byte at 21[BX]
  522.              The low word of the file's size is at 26[BX]
  523.              The high word of the file's size is at 28[BX]
  524. Uses:        AX, BX, flags
  525. Example:
  526.  
  527. .code
  528. ; program fragment assumes DS:@data
  529.      .
  530.      .
  531.      .
  532.      lea    bx,filespec
  533.      mov    cx,0              ; normal files only
  534.      call   findfirst         ; find first matching file
  535.      jc     no_more_files
  536.      cmp    ax,-1
  537.      je     no_memory         ; memory not available
  538.  
  539. ; print the filename on the screen
  540. tprint_next:
  541.      mov    si,bx
  542.      add    si,30             ; point to filename in DTA buffer
  543.      mov    dh,count          ; row value
  544.      mov    dl,0              ; column 0
  545.      mov    ah,12             ; color attribute - RED!
  546.      call   tprint            ; display the file name on the screen
  547.      inc    count             ; next filename on next row
  548.      call   findnext          ; any more matching filenames?
  549.      jnc    tprint_next
  550. no_more_files:
  551.  
  552. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  553.  
  554. FINDNEXT:    finds file matching search string; use after FindFirst.
  555.              used only after a successful call to FindFirst.
  556. Source:      findfile.asm (heap.asm)
  557.  
  558. Call with:   no parameters; assumes DS:@data
  559.  
  560.              FindNext de-allocates the DTA buffer space after the first
  561.              unsuccessful search for a matching file.
  562.  
  563. Returns:     DS:[BX] -> DTA buffer
  564.              CF = 1 if no more files match the filespec string.
  565. Uses:        BX, flags
  566. Example:     see FindFirst.
  567.  
  568.  
  569. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  570.  
  571. FINDTIME:    given a successful call to FindFirst or FindNext, returns
  572.              the file's time stamp
  573. Source:      findfile.asm
  574.  
  575. Call with:   DS:[BX] pointing to DTA buffer; assumes DS:@data
  576. Returns:     DX = hour
  577.              AX = minute
  578.              CX = second
  579. Uses:        AX, CX, DX, flags
  580. Example:     lea    bx,filespec
  581.              mov    cx,0              ; normal files only
  582.              call   findfirst         ; find first matching file
  583.              jc     no_more_files
  584.              cmp    ax,-1
  585.              je     no_more_files
  586.              call   findtime
  587.  
  588.  
  589.  
  590. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  591.  
  592. FLOAD:       read a file into far memory
  593. Source:      fload.asm (fsize.asm, allocdos.asm)
  594.  
  595. Call with:   DS:[DX] pointing to ASCIIZ filename
  596. Returns:     if CF = 0, BX = initial segment address of memory block
  597.                         DX:AX = bytes loaded from disk
  598.              if CF = 1, AX = DOS error code
  599. Uses:        AX, BX, DX, CF
  600. Example:
  601.  
  602. include asm.inc
  603.  
  604. public  test_fload
  605.  
  606. extrn   fload:proc
  607.  
  608. .data
  609. fileseg         dw 0
  610. fname           db 'filename.txt',0
  611. file_size       dw 0,0
  612.  
  613. .code
  614. test_fload      proc
  615. ; program fragment assumes DS:@data
  616.         .
  617.         .
  618.  
  619.         lea     dx,fname
  620.         call    fload           ; read file into DOS memory
  621.         jc      no_good         ;  jump if there was a problem
  622.  
  623.         mov     fileseg,bx      ; save initial segment address
  624.                                 ; of allocated memory
  625.         mov     file_size,ax    ; save file size
  626.         mov     file_size+2,dx
  627.  
  628. no_good:                        ; return with CF = 1 if error
  629.         ret                     ; CF = 0 if no error
  630. test_fload      endp
  631.         end
  632.  
  633.  
  634.  
  635. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  636.  
  637. FOPEN:       opens existing file and initializes ASMLIB buffered I/O
  638. Source:      fopen.asm (dosalloc.asm, $handle.asm)
  639.  
  640. Call with:   DS:[DX] pointing to name of file to be opened
  641.              AL = access mode
  642.               0 = read-only access
  643.               1 = write-only access
  644.               2 = read-write access NOT SUPPORTED YET
  645. Returns:     if CF = 0, AX = file handle
  646.              if CF = 1, AX = ASMLIB or DOS error code; file not opened
  647.                 if AX = 0, insufficient DOS memory available
  648.                 if AX = 0FFFFh, no handles available in ASMLIB I/O array;
  649.                    change NUMBER_OF_HANDLES in $handle.asm amd re-assemble
  650.                    (default = 20 handles)
  651. Uses:        AX, flags
  652. Example:
  653.  
  654. include  asm.inc
  655.  
  656. public   myprog
  657. extrn    fopen:proc, fclose:proc
  658.  
  659. .data
  660. file_name   db 'ASMLIB.DOC',0
  661. file_handle dw 0
  662.  
  663. .code
  664. myprog   proc
  665. ; program fragment assumes DS:@data
  666.          .
  667.          .
  668.          .
  669.          lea   dx,file_name
  670.          xor   al,al          ; read-only access
  671.          call  fopen
  672.          jc    something_went_wrong
  673.          mov   file_handle,ax ; save the handle
  674.          .
  675.          .
  676.          .
  677.  
  678. ; all done with this file
  679.          mov   bx,file_handle
  680.          call  fclose
  681.  
  682.  
  683.  
  684. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  685.  
  686. FPUT:        write specified number of bytes to output file buffer
  687. Source:      fput.asm ($handle.asm)
  688.  
  689. Call with:   BX = file handle
  690.              ES:[DI] pointing to data to write
  691.              CX = number of bytes to write
  692. Returns:     if CF = 0, no error
  693.              if CF = 1, AX = error code
  694. Uses:        AX, flags
  695. Example:
  696.  
  697. include  asm.inc
  698.  
  699. public   myproc
  700. extrn    fput:proc
  701. extrn    fputchr:proc
  702. extrn    fputcrlf:proc
  703.  
  704. .data
  705. data1    db 'several bytes may be written at once'
  706. data_len equ $-data1
  707.  
  708. .code
  709. ; program fragment assumes DS:@data
  710.          .
  711.          .
  712.          .
  713.          mov   bx,output_handle
  714.          push  ds
  715.          pop   es                     ; ES = DS = DGROUP
  716.          assume  es:DGROUP
  717.          lea   di,data1               ; ES:[DI] -> data1
  718.          mov   cx,data_len            ; bytes to write
  719.          call  fput
  720.          call  fputcrlf               ; write CR+LF for new line
  721.                                       ; in ASCII text file
  722.          mov   al,26                  ; End-of-File byte (optional)
  723.          call  fputchr
  724.  
  725.  
  726. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  727.  
  728. FPUTCHR:     write one character to output file buffer
  729. Source:      fputchr.asm (fput.asm)
  730.  
  731. Call with:   BX = output file handle
  732.              AL = character to write
  733. Returns:     if CF = 1, AX = MS-DOS error code
  734.              if CF = 0, no error
  735. Uses:        AX, flags
  736. Example:     see FPUT
  737. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  738.  
  739. FPUTCRLF:    write CR+LF pair to output file buffer
  740. Source:      fputcrlf.asm (fput.asm)
  741.  
  742. Call with:   BX = output file handle; file must have been opened by
  743.              FOPEN or FCREATE
  744. Returns:     if CF = 0, no error
  745.              if CF = 1, AX = DOS error code
  746. Uses:        AX, flags
  747. Example:     see FPUT
  748.  
  749.  
  750.  
  751. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  752.  
  753. FPUTSTR:     write an ASCIIZ string to output buffer
  754. Source:      fpustr.asm (strlen.asm, fput.asm)
  755.  
  756. Call with:   BX = file handle
  757.              ES:[DI] points to ASCIIZ string
  758. Returns:     if CF = 0, AX = bytes written
  759.              if CF = 1, AX = DOS error code
  760. Uses:        AX, flags
  761. Example:
  762.  
  763. include  asm.inc
  764.  
  765. public   myproc
  766. extrn    fputstr:proc
  767. extrn    fputcrlf:proc
  768.  
  769. .data
  770. strptr   dw 0                      ; pointer to string, assigned by program
  771.  
  772. .code
  773. ; program fragment assumes DS:@data
  774.          .
  775.          .
  776.          .
  777.          push  ds
  778.          pop   es                     ; ES = DS = DGROUP
  779.          assume  es:DGROUP
  780.          mov   bx,output_handle
  781.          mov   di,strptr              ; ES:[DI] -> data1
  782.          call  fputstr
  783.          call  fputcrlf               ; write CR+LF for new line
  784.                                       ; in ASCII text file
  785.  
  786.  
  787.  
  788. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  789.  
  790. FSEEK:       move file pointer for a file opened by FOPEN
  791. Source:      fseek.asm ($handle.asm)
  792.  
  793. Call with:   BX = file handle
  794.              AL = method code: 0 = absolute offset from start of file
  795.                                1 = signed offset from current file pointer
  796.                                2 = signed offset from end of file
  797.              CX:DX = dword offset
  798. Returns:     if CF = 1, AX = DOS error code
  799.              if CF = 0, DX:AX = current location of file pointer
  800. Uses:        AX, DX, flags
  801.  
  802. Example:
  803.  
  804. include   asm.inc
  805.  
  806. public  whoknows
  807.  
  808. extrn fopen:proc, fseek:proc
  809.  
  810. .data
  811. file0   db 'file0.dat',0
  812.  
  813. .code
  814. whoknows  proc
  815. ; program fragment assumes DS:@data
  816.         .
  817.         .
  818.         .
  819.         mov     dx,offset DGROUP:file0
  820.         mov     al,1              ; write only
  821.         call    fopen
  822.         jc      error
  823.         xor     cx,cx
  824.         mov     dx,cx             ; zero offset
  825.         mov     al,2              ; relative to end of file
  826.         call    fseek             ; move pointer to end of file
  827.  
  828.  
  829.  
  830.  
  831.  
  832. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  833.  
  834. FSIZE:       determines a file's size
  835. Source:      fsize.asm
  836.  
  837. Call with:   BX = valid file handle
  838. Returns:     if CF = 0, DX:AX = file size
  839.              if CF = 1, AX = MS-DOS error code
  840. Uses:        AX, DX, CF
  841. Example:
  842.  
  843. include asm.inc
  844.  
  845. extrn   fsize:proc
  846.  
  847. .data
  848. filenam db 'ASMLIB.DOC',0      ; ASCIIZ filename
  849.  
  850. .code
  851.         .
  852.         .
  853.         .
  854.         lea     dx,filenam     ; point to filename
  855.         mov     ax,3D00h       ; MS-DOS open file function, read-only
  856.         int     21h
  857.         jc      oops           ; jump to error control
  858.                                ; else no problem - continue
  859.         mov     bx,ax          ; file handle in BX
  860.         call    fsize
  861.  
  862.  
  863. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  864.  
  865. QFNAME:      qualifies a filename
  866. Source:      qfname.asm
  867.  
  868. Call with:   DS:[BX] pointing to a filename; the filename may contain
  869.              drive specification and/or complete or partial path name.
  870.              Drive specification and path name not required.
  871. Returns:     DS:[SI] pointing to the full DRIVESPEC:\PATH\FILENAME
  872.              CX = length of full filename
  873.              Note that DS:[SI] points to QFName's buffer space; the next
  874.              call to QFName will return a new filename at the same address.
  875. Uses:        SI, CX, flags
  876. Example:
  877.  
  878. include asm.inc
  879.  
  880. .data
  881. docs   db '*.doc',0         ; search for .DOC files in current directory
  882.  
  883. .code
  884. ; program fragment assumes DS:@data
  885.        .
  886.        .
  887.        .
  888.        lea    bx,docs
  889.        call   qfname
  890.  
  891.