home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / dos / prg / bas / asilib11 / data.doc < prev    next >
Text File  |  1994-10-22  |  18KB  |  524 lines
  1. *******************************  DATA  *************************************
  2.  
  3. ASILIB data manipulation subroutines Copyright (C) 1994 Douglas Herr
  4. all rights reserved
  5.  
  6. ASIC string data is restricted to a maximum of 80 bytes per string, and
  7. each ASIC string uses 80 bytes plus one string terminating NUL byte.
  8. ASILIB's string subroutines work perfetly well with ASIC strings, and
  9. most permit any other data space in ASIC's data area to be used as
  10. though it were a text string.  For example, if your program is reading a
  11. text file with each line as ling as 132 characters, you would have trouble
  12. fitting each line into an ASIC string.  However, you may dimension an
  13. array of 132 bytes (plus one terminating byte) as an integer array:
  14.  
  15. DIM reallyastring(67)
  16.  
  17. (Recall that each integer is 2 bytes)
  18.  
  19. By passing reallyastring(1) to FGetStr (for example) in place of the string
  20. parameter, you can safely read lines up to 132 characters long.  There are
  21. a few ASILIB subroutines that will work ONLY with ASIC strings; this fact
  22. is clearly stated in the documentation for each applicable subroutine.
  23.  
  24.  
  25. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  26.  
  27. GET2:         Get 2 bytes from far memory
  28.  
  29. Parameters:   data segment, data offset&, twobytes
  30.  
  31.               Read 2 bytes from data in far memory.  Note that in order
  32.               to access the upper 32k of a large data block you need to
  33.               use a long integer as your offset, even with the normal
  34.               ASILIB.LIB library.  Get2 in ASIHUGE.LIB works properly with
  35.               data blocks over 64k.  In either case, the data segment used
  36.               to access the data is the base segment returned by ASILIB's
  37.               ALLOCDOS or other ASILIB subroutines that allocate far
  38.               memory and return a segment address.
  39.  
  40. Example:
  41.  
  42. REM  My program has a data block in far memory and I want to retrieve
  43. REM  an integer from it
  44.  
  45. REM  50th integer
  46. REM  remember that the first integer is at offset 0
  47.         dataoffset&=98
  48.         call sub "get2", datasegment, dataoffset&, twobytes
  49.  
  50.  
  51. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  52.  
  53.  
  54. GET4:         Get 4 bytes from far memory
  55.  
  56. Parameters:   data segment, data offset&, fourbytes&
  57.  
  58.               Read 4 bytes from data in far memory.  Note that in order
  59.               to access the upper 32k of a large data block you need to
  60.               use a long integer as your offset, even with the normal
  61.               ASILIB.LIB library.  Get4 in ASIHUGE.LIB works properly with
  62.               data blocks over 64k.  In either case, the data segment used
  63.               to access the data is the base segment returned by ASILIB's
  64.               ALLOCDOS or other ASILIB subroutines that allocate far
  65.               memory and return a segment address.
  66.  
  67. Example:
  68.  
  69. REM  My program has a data block in far memory and I want to retrieve
  70. REM  a long integer from it
  71.  
  72. REM  50th integer
  73. REM  remember that the first integer is at offset 0
  74.         dataoffset&=196
  75.         call sub "get4", datasegment, dataoffset&, fourbytes&
  76.  
  77.  
  78. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  79.  
  80. I2TOSTR:     convert an integer value to a string
  81.  
  82. I4TOSTR:     convert a long integer value to a string
  83.  
  84. Parameters:  (i2tostr) number, nstring$
  85.              (i4tostr) number&, nstring$
  86.  
  87.              ASILIB's TPrint, GPrint and other 'print' subroutines require
  88.              a string argument.  Numeric data must be converted to a string
  89.              before printing.  NString$ is where the string form of the
  90.              number is placed.  Note that i4tostr number& is a long integer
  91.              which requires ASIC's Extended math option.  If you use an
  92.              ASILIB string, the string must be at least 7 bytes for i2tostr
  93.              or 12 bytes for i4tostr.  If you use an ASIC string, you don't
  94.              need to consider the string length because all ASIC strings
  95.              are 80 bytes.
  96.  
  97. Example:
  98.  
  99. REM  using ASIC string
  100.         n=12345
  101.         call sub "i2tostr", n, nstring$
  102.  
  103. REM  using ASILIB string
  104. REM  a 6-integer array is 12 bytes
  105.         DIM n(6)
  106.         n&=1234567&
  107.         call sub "i4tostr", n&, n(1)
  108.  
  109.  
  110.  
  111. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  112.  
  113. LTRIM:        removes leading blanks from an ASIC or ASILIB string
  114.  
  115. Parameters:   inputstring$
  116.  
  117.               LTRIM removes leading blanks from a string.
  118.               LTRIM does NOT copy the resulting string to a new area: the
  119.               previous string is modified.  LTRIM is handy when using
  120.               ASILIB's I2TOSTR and I4TOSTR subroutines.
  121.  
  122. Example:
  123.  
  124.         oldstring$="   unrealistic example"
  125.         call sub "ltrim", oldstring$
  126.  
  127.  
  128. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  129.  
  130. PUT2:         copy 2 bytes to a far memory block
  131.  
  132. Parameters:   data segment, data offset&, twobytes
  133.  
  134.               Copies 2 bytes to far memory.  Note that in order
  135.               to access the upper 32k of a large data block you need to
  136.               use a long integer as your offset, even with the normal
  137.               ASILIB.LIB library.  Put2 in ASIHUGE.LIB works properly with
  138.               data blocks over 64k.  In either case, the data segment used
  139.               to access the data is the base segment returned by ASILIB's
  140.               ALLOCDOS or other ASILIB subroutines that allocate far
  141.               memory and return a segment address.
  142.  
  143. Example:
  144.  
  145. REM  My program has a data block in far memory and I want to copy
  146. REM  an integer to it
  147.  
  148. REM  50th integer
  149. REM  remember that the first integer is at offset 0
  150.         dataoffset&=98
  151.         call sub "put2", datasegment, dataoffset&, twobytes&
  152.  
  153.  
  154.  
  155. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  156.  
  157. PUT4:         copy 4 bytes to a far memory block
  158.  
  159. Parameters:   data segment, data offset&, fourbytes&
  160.  
  161.               Copy 4 bytes to far memory.  Note that in order
  162.               to access the upper 32k of a large data block you need to
  163.               use a long integer as your offset, even with the normal
  164.               ASILIB.LIB library.  Put4 in ASIHUGE.LIB works properly with
  165.               data blocks over 64k.  In either case, the data segment used
  166.               to access the data is the base segment returned by ASILIB's
  167.               ALLOCDOS or other ASILIB subroutines that allocate far
  168.               memory and return a segment address.
  169.  
  170. Example:
  171.  
  172. REM  My program has a data block in far memory and I want to copy
  173. REM  a long integer to it
  174.  
  175. REM  50th integer
  176. REM  remember that the first integer is at offset 0
  177.         dataoffset&=196
  178.         call sub "put4", datasegment, dataoffset&, fourbytes&
  179.  
  180.  
  181. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  182.  
  183. RTRIM:        removes trailing blanks from an ASIC or ASILIB string
  184.  
  185. Parameters:   inputstring$
  186.  
  187.               RTRIM removes trailing blanks from the end of a string.
  188.               RTRIM does NOT copy the resulting string to a new area: the
  189.               previous string is modified.
  190.  
  191. Example:
  192.  
  193.         oldstring$="unrealistic example      "
  194.         call sub "rtrim", oldstring$
  195.  
  196.  
  197. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  198.  
  199. STRCHR:       find the first matching character in a string, case-sensetive
  200.  
  201. Parameters:   String to search, character to find, character offset
  202.  
  203.               Given an ASIC or ASILIB string, STRCHR finds the first
  204.               character in the string matching a specified character,
  205.               returning the offset of the character in the string.
  206.               If the character offset is returned = -1, the character
  207.               was not found in the string.  Note that the offset of the
  208.               first character in the string = 0.
  209.  
  210. Example:
  211.  
  212. REM  search for the first " " in a string
  213.  
  214.         call sub "strchr", anyoldstring$, ASC(" "), charoffset
  215.         if charoffset = -1 then
  216.            print "Can't find it"
  217.         endif
  218.  
  219. See also:
  220.         STRRCHR, STRICHR
  221.  
  222.  
  223. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  224.  
  225. SORTI2HI:     Sort integer array, highest first
  226. SORTI2LO:     Sort integer array, lowest first
  227. SORTI4HI:     Sort long integer array, highest first
  228. SORTI4LO:     Sort long integer array, lowest first
  229.  
  230. Parameters:   array segment, array offset, array elements
  231.  
  232.               Beginning at the array element at the specified segment:offset
  233.               address, these subroutines sort the specified number of array
  234.               elements.  These subroutines use the Shell sort algorithm.
  235.  
  236. Example:
  237.  
  238. REM  My program is using a long integer array abd I want to sort the
  239. REM  entire array, lowest first.
  240.  
  241.         dim longdata&(1000)
  242.  
  243. REM  program establishes vaules for array elements
  244.         .
  245.         .
  246.         .
  247. REM  get array address
  248.         call sub "asicds", arraysegment
  249.         arrayoffset=VARPTR(longdata&(1))
  250.         arrayelements=1000
  251.         call sub "sorti4lo", arraysegment, arrayoffset, arrayelements
  252.  
  253.  
  254. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  255.  
  256. STRICHR:      find the first matching character in a string, case-insensetive
  257.  
  258. Parameters:   String to search, charater to find, character offset
  259.  
  260.               Given an ASIC or ASILIB string, STRICHR finds the first
  261.               character in the string matching a specified character,
  262.               returning the offset of the character in the string.
  263.               If the character offset is returned = -1, the character
  264.               was not found in the string.  Note that the offset of the
  265.               first character in the string = 0.
  266.  
  267. Example:
  268.  
  269. REM  search for the first "h" or "H" in a string
  270.  
  271.         call sub "strichr", anyoldstring$, ASC("h"), charoffset
  272.         if charoffset = -1 then
  273.            print "Can't find it"
  274.         endif
  275.  
  276. See also:
  277.         STRCHR, STRRCHR
  278.  
  279.  
  280. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  281.              
  282. STRIPCHR:     remove all occurances of a character from a string.
  283.  
  284. Parameters:   inputstring$, character
  285.  
  286.               STRIPCHR removes all occurances of character from the
  287.               input string.
  288.  
  289. Example:
  290.  
  291. REM  remove commas from a numeric string
  292.  
  293.         n$="123,456,789"
  294.         ch=ASC(",")
  295.         call sub "stripchr", n$, ch
  296.  
  297.  
  298. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  299.  
  300. STRISTR:      search string for substring, case-insensetive
  301.  
  302. Parameters:   source string, target string, string offset
  303.  
  304.               Similar to ASIC's INSTR, STRISTR searches either an ASIC
  305.               string or an ASILIB string (source string) for a matching
  306.               substring (target string).  Note that STRISTR, unlike INSTR,
  307.               considers the first character in the source string to be at
  308.               string offset = 0.  If the target string is not found in the
  309.               source string, string offset = -1.  Source string and target
  310.               string may either be an ASIC string or an ASILIB string.
  311.               STRISTR is NOT case-sensetive: "AAA" = "aaa" = "AaA".
  312.  
  313. Example:
  314.         a$="Greased lightning"
  315.         b$="grease"
  316.         call sub "stristr",a$, b$, i
  317.         REM in this example i = 0
  318.  
  319. See also:
  320.         STRSTR, STRRSTR, STRCHR, STRRCHR
  321.  
  322.  
  323.  
  324. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  325.  
  326. STRLEN:       finds length of an ASILIB string
  327.  
  328. Parameters:   stringaddress, stringlength
  329.  
  330.               Determines length of ASIC or ASILIB string.  ASIC strings
  331.               are limited to 80 characters; ASILIB strings may be as long
  332.               as ASIC's DIM statements allow.
  333.  
  334. Example:
  335.  
  336. REM  use ASIC numeric array to create ASILIB string space
  337. REM  later in the program the string has been used and I need to determine
  338. REM  its exact length.
  339.  
  340. REM  allow space for 2000-byte string
  341.         DIM ASILIBstring(1000)
  342.          .
  343.          .
  344.          .
  345.         stringaddress=VARPTR(ASILIBstring(1))
  346.         call sub "strlen", stringaddress, stringlength
  347.  
  348.  
  349. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  350.  
  351. STRLWR:       Convert string to lower case
  352.  
  353. Parameters:   string to convert
  354.  
  355.               STRLWR converts any ASILB or ASIC string to lower case.
  356.  
  357. Example:
  358.  
  359.         a$="ThIs iS A MiXeD-CaSe sTrInG"
  360.         call sub "strlwr", a$
  361.  
  362.  
  363.  
  364. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  365.  
  366. STRREV:      reverses all characters in a string
  367.  
  368. Parameters:  rev$
  369.  
  370.              Reverses all characters in a string, regardless of length.
  371.              works with ASIC strings and ASILIB strings up to 32767 bytes.
  372.  
  373. Example:
  374.  
  375.         a$="123456789"
  376.         call sub "strrev", a$
  377.         print a$              REM  prints '987654321'
  378.  
  379.  
  380.  
  381. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  382.  
  383. STRRCHR:      find the last matching character in a string
  384.  
  385. Parameters:   String to search, charater to find, character offset
  386.  
  387.               Given an ASIC or ASILIB string, STRRCHR finds the last
  388.               character in the string matching a specified character,
  389.               returning the offset of the character in the string.
  390.               If the character offset is returned = -1, the character
  391.               was not found in the string.  Note that the offset of the
  392.               first character in the string = 0.
  393.  
  394. Example:
  395.  
  396. REM  search for the last "\" in a full filename
  397.  
  398.         filename$ = "C:\ASIC\LIB\ASILIB.LIB"
  399.         call sub "strrchr", filename$, ASC("\"), charoffset
  400.         if charoffset = -1 then
  401.            print "Can't find it"
  402.         endif
  403.  
  404. See also:
  405.         STRCHR, STRICHR
  406.  
  407.  
  408.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  409.  
  410. STRRSTR:      search string for last substring
  411.  
  412. Parameters:   source string, target string, string offset
  413.  
  414.               Similar to ASIC's INSTR, STRRSTR searches a source string
  415.               for a matching substring (target string).  STRRSTR searches
  416.               for the LAST occurance of the target in the source.  Note that
  417.               STRRSTR, unlike INSTR, considers the first character in the
  418.               source string to be at string offset = 0.  If the target string
  419.               is not found in the source string, string offset = -1.  Source
  420.               string and target string may either be an ASIC string or an
  421.               ASILIB string.
  422.  
  423. Example:
  424.         a$="Software & Hardware"
  425.         b$="ware"
  426.         call sub "strrstr",a$, b$, i
  427.         REM in this case i = 15
  428.  
  429. See also:
  430.         STRSTR, STRISTR, STRCHR, STRRCHR
  431.  
  432.  
  433.  
  434.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  435.  
  436. STRSTR:       search string for substring
  437.  
  438. Parameters:   source string, target string, string offset
  439.  
  440.               Similar to ASIC's INSTR, STRSTR searches either an ASIC
  441.               string or an ASILIB string (source string) for a matching
  442.               substring (target string).  Note that STRSTR, unlike INSTR,
  443.               considers the first character in the source string to be at
  444.               string offset = 0.  If the target string is not found in the
  445.               source string, string offset = -1.  Source string and target
  446.               string may either be an ASIC string or an ASILIB string.
  447.  
  448. Example:
  449.         a$="Greased lightning"
  450.         b$="light"
  451.         call sub "strstr",a$, b$, i
  452.         REM in this example i = 8
  453.  
  454. See also:
  455.         STRRSTR, STRISTR, STRCHR, STRRCHR
  456.  
  457.  
  458.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  459.  
  460. STRUPR:       Convert string to upper case
  461.  
  462. Parameters:   string to convert
  463.  
  464.               STRUPR converts any ASILB or ASIC string to upper case.
  465.  
  466. Example:
  467.  
  468.         a$="This is a mixed-case string, mostly lower case"
  469.         call sub "strupr", a$
  470.  
  471.  
  472.  
  473.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  474.  
  475. SWAPB:        swaps specified number of bytes
  476.  
  477. Parameters:   (64k library) seg0, offset0, seg1, offset1, bytes
  478.               (huge library) seg0, offset0&, seg1, offset1&, bytes&
  479.  
  480.               SWAPB exchanges data between two regions of memory, region0
  481.               and region1.  You supply the base segment and starting offset
  482.               of each region, and the number of bytes to swap.  Note that
  483.               the huge-data library requires long integer offsets and bytes.
  484.  
  485.               With the 64k-data library, bytes is limited to 65535.  Normally
  486.               ASIC assumes that integers are in the range of -32768 to +32767
  487.               but you may pass long integers up to 65535 using ASIC long
  488.               integers.
  489.  
  490. Example:
  491.  
  492. REM  I want to swap the first 150 elements of arrays a() and b()
  493.         dim a(1000)
  494.         dim b(2000)
  495.  
  496. REM  program fills in the arrays
  497.         .
  498.         .
  499.         .
  500. REM  get ASIC's default data segment
  501.         call sub "ASICDS", defaultseg
  502.         aptr=VARPTR(a(1))
  503.         bptr=VARPTR(b(1))
  504.  
  505. REM  remember that each integer is 2 bytes
  506.         bytes=300
  507.         call sub "swapb", defaultseg, aptr, defaultseg, bptr, bytes
  508.  
  509.  
  510.  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  511.  
  512. TODAY:        Get today's date from system clock
  513.  
  514. Parameters:   No input parameters; returns month, date, year, dayofweek
  515.  
  516.               Returns integer values for month (1 - 12), date of month
  517.               (1 - 31), year (1980 - 2099), and day of week (1 - 7, Sunday
  518.               through Saturday) from the system clock.
  519.  
  520. Example:
  521.  
  522.         call sub "today", month, date, year, dayofweek
  523.  
  524.