home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / asmutil / asmlib37.zip / DATA.DOC < prev    next >
Text File  |  1993-01-20  |  39KB  |  1,188 lines

  1.  
  2. *******************************  DATA  *************************************
  3.  
  4. ASMLIB data manipulation subroutines Copyright (C) 1991 - 1993 Douglas Herr
  5. all rights reserved
  6.  
  7. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  8.  
  9. CHRDEL:      deletes a character from a string
  10. CHRNDEL:     deletes a character from a string of known length
  11.              The resulting space is closed by moving the remaining
  12.              characters forward
  13. Source:      chrdel.asm (strlen.asm)
  14.  
  15. Call with:   DS:[BX] pointing to an ASCIIZ string
  16.              (chrndel only) CX = current string length
  17.              AX = offset from DS:[BX] to character to delete
  18. Returns:     CX = new string length
  19. Uses:        CX
  20. Example:     lea   bx,string          ; DS:[BX] points to string
  21.              mov   ax,3               ; delete character at DS:[BX+3]
  22.              call  chrdel             ; delete the character, shorten string
  23.  
  24.  
  25. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  26.  
  27. COLORATTR:   calculate a color attribute for ASMLIB's text-mode subroutines.
  28.              Intended for 16-color text modes.
  29. Source:      coloratt.asm
  30. Call with:   AL = foreground color (0 - 15)
  31.              AH = background color (0 - 15)
  32. Returns:     AH = color attribute
  33. Uses:        AX
  34. Example:
  35.  
  36. include      asm.inc
  37.  
  38.       mov    al,hired            ; bright red
  39.       mov    ah,blue             ; blue
  40.       call   colorattr           ; this should get their attention
  41.       mov    warning,ah          ; save the attribute
  42.  
  43. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  44.  
  45. CSET:        centers a string in a fixed field
  46. Source:      cset.asm (strlen.asm)
  47.  
  48. Call with:   ES:[DI] = address of field string
  49.              DS:[SI] = address of string to be centered in the field
  50.              Both strings must be zero-terminated (ASCIIZ).  The field
  51.              string may not contain any nul characters except for the
  52.              terminator.
  53. Returns:     CF = 0 if no error
  54.              CF = 1 if string was truncated to fit in the field
  55. Uses:        CF; all other flags and registers are saved
  56. Example:     mov   ax,@data             ; in this case, both strings
  57.              mov   ds,ax                ; are in DGROUP
  58.              mov   es,ax
  59.              assume es:@data, ds:@data
  60.              lea   di,field             ; field string
  61.              lea   si,source            ; string to be centered in field
  62.              call  cset
  63.  
  64.  
  65. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  66.  
  67. DAYNAME:     returns a pointer to an ASCII string for specified day
  68.              of the week
  69. Source:      dname.asm (a$mname.asm)
  70.  
  71. Call with:   AX = day of week (1 - 7, Sunday = 1)
  72. Returns:     ES:[BX] = pointer to day name string
  73.              CX = length of new string
  74.              Note that the day name string is not zero-terminated
  75.              strndup may be used to copy the string to the near heap
  76. Uses:        ES, BX, CX
  77. Example:     mov    ax,day
  78.              call   dayname
  79.  
  80.  
  81.  
  82. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  83.  
  84. FILL4, FILL4b: fill a buffer with specified 4-byte data
  85. Source:        small & medium: fill4.asm
  86.                huge: fill4.asm (lowES2hi.asm)
  87.  
  88. Call with:   DS:[SI] pointing to 4-byte data (integer, float or other)
  89.              ES:[DI] pointing to buffer
  90.              CX = number of 4-byte data blocks to fill in buffer
  91.              Fill4b: BX = byte increment between data blocks
  92. Returns:     nothing
  93. Uses:        nothing
  94. Example:
  95.  
  96. include asm.inc
  97.  
  98. extrn   fill4:proc
  99.  
  100. .data
  101. wonowon dd 101.      ; float4 value
  102. farseg  dw ?         ; program allocates buffer, stores seg address here
  103.  
  104. .code
  105. program fragment assumes DS:@data
  106.         .
  107.         .
  108.         .
  109.         mov   es,farseg
  110.         xor   di,di      ; start at beginning of far segment
  111.         lea   si,wonowon ; fill every other 4-byte block in far segment
  112.         mov   bx,8       ; skip 4 bytes between data blocks
  113.         mov   cx,25      ; do it 25 times
  114.         cal   fill4
  115.  
  116.  
  117.  
  118. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  119.  
  120. FILL8, FILL8b: fill a buffer with specified 8-byte data
  121. Source:        small & medium: fill8.asm
  122.                huge: fill8.asm (lowES2hi.asm)
  123.  
  124. Call with:   DS:[SI] pointing to 8-byte data (integer, float or other)
  125.              ES:[DI] pointing to buffer
  126.              CX = number of 8-byte data blocks to fill in buffer
  127.              Fill8b: BX = byte increment between data blocks
  128. Returns:     nothing
  129. Uses:        nothing
  130. Example:     see Fill4
  131.  
  132.  
  133.  
  134.  
  135. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  136.  
  137. FSTRISTR:    search for a string in a disk file, case insensetive
  138. Source:      fstristr.asm (strlen.asm, $strstr.asm, strnupr.asm)
  139.  
  140. FSTRSTR:     search for a string in a disk file, case sensetive
  141. Source:      fstrstr.asm (strlen.asm, $strstr.asm)
  142.  
  143. Call with:   BX = file handle, DS:[SI] points to string to find
  144.              The file must have been opened with read access, and at least
  145.              64k DOS memory must be free.  See STARTUP.ASM and ENDPROG.ASM.
  146. Returns:     if CF = 0, DX:AX is the offset of the string in the file
  147.              if CF = 1: memory not available if AX = DX = 0
  148.                         string not found if AX = DX = -1
  149.                         error reading file if AX = DX = -2
  150. Uses:        AX, DX, flags
  151.  
  152. Example:
  153.  
  154. extrn   fstrstr:proc
  155.  
  156. .data
  157. string   db 'A String In The File',0
  158. filename db 'anyold.fil',0
  159.  
  160. .code
  161. yoursub proc
  162.         mov      dx,offset filename
  163.         mov      ax,3D00h          ; open the file with read access
  164.         int      21h
  165.         jc       no_good
  166.         mov      bx,ax
  167.         mov      si,offset string  ; DS:[SI] points to the string
  168.         call     fstrstr
  169.         jc       no_good           ; returns with DX = high word of
  170.                                    ; string position, AX = low word
  171.  
  172.  
  173. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  174.  
  175. GETCMD:      isolates command line parameters
  176.              GetCMD assumes that parameters are separated by
  177.              one or more spaces
  178. Source:      getcmd.asm
  179.  
  180. Call with:   ES = PSP segment (see STARTUP.ASM; not requried with TINY model)
  181.              AX = parameter number (first command line parameter = 0)
  182. Returns:     ES:[BX] pointing to command line parameter
  183.              CX = length of parameter string
  184.              CX = 0 if no command parameter(AX)
  185.              Note: the string at ES:[BX] is not zero-terminated
  186. Uses:        BX
  187. Example:
  188.  
  189. include asm.inc
  190.  
  191. extrn  getcmd:proc
  192.  
  193. .data
  194. extrn  pspseg:word        ; PSP segment saved by startup code
  195.  
  196. .code
  197.        .
  198.        .
  199.        .
  200.        mov    es,pspseg
  201.        mov    ax,0        ; get first parameter
  202.        call   getcmd      ; returns with ES:[BX] pointing to parameter
  203.                           ; and CX = length of parameter
  204.        jcxz   no_parameters
  205.        
  206.  
  207.  
  208. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  209.  
  210. I2TOSTR:     convert an integer value to an ASCIIZ string
  211. Source:      i2tostr.asm
  212.  
  213. I4TOSTR:     convert a long integer value to an ASCIIZ string
  214. Source:      i4tostr.asm
  215.  
  216.              ASMLIB's TPrint, GPrint and other 'print' subroutines require
  217.              a string argument.  Numeric data must be converted to a string
  218.              before printing.
  219.  
  220. Call with:   DS:[SI] pointing to a buffer space
  221.              (i2tostr) AX = integer value
  222.              (i4tostr) DX:AX = long integer value
  223.              i2tostr requires a 7-byte (or greater) buffer;
  224.              i4tostr requires a 12-byte (or greater) buffer
  225. Returns:     ASCIIZ string at DS:[SI]; numerals are right-justified
  226. Uses:        nothing; all registers and flags are saved
  227. Supports:    (i2tostr) signed 2-byte integers
  228.              (i4tostr) signed 4-byte integers
  229. Example:
  230.  
  231. include asm.inc
  232.  
  233. extrn  i2tostr:proc
  234.  
  235. .data
  236. nbuffer  db 7 dup(?)
  237.  
  238. .code
  239.  
  240.        .
  241.        .
  242.        .
  243.        mov   ax,@data
  244.        mov   ds,ax         ; numeric buffer is in DGROUP
  245.        assume  ds:@data
  246.        lea   si,nbuffer
  247.        mov   ax,32750      ; integer value
  248.        call  i2tostr
  249.  
  250.  
  251.  
  252. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  253.  
  254. LOWDS2HI:    converts low DS:high SI address to high DS:low SI
  255.              this is handy for data structures over 64k
  256. Source:      lowds2hi.asm
  257.  
  258. Call with:   DS:[SI] = address to convert
  259. Returns:     DS:[SI] = converted address; SI <= 15
  260. Uses:        DS, SI; all other registers and flags are saved
  261. Example:
  262.  
  263. extrn   lowDS2hi:proc
  264.  
  265. .code
  266.         .
  267.         .
  268.         .
  269.         mov   ds,hugeseg
  270.         mov   si,next_data
  271.         call  lowDS2hi       ; ready to address next (65535-15) bytes
  272.  
  273.  
  274. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  275.  
  276. LOWES2HI:    converts low ES:high DI address to high ES:low DI
  277.              this is handy for data structures over 64k
  278. Source:      lowes2hi.asm
  279.  
  280. Call with:   ES:[DI] = address to convert
  281. Returns:     ES:[DI] = converted address; DI <= 15
  282. Uses:        ES, DI; all other registers and flags are saved
  283. Example:
  284.  
  285. extrn   lowES2hi:proc
  286.  
  287. .code
  288.         .
  289.         .
  290.         .
  291.         mov   es,hugeseg
  292.         mov   di,next_data
  293.         call  lowES2hi       ; ready to address next (65535-15) bytes
  294.  
  295.  
  296.  
  297. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  298.  
  299. LSET:        left-justifies a string in a fixed field
  300. Source:      lset.asm (strlen.asm)
  301.  
  302. Call with:   ES:[DI] = address of field string
  303.              DS:[SI] = address of string to be justified in the field
  304.              Both strings must be zero-terminated (ASCIIZ).  The field
  305.              string may not contain any NUL characters except for the
  306.              terminator.
  307. Returns:     CF = 0 if no error
  308.              CF = 1 if string was truncated to fit in the field
  309. Uses:        CF
  310.              all other flags and registers saved
  311. Example:     mov   ax,@data             ; in this case, both strings
  312.              mov   ds,ax                ; are in DGROUP
  313.              mov   es,ax
  314.              assume es:@data, ds:@data
  315.              lea   di,field             ; field string
  316.              lea   si,source            ; string to be justified in field
  317.              call  lset
  318.  
  319.  
  320. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  321.  
  322. LTRIM:       remove leading blanks from an ASCIIZ string
  323. Source:      ltrim.asm (strlen.asm)
  324.  
  325. Call with:   DS:[BX] pointing to string
  326. Returns:     CX = new string length
  327. Uses:        CX
  328. Example:     lea    bx,string
  329.              call   ltrim
  330.  
  331.  
  332.  
  333.  
  334. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  335.  
  336. MAXI2, MAXI2b: find maximum value in a signed integer array
  337. Source:        small & medium models: maxi2.asm
  338.                huge model: maxi2.asm (lowDS2hi.asm)
  339.  
  340. MINI2, MINI2b: find minimum value in a signed integer array
  341. Source:        small & medium models: mini2.asm
  342.                huge model: mini2.asm (lowDS2hi.asm)
  343.  
  344. MAXU2, MINU2b: find maximum value in an unsigned integer array
  345. Source:        small & medium models: maxu2.asm
  346.                huge model: maxu2.asm (lowDS2hi.asm)
  347.  
  348. MINU2, MINU2b: find minimum value in an unsigned integer array
  349. Source:        small & medium models: minu2.asm
  350.                huge model: minu2.asm (lowDS2hi.asm)
  351.  
  352. Call with:   ES:[DI] pointing to the array
  353.              CX = number of array elements
  354.              For max/min?2b, call with BX = byte increment between
  355.              array elements.  Max/min?2 assume increment = 2.
  356. Returns:     AX = array element number with maximum value
  357.              see example to calculate address of maximum value
  358.              if subroutine was called with CX = 0, CF = 1
  359. Uses:        AX, CF
  360. Example:
  361.  
  362. include asm.inc
  363.  
  364. extrn  maxi2:proc
  365.  
  366. .data
  367.  
  368. integers     dw 140 dup(0)
  369.  
  370. .code
  371.              .     ; program establishes array values
  372.              .
  373.              .
  374.              mov    ax,@data
  375.              mov    es,ax
  376.              assume es:@data
  377.              lea    di,integers
  378.              mov    cx,140        ; search the entire array
  379.              call   maxi2
  380.              shl    ax,1          ; convert word offset to byte offsest
  381.              add    di,ax         ; ES:[DI] points to the maximum value
  382.                                   ; With max/min?2b, the offset of the
  383.                                   ; value is DI + (AX * BX).
  384.  
  385. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  386.  
  387. MAXI4, MAXI4b: find maximum value in a signed 4-byte integer array
  388. Source:        small & medium models: maxi4.asm
  389.                huge model: maxi4.asm (lowDS2hi.asm)
  390.  
  391. MINI4, MINI4b: find minimum value in a signed 4-byte integer array
  392. Source:        small & medium models: mini4.asm
  393.                huge model: mini4.asm (lowDS2hi.asm)
  394.  
  395. MAXU4, MAXU4b: find maximum value in an unsigned 4-byte integer array
  396. Source:        small & medium models: maxu4.asm
  397.                huge model: maxu4.asm (lowDS2hi.asm)
  398.  
  399. MINU4, MINU4b: find minimum value in an unsigned 4-byte integer array
  400. Source:        small & medium models: minu4.asm
  401.                huge model: minu4.asm (lowDS2hi.asm)
  402.  
  403. Call with:   ES:[DI] pointing to the array
  404.              CX = number of array elements
  405.              For max/min?4b, call with BX = byte increment between
  406.              array elements.  Max/min?4 assume increment = 4.
  407. Returns:     AX = array element number with maximum value
  408.              see example to calculate address of maximum value.
  409.              if subroutine was called with CX = 0, CF = 1
  410. Uses:        AX, CF
  411. Example:
  412.  
  413. include asm.inc
  414.  
  415. extrn  maxi4:proc
  416.  
  417. .data
  418.  
  419. int4         dd 140 dup(0)
  420.  
  421. .code
  422.              .     ; program establishes array values
  423.              .
  424.              .
  425.              mov    ax,@data
  426.              mov    es,ax
  427.              assume es:@data
  428.              lea    di,int4
  429.              mov    cx,140        ; search the entire array
  430.              call   maxi4
  431.              shl    ax,1          ; convert dword offset to word offset
  432.              shl    ax,1          ; convert word offset to byte offset
  433.              add    di,ax         ; ES:[DI] points to the maximum value
  434.                                   ; With max/min?4b, the offset of the
  435.                                   ; value is DI + (AX * BX).
  436.  
  437. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  438.  
  439. MONTHNAME:   returns a pointer to an ASCII string for specified month
  440. Source:      mname.asm (a$mname.asm)
  441.  
  442. Call with:   AX = month (1 - 12, January = 1)
  443. Returns:     ES:[BX] = pointer to month name string
  444.              CX = length of month string
  445.              Note that the month name string is not zero-terminated
  446.              strndup may be used to copy the string to the near heap
  447. Uses:        ES, BX, CX
  448. Example:     mov    ax,month
  449.              call   monthname
  450.              jc     no_memory
  451.  
  452.  
  453.  
  454. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  455.  
  456. NFORMAT:     formats a numeric string
  457. Source:      nformat.asm (ltrim.asm, strspace.asm, heap.asm)
  458.  
  459. Call with:   DS:[SI] pointing to a numeric string (such as one produced
  460.              by i4tostr or i2tostr)
  461.              AL = number of decimal places in output string
  462.              BL = option code
  463.               where option 1 = negative numbers enclosed with parentheses
  464.                     option 2 = commas between thousands
  465.                     option 4 = decimals truncated (instead of rounded)
  466.              assumes DS @data
  467.              Note: you must initialize the near heap with HINIT before
  468.              using NFORMAT.  See STARTUP.ASM.
  469. Returns:     DS:[BX] pointing to formatted ASCIIZ string
  470. Uses:        BX, CF
  471.  
  472. Example:
  473.  
  474. include asm.inc
  475.  
  476. extrn  nformat:proc, i2tostr:proc
  477. extrn  hinit:proc
  478.  
  479. .data
  480.  
  481. ; reserve space for the heap
  482. heapsize equ 3000                ; should be plenty
  483. hbuffer  db heapsize  dup (0)
  484.  
  485. ; I'll use this numeric buffer
  486. nbuffer  db 12 dup(0)
  487.  
  488. .code
  489. ; program fragment assumes DS:@data
  490.          .
  491.          .
  492.          .
  493.          lea    bx,hbuffer
  494.          mov    ax,heapsize
  495.          call   hinit
  496.          mov    ax,-12345
  497.          lea    si,nbuffer
  498.          call   i2tostr
  499.          mov    al,2             ; 2 decimal places
  500.          mov    bl,1 OR 2        ; I want parentheses and commas
  501.          call   nformat          ; result returned at DS:[BX]
  502.                                  ; remember to release the formatted
  503.                                  ; string space with HFREE when you're
  504.                                  ; done with the string
  505.  
  506. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  507.  
  508. PATH:        finds paths in program enviornment
  509.              isolates each path in "PATH=" part of enviornment
  510. Source:      path.asm (strlen.asm)
  511.  
  512. Call with:   ES = PSP segment, AX = path number.  See STARTUP.ASM.
  513. Returns:     ES:[BX] -> path(AX) in enviornment block, CX = length of path
  514.              If CX = 0, path(AX) does not exist.  The first path in the
  515.              enviornment is path(0).
  516.              Note that the path string at ES:[BX] is NOT zero-terminated.
  517. Uses:        BX, CX, ES; flags and all other registers are saved
  518. Example:     
  519.  
  520. ; program startup code saves PSP segment
  521. include asm.inc
  522.  
  523. extrn   path:proc
  524.  
  525. stacksize equ 1024
  526. .stack stacksize
  527.  
  528. .data
  529. public pspseg
  530. pspseg dw ?                          ; storage for PSP segment
  531.  
  532. .code
  533. includelib asmlib
  534. start:
  535. ; start by pointing DS to DGROUP
  536.         mov     ax,@data
  537.         mov     ds,ax
  538.         assume  ds:@data
  539.  
  540. ; save PSP segment
  541.         mov     pspseg,es
  542.          .
  543.          .
  544.          .
  545. ; sometime later in the program
  546.         xor     ax,ax        ; start with the first path
  547. find_path:
  548.         mov     es,pspseg
  549.         call    path
  550.         jcxz    no_path      ; exit if no more paths, or else copy CX bytes
  551.                              ;  at ES:[BX] to some useful location (try
  552.                              ;  strndup).
  553.         inc     ax           ; look for next path
  554.         jmp     find_path
  555.  
  556. no_path:
  557.  
  558.  
  559. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  560.  
  561. QFNAME:      qualifies a filename
  562. Source:      qfname.asm
  563.  
  564. Call with:   DS:[BX] pointing to a filename; the filename may contain
  565.              drive specification and/or complete or partial path name.
  566.              Drive specification and path name not required.
  567. Returns:     DS:[SI] pointing to the full DRIVESPEC:\PATH\FILENAME
  568.              CX = length of full filename
  569.              Note that DS:[SI] points to QFName's buffer space; the next
  570.              call to QFName will return a new filename at the same address.
  571. Uses:        SI, CX, flags
  572. Example:
  573.  
  574. include asm.inc
  575.  
  576. .data
  577. docs   db '*.doc',0         ; search for .DOC files in current directory
  578.  
  579. .code
  580.        .
  581.        .
  582.        .
  583.        mov    ax,@data
  584.        mov    ds,ax
  585.        lea    bx,docs
  586.        call   qfname        ; returns 'drive:\path\*.doc'
  587.  
  588.  
  589. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  590.  
  591. RANDOM:      generates a near-random number
  592. Source:      random.asm
  593.  
  594. Call with:   no parameters
  595. Returns:     AX = near-random number between 0 and 65535
  596.              you may notice repeating patterns every few thousand calls
  597.              to Random.
  598. Uses:        AX
  599. Example:     call   random
  600.  
  601.  
  602.  
  603. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  604.  
  605. RSET:        right-justifies a string in a fixed field
  606. Source:      rset.asm (strlen.asm)
  607.  
  608. Call with:   ES:[DI] = address of field string
  609.              DS:[SI] = address of string to be justified in the field
  610.              Both strings must be zero-terminated (ASCIIZ).  The field
  611.              string may not contain any nul characters except for the
  612.              terminator.
  613. Returns:     CF = 0 if no error
  614.              CF = 1 if string was truncated to fit in the field
  615. Uses:        CF; all other flags and registers saved
  616. Example:     mov   ax,@data             ; in this case, both strings
  617.              mov   ds,ax                ; are in DGROUP
  618.              mov   es,ax
  619.              assume es:@data, ds:@data
  620.              lea   di,field             ; field string
  621.              lea   si,source            ; string to be justified in field
  622.              call  rset
  623.  
  624.  
  625. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  626.  
  627. RTRIM:       removes trailing blanks from an ASCIIZ string
  628. Source:      rtrim.asm (strlen.asm)
  629.  
  630. Call with:   DS:[BX] pointing to string
  631. Returns:     CX = new string length
  632. Uses:        CX
  633. Example:     lea    bx,string
  634.              call   rtrim
  635.  
  636.  
  637.  
  638. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  639.  
  640. SORTI4HI:    sort a signed array of 4-byte integers, highest first
  641. Source:      sorti4hi.asm
  642.  
  643. SORTI4LO:    sort a signed array of 4-byte integers, lowest first
  644. Source:      sorti4lo.asm
  645.  
  646. Call with:   ES:[DI] = address of first element of array to sort
  647.              CX = number of array elements
  648. Returns:     nothing
  649. Uses:        nothing; all registers and flags are saved
  650. Example:
  651.  
  652. include asm.inc
  653.  
  654. extrn    sorti4hi:proc
  655.  
  656. .data
  657.  
  658. i4data   dd 1500 dup(0)
  659.  
  660. .code
  661.  
  662.              .      ; program establishes data values
  663.              .
  664.              .
  665.          mov    ax,@data
  666.          mov    es,ax
  667.          assume es:@data
  668.          lea    di,i4data
  669.          mov    cx,1500
  670.          call   sorti4hi
  671.  
  672.  
  673.  
  674. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  675.  
  676. STRTOI2:     converts an ASCII string to equivalent integer value
  677. STRNTOI2:    converts n bytes of an ASCII string to equivalent integer value
  678.              strtoi2 and strntoi2 ignore leading blanks and tabs, then read
  679.              the string until a non-numeric character is read.
  680.              strntoi2 reads a maximum of CX characters or until a
  681.              non-numeric character is read, whichever comes first.
  682. Source:      strtoi2.asm
  683.  
  684. STRTOI4:     converts an ASCII string to a long integer value
  685. STRNTOI4:    converts n bytes of an ASCII string to a long integer value
  686.              similar to strtoi2 and strntoi2, but returning a long integer
  687.              value in DX:AX.
  688. Source:      strtoi4.asm
  689.  
  690. Call with:   DS:[SI] = address of string
  691.              strntoi2/strntoi4 only: CX = number of bytes to read
  692. Returns:     AX = integer value, or DX:AX = long integer value
  693.              strtoix:  DS:[SI] points to character past terminating byte
  694.              strntoix: if CX = 0, DS:[SI] points to next character
  695.                      if CX <> 0, DS:[SI] points to character past
  696.                      terminating byte
  697.              BL = error code
  698.                 bit 0 if set = CR read before reading any numeric characters
  699.                 bit 1 if set = CR was the terminating character
  700.                 bit 6 if set = overflow; result in DX:AX is unusable
  701.                 bit 7 if set = result is unsigned; result is unusable if the
  702.                                value represented by the string was negative
  703. Uses:        AX, BX, CX, SI, flags
  704. Example:     lea    si,long_integer  ; near address of ASCII string
  705.              mov    cx,7             ; 7-byte field
  706.              call   strntoi2         ; return result as an integer in AX
  707.  
  708.  
  709.  
  710.  
  711. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  712.  
  713. STRCAT:      catenates (combines) two ASCIIZ strings
  714. Source:      strcat.asm (strdup.asm, strlen.asm, heap.asm)
  715.  
  716. Call with:   DS:[SI] = address of first string
  717.              DS:[BX] = address of second string
  718.              assumes DS:@data
  719. Returns:     if CF = 0, DS:[BX] = address of combined ASCIIZ string
  720.              if CF = 1, insufficient memory available in near heap
  721.              Note: you must initialize the near heap with HINIT before
  722.              using STRCAT.  See STARTUP.ASM.
  723. Uses:        BX, CX, CF
  724. Example:
  725.  
  726. include asm.inc
  727.  
  728. extrn  strcat:proc
  729.  
  730. .data
  731. string0 db 'this string goes first',0
  732. string1 db ' this one is added at the end of the first',0
  733.  
  734. .code
  735. ; program fragment assumes DS:@data
  736.        .
  737.        .
  738.        .
  739.        lea    si,string0       ; address of first string
  740.        lea    bx,string1       ; address of second string
  741.        call   strcat           ; result returned at DS:[BX]
  742.        jc     heap_is_full     ; original strings are undisturbed
  743.  
  744.  
  745.  
  746. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  747.  
  748. STRCHR:      search an ASCIIZ string for a specified character
  749. STRNCHR:     search n bytes of an ASCII string for a specified character
  750. Source:      strchr.asm (strlen.asm)
  751.  
  752. Call with:   DS:[BX] = pointer to ASCIIZ string
  753.              AL = character to find
  754.              CX = number of bytes to search (strnchr only)
  755. Returns:     CX = string length
  756.              if CF = 0, AX is the offset from DS:[BX] to matching character
  757.              in the source string
  758.              if CF = 1, no matching character found
  759. Uses:        CX, AX, CF
  760.  
  761. Example on next page
  762.  
  763. ; use STRNCHR to determine if a key pressed was a legal key
  764. include asm.inc
  765.  
  766. extrn   strnchr:proc, getkey:proc, toupper:proc
  767.  
  768. .data
  769.  
  770. valid_string db 'ABC123',27      ; keys 1,2,3,A,B,C and Esc
  771. valid_len    equ $-valid_string  ; number of valid keys
  772.  
  773. dispatch_table label word
  774.         dw akey, bkey, ckey, onekey, twokey, threekey, esckey
  775.  
  776. .code
  777. ; program fragment assumes DS:@data
  778.         .
  779.         .
  780.         .
  781. get_another:
  782.         lea   bx,valid_string ; DS:[BX] points to a string of valid keys
  783.         call  getkey          ; keycode returned in AX
  784.         shr   ah,1            ; test for extended keycode
  785.         jc    get_another     ; I'm not interested in extended keycodes today
  786.  
  787.         call  toupper         ; convert keycode to upper case
  788.         mov   cx,valid_len
  789.         call  strnchr
  790.         jc    get_another     ; CF = 1 if key pressed is not among the
  791.                               ; keys in the validation string
  792.         mov   bx,ax
  793.         shl   bx,1            ; convert byte offset to word offset
  794.         jmp   dispatch_table[bx]
  795.  
  796. akey:   .
  797.         .
  798.         .
  799.  
  800. bkey:   .
  801.         .
  802.         .
  803.  
  804. ckey:   .
  805.         .
  806.         .
  807.  
  808. ; etc
  809.  
  810.  
  811.  
  812. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  813.  
  814. STRCPY:      copy an ASCIIZ string to existing buffer
  815. Source:      strcpy.asm (strlen.asm, strncpy.asm)
  816.  
  817. Call with:   ES:[BX] pointing to ASCIIZ string
  818.              DS:[SI] pointing to destination buffer
  819.              STRCPY assumes that the buffer is long enough to hold the
  820.              entire string.  The string's terminating NUL byte is not
  821.              copied to the buffer.
  822. Returns:     CX = string length
  823. Uses:        CX
  824. Example:
  825.  
  826. include asm.inc
  827.  
  828. extrn   strcpy:proc
  829.  
  830. .fardata
  831. fstring        db 'a far string',0
  832.  
  833. .data
  834. string_buffer  db 128 dup (?)
  835.  
  836. .code
  837. ; code fragment assumes DS:@data
  838.        .
  839.        .
  840.        .
  841. ; copy far string to DGROUP for convenient manipulation
  842.        mov    ax,@fardata
  843.        mov    es,ax
  844.        assume es:@fardata
  845.        mov    bx,offset @fardata:fstring
  846.        mov    si,offset @data:string_buffer
  847.        call   strcpy
  848.  
  849.  
  850. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  851.  
  852. STRNCPY:     copy CX bytes to an existing buffer
  853. Source:      strncpy.asm
  854.  
  855. Call with:   ES:[BX] pointing to ASCII string
  856.              DS:[SI] pointing to destination buffer
  857.              CX = number of bytes to copy
  858.              STRNCPY assumes that the buffer is long enough to hold the
  859.              entire string
  860. Returns:     nothing
  861. Uses:        nothing; all registers and flags are saved
  862. Example:
  863.  
  864. ; I want to copy a command line parameter to DGROUP
  865.  
  866. include asm.inc
  867. extrn   getcmd:proc
  868. extrn   strncpy:proc
  869.  
  870. .data
  871. extrn   pspseg:word             ; PSP segment address was saved by STARTUP
  872. string_buffer   db 128 dup (?)
  873.  
  874. .code
  875. ; code fragment assumes DS:@data
  876.        .
  877.        .
  878.        .
  879.        mov      es,pspseg
  880.        xor      ax,ax           ; first command line parameter
  881.        call     getcmd          ; returns parameter at ES:[BX], length as CX
  882.        jcxz     no_parameters
  883.        lea      si,string_buffer
  884.        call     strncpy
  885.  
  886. ; make it zero-terminated
  887.        add      si,cx
  888.        mov      byte ptr [si],0
  889.  
  890.  
  891. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  892.  
  893. STRINS:      inserts string1 in string0 at specified offset.
  894.              Creates new string in near heap; first part of new string
  895.              is n bytes of string0; middle of new string is string1; end
  896.              of new string is remainder of string0.
  897. Source:      strins.asm (strlen.asm, heap.asm)
  898.  
  899. Call with:   DS:[SI] pointing to string0
  900.              DS:[BX] pointing to string1
  901.              AX = offset in string0 to insert string1 (0 >= AX >= 32767)
  902.              Assumes DS:@data
  903. Returns:     if CF = 1, insufficient memory in hear heap
  904.              if CF = 0, DS:[BX] points to new string
  905.              Note: you must initialize the near heap with HINIT before
  906.              using STRINS.  See STARTUP.ASM.
  907. Uses:        BX, CF
  908. Example:
  909.  
  910. include asm.inc
  911.  
  912. extrn  strins:proc
  913.  
  914. .data
  915. string0 db '1234567890',0
  916. string1 db 'abcdefghij',0
  917.  
  918. .code
  919.        .
  920.        .
  921.        .
  922.        mov    ax,@data
  923.        mov    ds,ax            ; dgroup
  924.        assume ds:@data         ; tell MASM about it
  925.        lea    si,string0       ; address of first string
  926.        lea    bx,string1       ; address of second string
  927.        mov    ax,3             ; string1 inserted after '123'
  928.        call   strins           ; result returned at DS:[BX]
  929.        jc     heap_is_full     ; original strings are undisturbed
  930.  
  931.  
  932.  
  933. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  934.  
  935. STRDUP:      duplicates a string at ES:[BX]
  936. Source:      strdup.asm (strlen.asm, heap.asm)
  937.  
  938. STRNDUP:     duplicates n bytes of a string at ES:[BX]
  939. Source:      strndup (strdup.asm, heap.asm)
  940.  
  941. Call with:   ES:[BX] = address of source string
  942.              assumes DS:@data
  943.              (strndup) CX = number of bytes to duplicate
  944.              String copied to near heap
  945.              Source string need not be in same segment as heap
  946.              strdup requires an ASCIIZ string; strndup duplicates CX
  947.              characters at ES:[BX] whether zero-terminated or not.  The
  948.              duplicate created by strdup or strndup will be an ASCIIZ
  949.              string.
  950.  
  951. Returns:     if CF = 0, DS:[BX] = address of string copy
  952.                         CX = string length
  953.              if CF = 1, insufficient memory in near heap
  954.              Note: you must initialize the near heap with HINIT before
  955.              using STRDUP.  See STARTUP.ASM.
  956. Uses:        BX, CX, CF; all other flags and registers are saved
  957. Example:     mov  ax,@data
  958.              mov  ds,ax
  959.              mov  es,ax              ; in this case, the source string
  960.                                      ; is in the data segment
  961.              lea  bx,source          ; ES:[BX] = source address
  962.              call strdup
  963.              jc   oops               ; not enough memory if CF = 1
  964.                                      ; otherwise, DS:[BX] = address
  965.                                      ; of string copy
  966.  
  967.  
  968. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  969.              
  970. STRIPCHR:    remove all occurances of a character from an ASCIIZ string.
  971. Source:      stripchr.asm (strlen.asm)
  972.  
  973. Call with:   DS:[BX] = string address
  974.              AL = character to remove from the string
  975. Returns:     CX = new string length
  976. Uses:        CX
  977. Example:     lea    bx,string        ; DS:[BX] -> string
  978.              mov    al,'$'           ; remove "$" character from string
  979.              call   stripchr
  980.  
  981.  
  982. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  983.  
  984. STRLEN:      finds length of an ASCIIZ string
  985. Source:      strlen.asm
  986.  
  987. Call with:   DS:[BX] = address of the string
  988. Returns:     CX = length of string excluding the terminating NUL
  989. Uses:        CX
  990. Example:     lea   bx,string
  991.              call  strlen
  992.  
  993.  
  994. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  995.  
  996. STRLWR:      changes upper-case characters in a string to lower case
  997. Source:      strlwr.asm
  998.  
  999. STRNLWR:     changes n bytes of a string to lower case
  1000. Source:      strnlwr.asm
  1001.  
  1002. Call with:   DS:[BX] = address of an ASCIIZ string
  1003.              CX = number of bytes (strnlwr only)
  1004. Returns:     nothing
  1005. Uses:        nothing
  1006. Example:     lea    bx,string
  1007.              call   strlwr
  1008.  
  1009.  
  1010.  
  1011. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1012.  
  1013. STRRCHR:     find the last byte in a string matching AL
  1014. STRNRCHR:    find the last byte in n bytes matching AL
  1015. Source:      strrchr.asm (strlen.asm)
  1016.  
  1017. Call with:   DS:[BX] pointing to the first character of the string
  1018.              AL = byte to find
  1019.              (strnrchr only) CX = number of bytes to search
  1020. Returns:     if CF = 1, no match
  1021.              if CF = 0, AX = offset from DS:[BX] of the last matching byte
  1022. Uses:        AX, CF; all other flags and registers are saved
  1023. Example:
  1024.  
  1025. .data
  1026. string   db 'my old computer was a real slug',0
  1027.  
  1028. .code
  1029.         .
  1030.         .
  1031.         .
  1032.          mov   ax,@data
  1033.          mov   ds,ax
  1034.          assume  ds:@data
  1035.  
  1036.          mov   al,'w'         ; look for the lower-case "w"
  1037.          lea   bx,string
  1038.          call  strrchr
  1039.          jc    oops           ; cut outta here if not in the string
  1040.                               ; else go on
  1041.  
  1042.  
  1043.  
  1044. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1045.  
  1046. STRREV:      reverses all characters in a string
  1047. STRNREV:     reverses n characters in a string
  1048. Source:      strrev.asm (strlen.asm)
  1049.  
  1050. Call with:   DS:[BX] pointing to the first character of the string
  1051.              CX = number of bytes in string to reverse (strnrev only)
  1052. Returns:     CX = string length
  1053. Uses:        CX; all other registers and flags saved
  1054. Example:     lea   bx,string          ; DS:[BX] points to ASCIIZ string
  1055.              call  strrev             ; also returns CX = string length
  1056.  
  1057.  
  1058.  
  1059. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1060.  
  1061. STRSPACE:    creates an ASCIIZ string filled with the space character,
  1062.              terminated with NUL
  1063. Source:      strspace.asm (heap.asm)
  1064.  
  1065. Call with:   AX = string length (not including terminating NUL)
  1066.              Assumes DS:@data
  1067. Returns:     if CF = 1, insufficient memory in near heap
  1068.              if CF = 0, DS:[BX] points to the new string
  1069.                         CX = string length (should be same as AX)
  1070.              Note: you must initialize the near heap with HINIT before
  1071.              using STRSPACE.  See STARTUP.ASM.
  1072. Uses:        CX, BX, CF
  1073. Example:     mov   ax,14              ; make a new string 14 characters long
  1074.              call  strspace
  1075.              jc    oops               ; not enough memory if CF = 1
  1076.              mov   string14,bx        ; else save pointer to string
  1077.  
  1078.  
  1079. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1080.  
  1081. STRSET:      sets all bytes of an ASCIIZ string to a specified character
  1082. STRNSET:     sets n bytes of an ASCIIZ string to a specified character
  1083. Source:      strset.asm (strlen.asm)
  1084.  
  1085. Call with:   DS:[BX] pointing to a valid ASCIIZ string
  1086.              AL = character
  1087.              CX = number of bytes to set (strnset only)
  1088. Returns:     CX = string length
  1089. Uses:        CX
  1090. Example:     lea   bx,string          ; DS:[BX] points to an ASCIIZ string
  1091.              mov   al,'*'
  1092.              call  strset
  1093.  
  1094.  
  1095.  
  1096.  
  1097. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1098.  
  1099. STRSTR:      finds the first match with a target string in a source string
  1100.              case sensetive
  1101. Source:      strstr.asm ($strstr.asm, strlen.asm)
  1102.  
  1103. STRISTR:     finds the first match with a target string in a source string
  1104.              case insensetive
  1105. Source:      stristr.asm (strstr.asm, strdup.asm, upcase.asm, heap.asm)
  1106.  
  1107. STRRSTR:     finds the last match with a target string in a source string
  1108.              case sensetive
  1109. Source:      strrstr.asm (strrev.asm, $strstr.asm)
  1110.  
  1111. Call with:   ES:[DI] pointing to source string, DS:[SI] pointing to
  1112.              target string.
  1113.              STRISTR assumes DS:@data
  1114. Returns:     if CF = 0, AX = offset of target in source string.
  1115.              if CF = 1, no match
  1116.  
  1117.              Note: you must initialize the near heap with HINIT before
  1118.              using STRISTR.  See STARTUP.ASM.
  1119. Uses:        AX, CF; all other flags and registers are saved
  1120. Example:     mov   ax,@fardata
  1121.              mov   es,ax
  1122.             assume es:@fardata     ; source string is in far data area
  1123.              mov   ax,@data
  1124.              mov   ds,ax
  1125.             assume ds:@data
  1126.              lea   di,string       ; source = 'monday',0
  1127.              lea   si,substring    ; target = 'day',0
  1128.              call  strstr          ; in this example, strstr returns ax = 3
  1129.  
  1130.  
  1131. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1132.  
  1133. STRUPR:      changes lower-case characters in an ASCIIZ string to upper case
  1134. Source:      strupr.asm
  1135.  
  1136. STRNUPR:     changes lower-case characters in an n-length string to upper case
  1137. Source:      strnupr.asm
  1138.  
  1139. Call with:   DS:[BX] pointing to string
  1140.              (strnupr only) CX = number of bytes in string
  1141. Returns:     nothing
  1142. Uses:        nothing
  1143. Example:     mov    bx,offset string
  1144.              mov    cx,bytes
  1145.              call   strnupr
  1146.  
  1147.  
  1148.  
  1149. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1150.  
  1151. SWAPB:       swaps AX bytes at DS:[SI] with the same number at ES:[DI]
  1152. Source:      swapb.asm
  1153.  
  1154. Call with:   DS:[SI] pointing to one of the data areas, ES:[DI] pointing
  1155.              to the other
  1156.              AX = number of bytes to swap
  1157. Returns:     nothing
  1158. Uses:        nothing; all registers and flags are saved
  1159. Example:
  1160.  
  1161. include  asm.inc
  1162.  
  1163. extrn    swapb:proc
  1164.  
  1165. .data
  1166.  
  1167. string1  db 'this is string 1',0
  1168. string2  db 'this is string 2',0
  1169.  
  1170. strings  dw string1, string2         ; addresses of the strings
  1171.                                      ; this example will swap
  1172.                                      ; the string pointers
  1173.  
  1174. .code
  1175. public   stringswap
  1176. stringswap   proc
  1177. ; program fragment assumes DS:@data
  1178.          .
  1179.          .
  1180.          .
  1181.          lea   si,strings
  1182.          push  ds
  1183.          pop   es                    ; ES = DS
  1184.          mov   di,si
  1185.          mov   ax,2                  ; each string pointer is 2 bytes
  1186.          add   di,ax                 ; point to 2nd pointer
  1187.          call  swapb
  1188.