home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / PASCAL / STRLIST / STRLIST.DOC < prev    next >
Text File  |  1992-03-11  |  7KB  |  168 lines
  1.           STRLIST.DOC  --  Turbo Pascal 6.0 String List Resource
  2.                         by Wilbert van Leijen
  3.  
  4.                 ***  Released into the Public Domain  ***
  5.  
  6. Description
  7. -----------
  8.  
  9.     STRLIST takes an ASCII file as input and converts it to an object
  10.     file, linkable to a TP 6.0 program.
  11.  
  12.     STRLIST interprets the ASCII file to be a list of strings,
  13.     each on a separate line.
  14.  
  15.     STRLIST aides you to store lists of strings efficiently in your
  16.     application; e.g. error messages or pick-list data.  This utility
  17.     overcomes the drawbacks of storing static data that, when put in
  18.     an array of String[nn] would waste considerable data space, or
  19.     when looked up using a Case statement, would unnecessarily increase
  20.     code size.
  21.  
  22. Usage
  23. -----
  24.  
  25.     Call STRLIST from the DOS command line as follows:
  26.  
  27.     STRLIST source[.LST] object[.OBJ] PublicName [/option]
  28.  
  29.     whereby:
  30.     "source":  file name of the ASCII input file (default extension: .LST)
  31.     "object":  file name of the output file (default extension: .OBJ)
  32.     "PublicName":  identifier (symbolic name) of the string list
  33.     "option":  one of the following:
  34.                /A  make list of ASCIIZ (null-terminated) strings
  35.                /P  make list of length-byte (Pascal) strings
  36.                /S  as with /P, but returned differently
  37.                /9  make list of "$" terminated strings and display them
  38.                    on the screen using DOS call 9
  39.  
  40.      The first three arguments are required.  If "option" is omitted,
  41.      it takes "/P" as the default value.
  42.  
  43. The input file
  44. --------------
  45.  
  46.     The input file must be a plain ASCII file.
  47.     Each line is treated as an entry in the string list and can therefore
  48.     be up to 255 characters long.
  49.     Leading and trailing spaces on a line are stripped from a string.
  50.  
  51.     STRLIST has limited parsing capabilities:
  52.     -  If the first non-blank character is a ";" (semi-colon), STRLIST will
  53.        interpret this as a line containing a comment, and will skip this
  54.        line.
  55.     -  If a line is empty or contains only spaces, it will be ignored and
  56.        no string is added to the list.  Hence, the minimum length of any
  57.        string is 1.
  58.     -  Special characters can be put in a string by prefixing them with
  59.        the "\" (backslash) character.  STRLIST recognises the following
  60.        special characters:
  61.  
  62.        \\      Single backslash
  63.        \A      ASCII 7 (Bell) character
  64.        \B      ASCII 8 (Backspace) character
  65.        \F      ASCII 12 (Form feed) character
  66.        \N      ASCII 10 (Line feed) character
  67.        \R      ASCII 13 (Carriage return) character
  68.        \T      ASCII 9 (Horizontal tab) character
  69.        \V      ASCII 11 (Vertical tab) character
  70.        \Xnn    Hexadecimal character, whereby "nn" must be 2 digits
  71.                Example: \X20 is a space; \X1A means EOF;
  72.                \X00 is the null character
  73.  
  74.     When STRLIST interprets special characters, case is not important.
  75.  
  76.     \x20Example of a string with leading space, \a beep and cr-lf\r\n
  77.  
  78.     ;  This is a comment.  Next line has a string of length 1
  79.     \x00
  80.  
  81. The output file
  82. ---------------
  83.  
  84.     The .OBJ file STRLIST generates is linkable to a TP 6.0 program.
  85.     STRLIST will always export two FAR callable routines; the name
  86.     of these routines depends on what you specify under "PublicName".
  87.     Both routines must be declared FAR.  Failure to do so might
  88.     result in a system crash.
  89.  
  90.     No matter what option you choose, the first exported identifier
  91.     will always be of the format "PublicNameCount".  This function
  92.     returns the number of strings in the list.
  93.  
  94.     Note that since TP 6.0, the declaration in the calling Pascal program
  95.     of all public routines in an .OBJ is not mandatory.  If you wish,
  96.     you can omit the declaration of "PublicNameCount".
  97.  
  98.     Note also that the list is "1-based": if you call "Publicname",
  99.     the first entry in the list is 1 (rather than zero).  For speed's
  100.     sake, "PublicName" does NOT perform any range checking!
  101.  
  102.     /A option (list of ASCIIZ strings):
  103.  
  104.        Function PublicNameCount : Integer; Far; External;
  105.        Function PublicName(i : Integer) : Pointer; Far; External;
  106.  
  107.     PublicName returns a pointer to the i-th ASCIIZ string.
  108.  
  109.     /P option (list of Pascal strings):
  110.  
  111.        Function PublicNameCount : Integer; Far; External;
  112.        Function PublicName(i : Integer) : String; Far; External;
  113.  
  114.     PublicName returns the i-th string in the list.
  115.     As with all Pascal functions returning strings, the result is
  116.     left on the stack.
  117.  
  118.     /S option (list of Pascal strings):
  119.  
  120.        Function PublicNameCount : Integer; Far; External;
  121.        Function PublicName(i : Integer) : Pointer; Far; External;
  122.  
  123.     PublicName returns the address of the i-string in the list.
  124.     One way to call PublicName is:   String(PublicName(i)^);
  125.  
  126.     /9 option (display string using DOS call 9):
  127.  
  128.        Function PublicNameCount : Integer; Far; External;
  129.        Procedure PublicName(i : Integer); Far; External;
  130.  
  131.     PublicName displays the i-th string on the screen.  The output
  132.     is redirectable.
  133.  
  134.     When we ignore the information any object file must pass to the linker,
  135.     the .OBJ file generated by STRLIST consists of these 3 parts:
  136.     -  the code of the exported routines
  137.        These are between 27 and 34 bytes in size
  138.     -  the string list
  139.        The strings are stored contiguously, without "slack bytes"
  140.     -  the index to the string list
  141.        A lookup table, its Pascal declaration would be:
  142.        Array[1..entries] of Word
  143.  
  144.     All data resides in the CODE segment.
  145.  
  146. Limitations
  147. -----------
  148.  
  149.     -  STRLIST can generate an .OBJ file of up to 64kB in size.  Object
  150.        files larger than 65520 bytes cannot be linked with TP 6.0 anyhow.
  151.     -  The maximum number of strings in the list is limited to 8192.
  152.     -  The maximum number of bytes in the whole string list must not
  153.        exceed a number something less than 64000 minus the size of the
  154.        lookup table (2 times the number of strings), since beside the
  155.        loader code, the string list and the index to the string list,
  156.        some space must be set aside for internal .OBJ file housekeeping
  157.        purposes.
  158.     -  When put in an unit, the string list can be safely overlaid,
  159.        provided that any other code in this unit adheres to the guidelines
  160.        regarding overlays, as spelled out in the TP 6.0 Programmer's Guide.
  161.  
  162. Author
  163. ------
  164.  
  165. Wilbert van Leijen   (Wilbert van.Leijen at Fido 2:500/12.10956)
  166. Marathonweg 72-2
  167. 1076 TM Amsterdam
  168. The Netherlands