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