home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 15 / CD_ASCQ_15_070894.iso / vrac / sk210f.zip / SKYHAWK.DOC < prev    next >
Text File  |  1994-05-24  |  184KB  |  7,088 lines
  1.  
  2.  
  3.  
  4.                            THE SKYHAWK DEVELOPER'S KIT
  5.  
  6.                                         by
  7.  
  8.                                    Bill Madison
  9.  
  10.                         W. G. Madison and Associates, Ltd.
  11.                                13819 Shavano Downs
  12.                                  P.O. Box 780956
  13.                             San Antonio, TX 78278-0956
  14.                                   (512)492-2776
  15.                                   CIS 73240,342
  16.                      Internet bill.madison@lchance.sat.tx.us
  17.  
  18.                     Copyright 1992, 1994 Madison & Associates
  19.                                All Rights Reserved
  20.  
  21.  
  22.                                TERMS AND CONDITIONS
  23.  
  24.              This collection of units with the associated TEST*.*
  25.              files and this .DOC file may be freely used, copied,
  26.              and distributed for non-commercial use, provided only
  27.              that no fee is charged for the package beyond a nominal
  28.              copying charge, and provided that the entire package is
  29.              distributed IN UNALTERED FORM. The sole exception to
  30.              this latter restriction is that bona-fide computer
  31.              clubs and user groups may append text material to the
  32.              documentation file, provided that any material so
  33.              appended is clearly identified as to its source, its
  34.              beginning, and its end.
  35.  
  36.              While no registration or other fee is charged for the
  37.              non-commercial use of the collection, we will willingly
  38.              accept contributions from those wishing to support our
  39.              work. An amount of $10.00 is suggested. Checks should
  40.              be made out to W. G. Madison and Associates, Ltd., and
  41.              forwarded to the above address.
  42.  
  43.              Those wishing to use the SkyHawk collection for commer-
  44.              cial purposes should contact Madison & Associates at
  45.              the above address to arrange terms.
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.                                         i
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.                                      PREFACE
  66.  
  67.              The Cessna SkyHawk is a small single engine airplane. It is
  68.         also the airplane in which I learned to fly. On the day of my
  69.         first solo flight, I felt as the poet must have when he wrote:
  70.  
  71.                      Up, up the long delirious burning blue,
  72.                I've topped the wind-swept heights with easy grace,
  73.                        Where never lark or even eagle flew
  74.                   And while with silent uplifting mind I've trod
  75.                     The high, untrespassed sanctity of space,
  76.                    Put out my hand and touched the face of God!
  77.  
  78.                                                 John Gillespie Magee, Jr.
  79.                                                             "High Flight"
  80.  
  81.  
  82.              As the SkyHawk Developer's Kit was being written and began
  83.         to be used at Madison and Associates, we found that we felt some-
  84.         what the same sense of freedom and mastery of the environment
  85.         when using the library as that which I had felt during my first
  86.         solo. We sincerely hope that you will share these feelings with
  87.         us.
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.                                         ii
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.                                   INTRODUCTION
  124.  
  125.              The SkyHawk Developer's Kit is a collection of units compil-
  126.         able under Borland's Turbo PASCAL 5 and above. Some of the func-
  127.         tionalities are to be found in other collections but are reimple-
  128.         mented here in an extended form or to provide a different ap-
  129.         proach. Some are unique to the SkyHawk collection. All are pro-
  130.         vided with the goal of removing the necessity of "reinventing the
  131.         wheel" during the development process.
  132.  
  133.              The collection is dynamic, in the sense that it is being
  134.         constantly augmented by the addition of new units and the im-
  135.         provement of the existing ones. We welcome all suggestions for
  136.         additional units and/or routines, bug reports, and general com-
  137.         ments. Just drop us a note at the address above. Or call us
  138.         (9:00am - 5:00pm Central time) or drop us an EMAIL message on
  139.         CompuServe or Internet using the appropriate address shown above.
  140.  
  141.              The SkyHawk collection depends on the TurboProfessional
  142.         5.22+ library from TurboPower Software. Most of the units were
  143.         initially developed while we were working on a series of projects
  144.         for which conversion to an object oriented design was not econom-
  145.         ically feasible. Thus the dependence on TurboProfessional rather
  146.         than ObjectProfessional. In most cases, however, you will find
  147.         that conversion to object oriented code will be trivial. When
  148.         time permits, Madison & Associates intends to convert the entire
  149.         collection to objects and to provide both.
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.                                        iii
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.                              WHAT'S IN THE LIBRARY?
  182.  
  183.         ____________________________
  184.         SHCLRDEF
  185.              ShClrDef is a unit which is serves two functions;
  186.  
  187.             *  It defines constants such that each normally allowable
  188.                combination of text forground and background colors can be
  189.                specified by name; e.g., YellowOnBlack, MagentaOnLtGray.
  190.  
  191.             *  It interfaces a function which displays a "screen selec-
  192.                tion panel", allowing the user to move a special cursor to
  193.                a desired forground/background color combination and then
  194.                select that combination by pressing <Ret>, returning the
  195.                attribute value. This function is particularly useful in
  196.                the construction of installation programs. The end user
  197.                can be permitted to select color combinations for any par-
  198.                ticular screen element, which can then be displayed.
  199.  
  200.              Two additional utility functions are interfaced.
  201.  
  202.             *  A function which, given an attribute value as input,
  203.                returns a string containing the attribute name; e.g.,
  204.  
  205.                                      ColorName($1E)
  206.  
  207.                returns 'YellowOnBlue', and
  208.  
  209.             *  A function which, given a valid color name, returns the
  210.                byte value; e.g.,
  211.  
  212.                                 Cstr2Byte('YellowOnblue')
  213.  
  214.                returns the byte value $1E.
  215.  
  216.  
  217.         ____________________________
  218.         SHCMDLIN
  219.              Developers of command line driven programs constantly face
  220.         the problem of providing acceptable levels of syntax flexibility
  221.         on the command line coupled with a minimum level of labor in
  222.         coding the command line analyzer. This unit, ShCmdLin, removes
  223.         all of the heartburn associated with the coding, while providing
  224.         a maximum level of syntactic flexibility to the user.
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.                                         iv
  233.  
  234.  
  235.  
  236.         ____________________________
  237.         SHCMPLX
  238.              ShCmplx is a complex arithmetic unit. It provides for the
  239.         basic binary arithmetic functions (addition, subtraction, multi-
  240.         plication, division), plus the raising of a complex number to a
  241.         real power. Conversion functions are provided to convert between
  242.         a complex number represented in Cartesian form and one repre-
  243.         sented in polar form. Finally, provision is made to convert a
  244.         complex number in Cartesian form to a string; or a complex in
  245.         polar form to a string expressing the angle either in degrees or
  246.         in radians.
  247.  
  248.  
  249.         ____________________________
  250.         SHCRCCHK
  251.              When the DOS COPY command is used, no true read-after-write
  252.         verification is performed. The only way to assure that the re-
  253.         cording was correct is to read the file after writing, and com-
  254.         pare the output file, byte for byte, with the input. For very
  255.         long files this can result in unacceptable delays.
  256.  
  257.              A reasonable compromise between speed and reliability is to
  258.         calculate the cyclic redundancy check (CRC) word of the input
  259.         file as it is being copied, and then on completion of the copying
  260.         operation, read back the output file and calculate its CRC. If
  261.         the two compare and the files are of the same size, the probabil-
  262.         ity that the two files differ is extremely small.
  263.  
  264.              ShCrcChk is a unit which interfaces two functions, both of
  265.         which calculate the CRC16 of a file whose name is provided as a
  266.         string parameter. One of the functions simply calculates the CRC
  267.         and returns it; the other in addition copies the input file to
  268.         another file whose name is provided as a second string parameter.
  269.  
  270.  
  271.         ____________________________
  272.         SHERRMSG
  273.              ShErrMsg is a unit which installs an exit procedure in Turbo
  274.         PASCAL programs. This exit procedure displays a short explanatory
  275.         message whenever a program terminates abnormally; i.e., whenever
  276.         it returns to DOS with a return code other than zero.
  277.  
  278.              It also interfaces replacements for the HALT and RUNERROR
  279.         procedures in Turbo PASCAL's SYSTEM unit. These procedures per-
  280.         form functions not provided by PASCAL's normal termination
  281.         procedures.
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.                                         v
  291.  
  292.  
  293.  
  294.         ____________________________
  295.         SHFINANC
  296.              ShFinanc is a higher level unit than most of the others in
  297.         this package. Its inclusion in this package is justified, how-
  298.         ever, by the need which we have frequently encountered to include
  299.         compound interest and annuity calculations in various systems
  300.         which we have implemented.
  301.  
  302.              The functions include compound present value and amount, and
  303.         annuity present value and amount for both ordinary annuities and
  304.         annuities due. Also included are functions returning the number
  305.         of payments given the interest rate and annuity present value, as
  306.         well as a function returning the interest rate of an annuity
  307.         given the number of payments and present value.
  308.  
  309.  
  310.         ____________________________
  311.         SHLIST
  312.              Lists, rings, and stacks are among the most common data
  313.         structures used (after arrays). They are also probably among the
  314.         worst offenders when it comes to "re-inventing the wheel." Many
  315.         programmers build special purpose list manipulation routines each
  316.         time a list is needed. Obviously, a generic list manipulation
  317.         package is a valuable addition to the available "bag of tricks."
  318.  
  319.              ShList contains all of the routines necessary to establish
  320.         and manipulate singly and doubly linked lists, rings, and stacks.
  321.         The data associated with any given list, ring, or stack can be
  322.         any standard or user defined data type. The structure of the data
  323.         can change, but the total length of the data must remain con-
  324.         stant. Thus, for example, variant records can be used.
  325.  
  326.  
  327.         ____________________________
  328.         SHLNGSTR
  329.              ShLngStr is a unit which provides the ability to manipulate
  330.         long strings (up to 65517 characters in length) using Turbo
  331.         PASCAL.
  332.  
  333.              ShLngStr stores all of its string data on the heap. When a
  334.         variable is declared to be of type LongString, this declaration
  335.         establishes only a pointer in the data segment. The LongString
  336.         must then be initialized prior to use. This initialization estab-
  337.         lishes a maximum allowable string length, which may now vary from
  338.         one LongString to the next. Only the amount of heap space requir-
  339.         ed for the initialized maximum length is used. In this respect,
  340.         the analog of a string declaration of, for example, "var
  341.         string[127];" has been preserved. Any of the procedures and
  342.         functions in this unit will observe the "declared" maximum
  343.         length, and will adjust their behavior appropriately.
  344.  
  345.  
  346.  
  347.  
  348.                                         vi
  349.  
  350.  
  351.  
  352.         ____________________________
  353.         SHUTILPK
  354.              ShUtilPk is a collection of miscellaneous utility proce-
  355.         dures, generally lower level than those in the other units of
  356.         this collection.
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.                                        vii
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.                                 UNIT DEPENDENCIES
  414.  
  415.              As mentioned above, the SkyHawk collection is dependent upon
  416.         the TurboProfessional-5.0 library published by TurboPower Soft-
  417.         ware. There are also dependencies within the SkyHawk collection
  418.         itself. The following matrix shows these dependencies.
  419.  
  420.  
  421.                                D  S  S  S  T  T  T  T  T  T  T
  422.                                O  H  H  H  P  P  P  P  P  P  P
  423.                                S  E  L  U  8  C  D  I  M  S  W
  424.                                |  R  I  T  0  R  O  N  E  T  I
  425.                     +--uses--> |  R  S  I  8  T  S  L  M  R  N
  426.                     |          |  M  T  L  7  |  |  I  C  I  D
  427.                     |          |  S  |  P  |  |  |  N  H  N  O
  428.                     |          |  G  |  K  |  |  |  E  K  G  W
  429.                     |          |  |  |  |  |  |  |  |  |  |  |
  430.                     ShClrDef   -  -  -  -  -  X  -  -  -  -  X
  431.                     ShCmdLin   X  -  X  X  -  -  -  -  -  -  -
  432.                     ShCmplx    -  -  -  -  -  -  -  -  -  -  -
  433.                     ShCrcChk   X  -  -  -  -  -  -  -  -  -  -
  434.                     ShDatPk    X  -  -  -  -  -  -  -  -  -  -
  435.                     ShErrMsg   -  -  -  -  -  -  -  -  -  -  -
  436.                     ShFinanc   -  X  -  X  X  X  -  -  -  X  -
  437.                     ShList     -  -  -  -  -  -  -  X  X  X  -
  438.                     ShLngStr   -  -  -  -  -  -  -  X  X  X  -
  439.                     ShUtilPk   -  -  -  -  -  -  X  -  -  X  -
  440.  
  441.                              Unit Dependencies Matrix
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.                                        viii
  465.                                                          05/24/94 01:33pm
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.                                     ShClrDef
  473.  
  474.                              A Color Definition Unit
  475.  
  476.  
  477.  
  478.         INTRODUCTION
  479.              ShClrDef is a unit which serves two functions;
  480.  
  481.             *  It defines constants such that each normally allowable
  482.                combination of text forground and background colors can be
  483.                specified by name; e.g., YellowOnBlack, MagentaOnLtGray.
  484.  
  485.             *  It interfaces a function which displays a "screen selec-
  486.                tion panel", allowing the user to move a special cursor to
  487.                a desired forground/background color combination and then
  488.                select that combination by pressing <Ret>. The attribute
  489.                value is returned.
  490.  
  491.              Two additional utility functions are interfaced.
  492.  
  493.             *  A function which, given an attribute value as input,
  494.                returns a string containing the attribute name; e.g.,
  495.  
  496.                                      ColorName($1E)
  497.  
  498.                returns 'YellowOnBlue', and
  499.  
  500.             *  A function which, given a valid color name, returns the
  501.                byte value; e.g.,
  502.  
  503.                                 Cstr2Byte('YellowOnblue')
  504.  
  505.                returns the byte value $1E.
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.                                   ShClrDef  1-1
  524.  
  525.  
  526.  
  527.         INTERFACED ELEMENTS
  528.  
  529.         Constants
  530.         =========
  531.              {Black text}                    {Blue text}
  532.              BlackOnBlack       = $00;       BlueOnBlack        = $01;
  533.              BlackOnBlue        = $10;       BlueOnBlue         = $11;
  534.              BlackOnGreen       = $20;       BlueOnGreen        = $21;
  535.              BlackOnCyan        = $30;       BlueOnCyan         = $31;
  536.              BlackOnRed         = $40;       BlueOnRed          = $41;
  537.              BlackOnMagenta     = $50;       BlueOnMagenta      = $51;
  538.              BlackOnBrown       = $60;       BlueOnBrown        = $61;
  539.              BlackOnLtGray      = $70;       BlueOnLtGray       = $71;
  540.  
  541.              {Green text}                    {Cyan text}
  542.              GreenOnBlack       = $02;       CyanOnBlack        = $03;
  543.              GreenOnBlue        = $12;       CyanOnBlue         = $13;
  544.              GreenOnGreen       = $22;       CyanOnGreen        = $23;
  545.              GreenOnCyan        = $32;       CyanOnCyan         = $33;
  546.              GreenOnRed         = $42;       CyanOnRed          = $43;
  547.              GreenOnMagenta     = $52;       CyanOnMagenta      = $53;
  548.              GreenOnBrown       = $62;       CyanOnBrown        = $63;
  549.              GreenOnLtGray      = $72;       CyanOnLtGray       = $73;
  550.  
  551.              {Red text}                      {Magenta text}
  552.              RedOnBlack         = $04;       MagentaOnBlack     = $05;
  553.              RedOnBlue          = $14;       MagentaOnBlue      = $15;
  554.              RedOnGreen         = $24;       MagentaOnGreen     = $25;
  555.              RedOnCyan          = $34;       MagentaOnCyan      = $35;
  556.              RedOnRed           = $44;       MagentaOnRed       = $45;
  557.              RedOnMagenta       = $54;       MagentaOnMagenta   = $55;
  558.              RedOnBrown         = $64;       MagentaOnBrown     = $65;
  559.              RedOnLtGray        = $74;       MagentaOnLtGray    = $75;
  560.  
  561.              {Brown text}                    {Light Gray text}
  562.              BrownOnBlack       = $06;       LtGrayOnBlack      = $07;
  563.              BrownOnBlue        = $16;       LtGrayOnBlue       = $17;
  564.              BrownOnGreen       = $26;       LtGrayOnGreen      = $27;
  565.              BrownOnCyan        = $36;       LtGrayOnCyan       = $37;
  566.              BrownOnRed         = $46;       LtGrayOnRed        = $47;
  567.              BrownOnMagenta     = $56;       LtGrayOnMagenta    = $57;
  568.              BrownOnBrown       = $66;       LtGrayOnBrown      = $67;
  569.              BrownOnLtGray      = $76;       LtGrayOnLtGray     = $77;
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.                                   ShClrDef  1-2
  582.  
  583.  
  584.  
  585.              {Dark Gray text}                {Light Blue text}
  586.              DkGrayOnBlack      = $08;       LtBlueOnBlack      = $09;
  587.              DkGrayOnBlue       = $18;       LtBlueOnBlue       = $19;
  588.              DkGrayOnGreen      = $28;       LtBlueOnGreen      = $29;
  589.              DkGrayOnCyan       = $38;       LtBlueOnCyan       = $39;
  590.              DkGrayOnRed        = $48;       LtBlueOnRed        = $49;
  591.              DkGrayOnMagenta    = $58;       LtBlueOnMagenta    = $59;
  592.              DkGrayOnBrown      = $68;       LtBlueOnBrown      = $69;
  593.              DkGrayOnLtGray     = $78;       LtBlueOnLtGray     = $79;
  594.  
  595.              {Light Green Text}              {Light Cyan text}
  596.              LtGreenOnBlack     = $0A;       LtCyanOnBlack      = $0B;
  597.              LtGreenOnBlue      = $1A;       LtCyanOnBlue       = $1B;
  598.              LtGreenOnGreen     = $2A;       LtCyanOnGreen      = $2B;
  599.              LtGreenOnCyan      = $3A;       LtCyanOnCyan       = $3B;
  600.              LtGreenOnRed       = $4A;       LtCyanOnRed        = $4B;
  601.              LtGreenOnMagenta   = $5A;       LtCyanOnMagenta    = $5B;
  602.              LtGreenOnBrown     = $6A;       LtCyanOnBrown      = $6B;
  603.              LtGreenOnLtGray    = $7A;       LtCyanOnLtGray     = $7B;
  604.  
  605.              {Light Red text}                {Light Magenta text}
  606.              LtRedOnBlack       = $0C;       LtMagentaOnBlack   = $0D;
  607.              LtRedOnBlue        = $1C;       LtMagentaOnBlue    = $1D;
  608.              LtRedOnGreen       = $2C;       LtMagentaOnGreen   = $2D;
  609.              LtRedOnCyan        = $3C;       LtMagentaOnCyan    = $3D;
  610.              LtRedOnRed         = $4C;       LtMagentaOnRed     = $4D;
  611.              LtRedOnMagenta     = $5C;       LtMagentaOnMagenta = $5D;
  612.              LtRedOnBrown       = $6C;       LtMagentaOnBrown   = $6D;
  613.              LtRedOnLtGray      = $7C;       LtMagentaOnLtGray  = $7D;
  614.  
  615.              {Yellow text}                   {White text}
  616.              YellowOnBlack      = $0E;       WhiteOnBlack       = $0F;
  617.              YellowOnBlue       = $1E;       WhiteOnBlue        = $1F;
  618.              YellowOnGreen      = $2E;       WhiteOnGreen       = $2F;
  619.              YellowOnCyan       = $3E;       WhiteOnCyan        = $3F;
  620.              YellowOnRed        = $4E;       WhiteOnRed         = $4F;
  621.              YellowOnMagenta    = $5E;       WhiteOnMagenta     = $5F;
  622.              YellowOnBrown      = $6E;       WhiteOnBrown       = $6F;
  623.              YellowOnLtGray     = $7E;       WhiteOnLtGray      = $7F;
  624.  
  625.  
  626.  
  627.         Types
  628.         =====
  629.              Orientation = (Vertical, Horizontal);
  630.  
  631.              Determines whether the color selection panel displayed by
  632.         SelectColors is presented with its long dimension oriented
  633.         vertically or horizontally on the screen.
  634.  
  635.  
  636.  
  637.  
  638.  
  639.                                   ShClrDef  1-3
  640.  
  641.  
  642.  
  643.         Routines
  644.         ========
  645.         ____________________________
  646.         SELECTCOLORS
  647.  
  648.         Declaration:
  649.              function SelectColors(Row, Col, BegAttr : byte;
  650.                               CpFrameChars      : FrameArray;
  651.                               Orient            : Orientation;
  652.                               ErasePanelOnExit,
  653.                               EraseCursorOnExit,
  654.                               WrapCursor        : boolean;
  655.                               Header  : string) : byte;
  656.  
  657.  
  658.         Purpose:
  659.              Displays a color selection panel, permitting the user to
  660.         move a special cursor using the arrow keys and select a desired
  661.         color combination using the <CR> key.
  662.  
  663.  
  664.         Comments:
  665.              The user navigates the panel with the arrow keys and selects
  666.         the desired color combination by pressing <CR>. The attribute
  667.         byte value currently under the cursor will be returned. The user
  668.         can also press <INS>, which will return a function value of $FF,
  669.         and by convention, should be taken to indicate that the currently
  670.         selected attribute value is to be unchanged. Additionally, the
  671.         user can press <ESC>, returning a function value of $FE, which by
  672.         convention should be taken to indicate that the current color
  673.         selection run is completed. Finally, a return of $FD indicates
  674.         that the user has pressed the <F1> key either alone or in
  675.         combination with one of the shift-type keys (<L-SHIFT>, <R-
  676.         SHIFT>, <CTRL>, or <ALT>), and by convention indicates that the
  677.         user is requesting help.
  678.  
  679.              The function performs the following actions:
  680.  
  681.             *  Displays a 16x8 panel of text colors with the window
  682.                coordinates of the upper left corner at coordinates X=Col,
  683.                Y=Row. If Col=255 the right edge of the panel will be at
  684.                the extreme right edge of the screen. Similarly, if
  685.                Row=255 the bottom edge of the panel will be at the bottom
  686.                of the screen.
  687.  
  688.             *  The attribute at which the cursor will be initially placed
  689.                is at BegAttr.
  690.  
  691.             *  The color panel will be framed using the characters
  692.                specified in CpFrameChars.
  693.  
  694.  
  695.  
  696.  
  697.                                   ShClrDef  1-4
  698.  
  699.  
  700.  
  701.             *  The orientation of the long dimension of the selection
  702.                panel is determined as specified by Orient.
  703.  
  704.             *  ErasePanelOnExit determines whether the panel is erased or
  705.                preserved on the screen when SelectColors returns to the
  706.                caller. The panel is always disposed, and its heap space
  707.                reclaimed.
  708.  
  709.             *  EraseCursorOnExit is only effective if ErasePanelOnExit is
  710.                false. If the panel is to be preserved between calls to
  711.                SelectColors, EraseCursor determines whether the or not
  712.                the cursor will continue to be displayed along with the
  713.                panel.
  714.  
  715.             *  WrapCursor determines whether the cursor will wrap both
  716.                horizontally and vertically. True allows the cursor to
  717.                wrap; False inhibits further cursor movement when a window
  718.                edge is reached.
  719.  
  720.             *  Header is the header line which will be displayed on the
  721.                panel. It can be supplied as an empty string (''), in
  722.                which case no header will be displayed.
  723.  
  724.             *  The function returns a normal text attribute byte, with
  725.                the following exceptions:
  726.  
  727.                Return         Explanation
  728.                ------         -----------
  729.                $FF            <INS> was pressed by the user. Leave the
  730.                              current value unchanged.
  731.                $FE            <ESC> was pressed by the user. Accept all
  732.                              current values and consider the run
  733.                              completed.
  734.                $FD            <F1> was pressed by the user. Provide a
  735.                              HELP screen or message.
  736.                $F0            Error in MakeWindow
  737.                $F1            Error in DisplayWindow
  738.  
  739.  
  740.  
  741.  
  742.  
  743.  
  744.  
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.                                   ShClrDef  1-5
  756.  
  757.  
  758.  
  759.         ____________________________
  760.         COLORNAME
  761.  
  762.         Declaration:
  763.              function ColorName(Attr  : byte) : string;
  764.  
  765.         Purpose:
  766.              Given a text attribute byte, ColorName returns the attribute
  767.         color name as defined above; e.g., ColorName($1E) will return
  768.         'YellowOnBlue'.
  769.  
  770.         Comment:
  771.              If a byte value is passed which does not correspond to a
  772.         valid text attribute, an empty string is returned.
  773.  
  774.         Example:
  775.  
  776.         See also
  777.              Cstr2Byte
  778.  
  779.  
  780.         ____________________________
  781.         CSTR2BYTE
  782.  
  783.         Declaration:
  784.              function Cstr2Byte(Cstr : string) : byte;
  785.  
  786.         Purpose:
  787.              Given a string containing a valid color name, returns the
  788.         corresponding byte value; e.g., Cstr2Byte('YellowOnBlue') returns
  789.         $1E.
  790.  
  791.         Comment:
  792.              If an invalid color name string is passed, Cstr2Byte will
  793.         return $00.
  794.  
  795.         Example:
  796.  
  797.         See also:
  798.              ColorName
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.                                   ShClrDef  1-6
  814.                                                          05/24/94 01:33pm
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.                                     ShCmdLin
  822.  
  823.                            A Command Line Parsing Unit
  824.  
  825.  
  826.         INTRODUCTION
  827.              Developers of command line driven programs constantly face
  828.         the problem of providing acceptable levels of syntax flexibility
  829.         on the command line coupled with a minimum level of labor in
  830.         coding the command line analyzer. This unit, ShCmdLin, removes
  831.         all of the heartburn associated with the coding, while providing
  832.         a maximum level of syntactic flexibility to the user.
  833.  
  834.              ShCmdLin contains all those routines necessary not only to
  835.         parse the command line but also to determine the current DOS
  836.         switch lead-in character and, if desired, change it. Further, the
  837.         parsing routine allows a set of characters (rather than just a
  838.         single character) to be defined as acceptable for switch lead-in.
  839.         It further permits a set of characters to serve as the switch
  840.         value lead-in. Thus, for example, one could use ['/','-'] for
  841.         switch lead-in, and [':','='] for value lead-in. This would have
  842.         the effect of making the following two command tails functionally
  843.         identical:
  844.  
  845.                      /Alpha-Bravo=27.9-Charlie:14/Delta=Echo
  846.                      -Alpha/Bravo:27.9/Charlie=14-Delta:Echo
  847.  
  848.              For each switch, the parsing routine prepares one variant
  849.         record (see below, the definition of the SwRec type) and appends
  850.         it to a list, from which it may be retrieved as required. Apply-
  851.         ing this to the example above, the following will be true.
  852.  
  853.              In each case in the example, the NAME of the first switch is
  854.         Alpha, and it has no assigned value (switches lacking an assigned
  855.         value will be returned as a string-type, but with an empty string
  856.         as the value); the NAME of the second switch is Bravo and it has
  857.         a real-type value of 27.9; the NAME of the third is Charlie and
  858.         it has an integer-type value of 14; and the NAME of the fourth is
  859.         Delta and it has a string-type value of 'Echo'.
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.                                   ShCmdLin  2-1
  873.  
  874.  
  875.  
  876.                                !!CAUTIONARY NOTE!!
  877.  
  878.              The characters ^C (<ETX> or #3), ^M (<CR> or #13), and
  879.              ^[ (<ESC> or #27) cannot be embedded in a command tail.
  880.              The parser, however, can be used to parse arbitrary
  881.              strings; not just command tails. THESE ARBITRARY
  882.              STRINGS MUST NOT CONTAIN ANY OF THE THREE INDICATED
  883.              CHARACTERS. These characters are RESERVED for internal
  884.              use by the parser.
  885.  
  886.                            !!END OF CAUTIONARY NOTE!!
  887.  
  888.  
  889.                                !!CAUTIONARY NOTE!!
  890.  
  891.              MARK/RELEASE must not be used for heap management when
  892.              using this unit. GETMEM/FREEMEM or NEW/DISPOSE must be
  893.              used instead.
  894.  
  895.                            !!END OF CAUTIONARY NOTE!!
  896.  
  897.  
  898.         INTERFACED ELEMENTS
  899.  
  900.         Types
  901.         =====
  902.              ValueType = (VtStr, VtReal, VtInt);
  903.              SwRec     = record
  904.                            Name  : string;
  905.                            case SwVal  : ValueType of
  906.                              VtStr : (StrVal : string);
  907.                              VtReal: (RealVal: Float);
  908.                              VtInt : (IntVal : integer);
  909.                            end; {SwRec}
  910.              CharSet = Set of Char;
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.                                   ShCmdLin  2-2
  931.  
  932.  
  933.  
  934.         Routines
  935.         ========
  936.         ____________________________
  937.         CLCLOSE
  938.  
  939.         Declaration:
  940.              procedure ClClose;
  941.  
  942.         Purpose:
  943.              Closes the internal data structures and frees the space
  944.         associated with the command line switch list.
  945.  
  946.         Comments:
  947.              If GetSwitch is used to retrieve switch values, ClClose
  948.         should be called following retrieval of the last switch. If
  949.         PopSwitch is used, ClClose need not be called.
  950.  
  951.         Examples:
  952.              See the files TESTCL.PAS and CLTEST.BAT
  953.  
  954.         See also:
  955.              ClInit    GetSwitch      PopSwitch
  956.  
  957.  
  958.         ____________________________
  959.         CLINIT
  960.  
  961.         Declaration:
  962.              procedure ClInit;
  963.  
  964.         Purpose:
  965.              Initializes the internal data structures used to store the
  966.         command line switch list.
  967.  
  968.         Comments:
  969.              ClInit MUST be called prior to any of the other Cl routines.
  970.  
  971.         Examples:
  972.              See the files TESTCL.PAS and CLTEST.BAT
  973.  
  974.         See also:
  975.              ClClose
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.                                   ShCmdLin  2-3
  989.  
  990.  
  991.  
  992.         ____________________________
  993.         CLPARSE
  994.  
  995.         Declaration:
  996.              procedure ClParse(StrPtr : Pointer; StrOnly : Boolean;
  997.                       LeadIn, ValDelim : CharSet; var Err : Integer);
  998.  
  999.         Purpose:
  1000.              To parse a command tail (or other string of similar form),
  1001.         producing a list of switch names and associated values which can
  1002.         then be retrieved using the GetSwitch or PopSwitch functions.
  1003.  
  1004.         Comments:
  1005.              Parsing is accomplished by invoking the procedure ClParse
  1006.         with five parameters:
  1007.  
  1008.            1.  StrPtr of type Pointer is used to point to the string to
  1009.                be parsed. If StrPtr is NIL, the command tail will be
  1010.                parsed.
  1011.  
  1012.            2.  StrOnly of type Boolean is used to determine if switch
  1013.                values of type String are to be forced, regardless of the
  1014.                form of the value. StrOnly = True forces String values.
  1015.  
  1016.            3.  LeadIn of type CharSet is used to identify the set of
  1017.                characters used to mark the beginning of a switch. It is
  1018.                suggested that LeadIn be set to [ ReadSwCh ]. The weakest
  1019.                condition used should be that the expression ( ReadSwCh in
  1020.                LeadIn ) be TRUE.
  1021.  
  1022.            4.  ValDelim of type CharSet is used to specify the set of
  1023.                characters which may be used to separate the switch name
  1024.                from the switch value.
  1025.  
  1026.            5.  Err of type Integer is used to return error conditions.
  1027.  
  1028.              Prior to the call to ClParse, a call MUST be made to ClInit.
  1029.  
  1030.              The procedure prepares a list of records, each record con-
  1031.         taining the name and value of one command line switch. These
  1032.         records will require 536 bytes of heap space per switch.
  1033.  
  1034.              All switches (with the optional exception of the first) are
  1035.         preceded by one of the members of the set LeadIn.
  1036.  
  1037.              Switches may take values of type Float, LongInt, or String.
  1038.         In each case, the switch value is separated from the switch name
  1039.         by one of the characters specified in the parameter ValDelim.
  1040.         Switches which do not take on any explicit value will be returned
  1041.         as type String, with a value length of zero.
  1042.  
  1043.  
  1044.  
  1045.  
  1046.                                   ShCmdLin  2-4
  1047.  
  1048.  
  1049.  
  1050.              Assuming StrOnly = FALSE in the call, switches whose VALUE
  1051.         is intended to be of type String, but with a FORM qualifying as a
  1052.         numeric, must be enclosed in either single or double quotation
  1053.         marks. Otherwise, the value will be returned as a Float or Long-
  1054.         Int, as determined by its specific syntax.
  1055.  
  1056.              Additionally, any blanks included in String values will be
  1057.         packed out unless the value is included in quotation marks.
  1058.         Further, if single quote marks are to be included as part of a
  1059.         string value, then double quotes must be used to define the
  1060.         value; and vice versa.
  1061.  
  1062.              Finally, blanks may be freely entered in the command tail to
  1063.         improve readability (except as noted above).
  1064.  
  1065.         Error Returns:
  1066.              The error parameter returns one of three values:
  1067.                   0 --> No error encountered.
  1068.                   1 --> Unbalanced single quotes encountered.
  1069.                   2 --> Unbalanced double quotes encountered.
  1070.                   3 --> Insufficient heap space to store the switch list.
  1071.  
  1072.              Assuming the error return is 0, the list of switches has
  1073.         been successfully prepared and is available for retrieval using
  1074.         GetSwitch or PopSwitch.
  1075.  
  1076.              If GetSwitch has been used to retrieve the switch values,
  1077.         ClClose should be called to release the heap space associated
  1078.         with the list of switches. This is not necessary if PopSwitch has
  1079.         been used for retrieval (but it won't hurt anything, either).
  1080.  
  1081.         Examples:
  1082.              See the files TESTCL.PAS and CLTEST.BAT
  1083.  
  1084.         See also:
  1085.              ClInit    ClClose   GetSwitch      PopSwitch
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.                                   ShCmdLin  2-5
  1105.  
  1106.  
  1107.  
  1108.         ____________________________
  1109.         GETSWITCH
  1110.  
  1111.         Declaration:
  1112.              function GetSwitch(var Y : SwRec) : boolean;
  1113.  
  1114.         Purpose:
  1115.              Retrieves the next switch record in the list of switch
  1116.         records prepared by ClParse. Returns FALSE if no more.
  1117.  
  1118.         Comments:
  1119.              The list of switches can, if desired, be treated as a ring
  1120.         (thus enabling switches to be read more than once). If GetSwitch
  1121.         is called again after returning a function value of FALSE, read-
  1122.         ing will recommence at the top of the list.
  1123.  
  1124.              Use of GetSwitch and PopSwitch should not be combined. If
  1125.         they are both used on the same pass through the command tail,
  1126.         orphan blocks (blocks which have no associated pointer, and thus
  1127.         cannot be accessed, retrieved, or disposed) will result on the
  1128.         heap.
  1129.  
  1130.         Examples:
  1131.              See the file TESTCL.PAS
  1132.  
  1133.         See also:
  1134.              PopSwitch
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.                                   ShCmdLin  2-6
  1163.  
  1164.  
  1165.  
  1166.         ____________________________
  1167.         POPSWITCH
  1168.  
  1169.         Declaration:
  1170.              function PopSwitch(var Y : SwRec) : boolean;
  1171.  
  1172.         Purpose:
  1173.              Retrieves the next switch record in the list of switch
  1174.         records prepared by ClParse, and frees its heap space. Returns
  1175.         FALSE if no more.
  1176.  
  1177.         Comments:
  1178.              Since PopSwitch frees the heap space associated with each
  1179.         switch after it has been returned to the caller, it is not
  1180.         necessary to call ClClose after reaching the end of the switch
  1181.         list. For the same reason, however, the switch list cannot be
  1182.         treated as a ring (that is, the switch list cannot be reread
  1183.         after the end has been reached).
  1184.  
  1185.              Use of GetSwitch and PopSwitch should not be combined. If
  1186.         they are both used on the same pass through the command tail,
  1187.         orphan blocks (blocks which have no associated pointer, and thus
  1188.         cannot be accessed, retrieved, or disposed) will result on the
  1189.         heap.
  1190.  
  1191.         Examples:
  1192.              See the file TESTCL.PAS
  1193.  
  1194.         See also:
  1195.              GetSwitch
  1196.  
  1197.  
  1198.  
  1199.  
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.                                   ShCmdLin  2-7
  1221.  
  1222.  
  1223.  
  1224.         ____________________________
  1225.         READSWCH
  1226.  
  1227.         Declaration:
  1228.              function ReadSwCh : char;
  1229.  
  1230.         Purpose:
  1231.              Returns the current DOS switch lead-in character.
  1232.  
  1233.         Comments:
  1234.              DOS normally recognizes the character '/' as the switch
  1235.         lead-in. DOS also permits this character to be changed. In par-
  1236.         ticular, some installations whose personnel are more comfortable
  1237.         in a UNIX-like environment have changed the switch lead-in to
  1238.         '-'. The ReadSwCh function permits the programmer to assure that
  1239.         the character which DOS recognizes will be included in the set of
  1240.         permissible lead-in characters which the parser will also
  1241.         recognize.
  1242.  
  1243.         Examples:
  1244.              See the file TESTCL.PAS
  1245.  
  1246.         See also:
  1247.              SetSwCh
  1248.  
  1249.  
  1250.         ____________________________
  1251.         SETSWCH
  1252.  
  1253.         Declaration:
  1254.              procedure SetSwCh(C : char);
  1255.  
  1256.         Purpose:
  1257.              Sets the DOS switch lead-in character to C.
  1258.  
  1259.         Comments:
  1260.              THIS PROCEDURE MODIFIES THE CURRENTLY RUNNING COPY OF DOS.
  1261.         Therefore it should only be used in exceptional circumstances,
  1262.         and with great caution. Otherwise the users could be in for quite
  1263.         a surprise! It is included here primarily for completeness.
  1264.  
  1265.         Examples:
  1266.                                   SetSwCh('+');
  1267.  
  1268.         will change the switch lead-in to '+'.
  1269.  
  1270.         See also:
  1271.              ReadSwCh
  1272.  
  1273.  
  1274.  
  1275.  
  1276.  
  1277.  
  1278.                                   ShCmdLin  2-8
  1279.                                                          05/24/94 01:33pm
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.                                      ShCmplx
  1287.  
  1288.                             A Complex Arithmetic Unit
  1289.  
  1290.  
  1291.         INTRODUCTION
  1292.              ShCmplx is a complex arithmetic unit for Turbo Pascal,
  1293.         version 5 or higher. It provides for the basic binary arithmetic
  1294.         functions (addition, subtraction, multiplication, division), plus
  1295.         the raising of a complex number to a real power. Conversion func-
  1296.         tions are provided to convert between a complex number repre-
  1297.         sented in Cartesian form and one represented in polar form.
  1298.         Finally, provision is made to convert a complex number in
  1299.         Cartesian form to a string; or a complex in polar form to a
  1300.         string expressing the angle either in degrees or in radians.
  1301.  
  1302.              All of the described functionality is available as a suite
  1303.         of Pascal functions. All except the string conversion routines
  1304.         are also available as Pascal procedures.
  1305.  
  1306.              However, recall that a complex number C is represented by
  1307.         two real numbers, say (R1, R2), where C = (R1 + i*R2) and i is
  1308.         the square root of -1. Thus, the representation is inherently a
  1309.         record structure. And Pascal functions can only return simple
  1310.         data types - no structured types.
  1311.  
  1312.              ShCmplx avoids this problem by storing all of its data on
  1313.         the heap. When a variable is declared to be of type Complex, this
  1314.         declaration establishes only a pointer in the data segment; the
  1315.         record structure itself is established on the heap.
  1316.  
  1317.              What this means in practice is that type complex, in this
  1318.         package, is not defined as
  1319.  
  1320.                   type
  1321.                     Complex = record
  1322.                                 Re,
  1323.                                 Im : ComplexElement;
  1324.                                 end;
  1325.  
  1326.         but, rather, as
  1327.  
  1328.                   type
  1329.                     ComplexBaseType = record
  1330.                                         Re,
  1331.                                         Im  : ComplexElement;
  1332.                                         end;
  1333.                     Complex         = ^ComplexBaseType;
  1334.  
  1335.  
  1336.  
  1337.                                    ShCmplx  3-1
  1338.  
  1339.  
  1340.  
  1341.              Thus, if we had an expression which we wished to evaluate -
  1342.         for example:
  1343.  
  1344.                                 A = A + B + C + D
  1345.  
  1346.         this is able to be evaluated (where CAddF is the function name
  1347.         for complex addition) as:
  1348.  
  1349.                      A^ := CAddF(CAddF(A, B), CAddF(C, D))^;
  1350.  
  1351.         which is the equivalent of (with the pointers de-referenced)
  1352.  
  1353.                             A := ((A + B) + (C + D));
  1354.         or
  1355.                      A^ := CAddF(A, CAddF(B, CAddF(C, D)))^;
  1356.  
  1357.         which is the equivalent of (again, with the pointers de-
  1358.         referenced)
  1359.  
  1360.                             A := (A + (B + (C + D)));
  1361.  
  1362.         and the result of this calculation can be displayed using either
  1363.  
  1364.                             WriteLn(Cmp2Str(A, 8, 4));
  1365.         or
  1366.              WriteLn(Cmp2Str(CAddF(CAddF(A, B), CAddF(C, D)), 8, 4));
  1367.  
  1368.         where the "8, 4" in each case carry the same significance as the
  1369.         parameters used in printing real quantities; specifically, the
  1370.         total field width and number of places to the right of the
  1371.         decimal point (in this case, for each numeric component).
  1372.  
  1373.              Note that
  1374.  
  1375.                                 A := CAddF(B, C);
  1376.  
  1377.         is normally not what you would want. This would assign the
  1378.         returned pointer value to the pointer variable 'A', rather than
  1379.         assigning the complex value pointed to by the returned pointer to
  1380.         the element pointed to by 'A', which you would get by writing
  1381.  
  1382.                                A^ := CAddF(B, C)^;
  1383.  
  1384.              This type of error is, unfortunately, not detectable by the
  1385.         Pascal compiler, the run-time system, or at the level of any ap-
  1386.         plication software. So you need to be careful that you don't do
  1387.         it to yourself.
  1388.  
  1389.              A test program (TESTCMPX.PAS) is included with the distribu-
  1390.         tion set. Study it for ideas and specifics of how to use the
  1391.         various functions.
  1392.  
  1393.  
  1394.  
  1395.                                    ShCmplx  3-2
  1396.  
  1397.  
  1398.  
  1399.         INTERFACED ELEMENTS
  1400.  
  1401.         Types
  1402.         =====
  1403.              ComplexElement  = Float;
  1404.              ComplexBaseType = record
  1405.                                  Re,
  1406.                                  Im  : ComplexElement;
  1407.                                  end;
  1408.              Complex         = ^ComplexBaseType;
  1409.  
  1410.  
  1411.         Constants
  1412.         =========
  1413.              cxHaltErr     : boolean        = true;
  1414.                   If TRUE, program execution halts on non-IO errors
  1415.  
  1416.              cxOK          = 0;
  1417.                   Previous operation completed successfully
  1418.  
  1419.              cxDivByZero   = 200;
  1420.                   An attempt has been made to divide by zero
  1421.  
  1422.              cxBadMagnitude= 201;
  1423.                   An attempt has been made to use a complex number (in
  1424.         polar coordinates) having a negative magnitude
  1425.  
  1426.  
  1427.         Routines
  1428.         ========
  1429.  
  1430.         ____________________________
  1431.         C2P
  1432.  
  1433.         Declarations:
  1434.              procedure C2P(A : Complex; var Result : Complex);
  1435.              function C2PF(A : Complex) : Complex;
  1436.  
  1437.         Purpose:
  1438.              Transforms a complex in Cartesian form into polar form.
  1439.  
  1440.         Examples:
  1441.              CpPwrR(C2PF(MyCmpx), 3.0, MyCmpxCubedPolar);
  1442.  
  1443.         Comments:
  1444.              The magnitude will be stored in Result^.Re and the angle
  1445.         (expressed in radians) in Result^.Im
  1446.  
  1447.         See Also:
  1448.              P2C
  1449.  
  1450.  
  1451.  
  1452.  
  1453.                                    ShCmplx  3-3
  1454.  
  1455.  
  1456.  
  1457.         ____________________________
  1458.         CABS
  1459.  
  1460.         Declarations:
  1461.              procedure CAbs(A  : Complex; var Result : ComplexElement);
  1462.              function CAbsF(A  : Complex)  : ComplexElement;
  1463.  
  1464.         Purpose:
  1465.              Returns the absolute value of a complex number.
  1466.  
  1467.         Examples:
  1468.              ∙∙∙
  1469.              MyCmpx^.Re := 3.0;
  1470.              MyCmpx^.Im := 4.0;
  1471.              ∙∙∙
  1472.              WriteLn(CAbs(MyCmpx):4:1);    {will display 5.0}
  1473.  
  1474.         Comments:
  1475.              Recall that the absolute value of a complex number Re + iIm
  1476.         is sqrt((Re * Re) + (Im * Im)).
  1477.  
  1478.         See Also:
  1479.  
  1480.  
  1481.         ____________________________
  1482.         CADD
  1483.  
  1484.         Declarations:
  1485.              procedure CAdd(A, B : Complex; var Result : Complex);
  1486.              function CAddF(A, B : Complex) : Complex;
  1487.  
  1488.         Purpose:
  1489.              Returns the sum of two complex numbers A + B.
  1490.  
  1491.         Examples:
  1492.              See the file TESTCMPX.PAS
  1493.  
  1494.         Comments:
  1495.  
  1496.         See Also:
  1497.              CSub      CMul      CDiv
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.                                    ShCmplx  3-4
  1512.  
  1513.  
  1514.  
  1515.         ____________________________
  1516.         CCONJ
  1517.  
  1518.         Declarations:
  1519.              procedure CConj(A : Complex; var Result : Complex);
  1520.              function CConjF(A : Complex) : Complex;
  1521.  
  1522.         Purpose:
  1523.              Returns the complex conjugate of a complex number.
  1524.  
  1525.         Examples:
  1526.              See the file TESTCMPX.PAS
  1527.  
  1528.         Comments:
  1529.              Recall that if a complex number A = R + Ii, then the complex
  1530.         conjugate of A is R - Ii.
  1531.  
  1532.         See Also:
  1533.  
  1534.  
  1535.         ____________________________
  1536.         CDIV
  1537.  
  1538.         Declarations:
  1539.              procedure CDiv(A, B : Complex; var Result : Complex);
  1540.              function CDivF(A, B : Complex) : Complex;
  1541.  
  1542.         Purpose:
  1543.              Returns the quotient of two complex numbers A / B.
  1544.  
  1545.         Examples:
  1546.              See the file TESTCMPX.PAS
  1547.  
  1548.         Comments:
  1549.              CAbsF(B) must be > 0.0. If CAbsF(B) <= 0.0, CmplxError will
  1550.         return -1.
  1551.  
  1552.         See Also:
  1553.              CAdd      CMul      CSub
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.                                    ShCmplx  3-5
  1570.  
  1571.  
  1572.  
  1573.         ____________________________
  1574.         CMP2STR
  1575.  
  1576.         Declarations:
  1577.              function Cmp2Str(A : Complex; Width, Places : byte) :
  1578.                                                                string;
  1579.  
  1580.         Purpose:
  1581.              Converts a complex value to a string of the form
  1582.                                    (Re + Im i)
  1583.  
  1584.         Examples:
  1585.              See the file TESTCMPX.PAS
  1586.  
  1587.         Comments:
  1588.              The Width and Places arguments have the same significance
  1589.         that they do in the system procedure STR, and are applied
  1590.         individually to both the REAL and IMAGINARY parts.
  1591.  
  1592.         See Also:
  1593.              CmpP2Str       CmpP2StrD
  1594.  
  1595.  
  1596.         ____________________________
  1597.         CMPLXERROR
  1598.  
  1599.         Declarations:
  1600.              function CmplxError  : integer;
  1601.  
  1602.         Purpose:
  1603.              Returns execution error conditions for the package.
  1604.  
  1605.         Examples:
  1606.              See the file TESTCMPX.PAS
  1607.  
  1608.         Comments:
  1609.              Return = 0     OK
  1610.                       -1    Attempt to divide by zero (CDiv)
  1611.                       -2    Magnitude of complex is zero (CpPwrR)
  1612.  
  1613.         See Also:
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620.  
  1621.  
  1622.  
  1623.  
  1624.  
  1625.  
  1626.  
  1627.                                    ShCmplx  3-6
  1628.  
  1629.  
  1630.  
  1631.         ____________________________
  1632.         CMPLXINIT
  1633.  
  1634.         Declarations:
  1635.              procedure CmplxInit;
  1636.  
  1637.         Purpose:
  1638.              Initializes the complex arithmetic package.
  1639.  
  1640.         Examples:
  1641.  
  1642.         Comments:
  1643.              This procedure MUST be called prior to calling any other
  1644.         subroutines in the complex arithmetic package.
  1645.  
  1646.         See also:
  1647.              CmplxDeInit
  1648.  
  1649.  
  1650.         ____________________________
  1651.         CMPLXDEINIT
  1652.  
  1653.         Declarations:
  1654.              procedure CmplxDeInit;
  1655.  
  1656.         Purpose:
  1657.              De-initializes the complex arithmetic package, releasing all
  1658.         the ring buffer heap space.
  1659.  
  1660.         Examples:
  1661.  
  1662.         Comments:
  1663.              Call this procedure if you wish to recover the heap space
  1664.         used by the package. If called, it will be necessary to call
  1665.         CmplxInit again, prior to calling and of the package subroutines.
  1666.         It is not necessary to call this procedure on program exit.
  1667.  
  1668.         See also:
  1669.              CmplxInit
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.  
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.                                    ShCmplx  3-7
  1686.  
  1687.  
  1688.  
  1689.         ____________________________
  1690.         CMPP2STR
  1691.  
  1692.         Declarations:
  1693.              function CmpP2Str(A : Complex; Width, Places : byte) :
  1694.                                                                string;
  1695.  
  1696.         Purpose:
  1697.              Converts a complex in polar form to a string with the angle
  1698.         expressed in radians.
  1699.  
  1700.         Examples:
  1701.              See the file TESTCMPX.PAS
  1702.  
  1703.         Comments:
  1704.              The Width and Places arguments have the same significance
  1705.         that they do in the system procedure STR, and are applied
  1706.         individually to both the MAGNITUDE and ANGLE parts.
  1707.  
  1708.         See Also:
  1709.              Cmp2Str        CmpP2StrD
  1710.  
  1711.  
  1712.         ____________________________
  1713.         CMPP2STRD
  1714.  
  1715.         Declarations:
  1716.              function CmpP2StrD(A : Complex; Width, Places : byte) :
  1717.                                                                string;
  1718.  
  1719.         Purpose:
  1720.              Converts a complex in polar form to a string with the angle
  1721.         in degrees.
  1722.  
  1723.         Examples:
  1724.              See the file TESTCMPX.PAS
  1725.  
  1726.         Comments:
  1727.              The Width and Places arguments have the same significance
  1728.         that they do in the system procedure STR, and are applied
  1729.         individually to both the MAGNITUDE and ANGLE parts.
  1730.  
  1731.         See Also:
  1732.              Cmp2Str        CmpP2Str
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.                                    ShCmplx  3-8
  1744.  
  1745.  
  1746.  
  1747.         ____________________________
  1748.         CMUL
  1749.  
  1750.         Declarations:
  1751.              procedure CMul(A, B : Complex; var Result : Complex);
  1752.              function CMulF(A, B : Complex) : Complex;
  1753.  
  1754.         Purpose:
  1755.              Returns the product of two complex numbers A * B.
  1756.  
  1757.         Example:
  1758.              See the file TESTCMPX.PAS
  1759.  
  1760.         Comments:
  1761.  
  1762.         See Also:
  1763.              CAdd      CDiv      CSub      RxC
  1764.  
  1765.  
  1766.         ____________________________
  1767.         CPPWRR
  1768.  
  1769.         Declarations:
  1770.              procedure CpPwrR(A : Complex; R : ComplexElement;
  1771.                                                 var Result : Complex);
  1772.              function CpPwrRF(A : Complex; R : ComplexElement) : Complex;
  1773.  
  1774.         Purpose:
  1775.              Raises a complex (in polar form) to a real power.
  1776.  
  1777.         Examples:
  1778.              See the file TESTCMPX.PAS
  1779.  
  1780.         Comments:
  1781.              If A^.Re = 0, CmplxError will return -2, and
  1782.                            Result will be 0 + 0i
  1783.                            n.b. A^.Re contains the magnitude.
  1784.  
  1785.         See Also:
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.                                    ShCmplx  3-9
  1802.  
  1803.  
  1804.  
  1805.         ____________________________
  1806.         CSUB
  1807.  
  1808.         Declarations:
  1809.              procedure CSub(A, B : Complex; var Result : Complex);
  1810.              function CSubF(A, B : Complex) : Complex;
  1811.  
  1812.         Purpose:
  1813.              Returns the difference between two complex numbers A - B.
  1814.  
  1815.         Examples:
  1816.              See the file TESTCMPX.PAS
  1817.  
  1818.         Comments:
  1819.  
  1820.         See Also:
  1821.              CAdd      CDiv      CMul
  1822.  
  1823.  
  1824.         ____________________________
  1825.         P2C
  1826.  
  1827.         Declarations:
  1828.              procedure P2C(A : Complex; var Result : Complex);
  1829.              function P2CF(A : Complex) : Complex;
  1830.  
  1831.         Purpose:
  1832.              Transforms a complex in polar form into Cartesian form. The
  1833.         magnitude is stored in A^.Re and the angle (expressed in radians)
  1834.         in A^.Im.
  1835.  
  1836.         Examples:
  1837.              See the file TESTCMPX.PAS
  1838.  
  1839.         Comments:
  1840.  
  1841.         See Also:
  1842.              C2P
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.  
  1859.                                   ShCmplx  3-10
  1860.  
  1861.  
  1862.  
  1863.         ____________________________
  1864.         RXC
  1865.  
  1866.         Declarations:
  1867.              procedure RxC(A : ComplexElement; B : Complex;
  1868.                                                 var Result : Complex);
  1869.              function RxCF(A : ComplexElement; B : Complex) : Complex;
  1870.  
  1871.         Purpose:
  1872.              Returns the complex product of a real and a complex.
  1873.  
  1874.         Examples:
  1875.              See the file TESTCMPX.PAS
  1876.  
  1877.         Comments:
  1878.              This is simply a special case of CMul, in which the
  1879.         imaginary part of one of the factors is zero. It occurrs with
  1880.         sufficient frequency, however, to warrent separate treatment.
  1881.  
  1882.         See Also:
  1883.              CMul
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.  
  1890.  
  1891.  
  1892.  
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.                                   ShCmplx  3-11
  1918.                                                          05/24/94 01:33pm
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.  
  1925.  
  1926.  
  1927.  
  1928.  
  1929.  
  1930.  
  1931.  
  1932.  
  1933.  
  1934.  
  1935.  
  1936.  
  1937.  
  1938.  
  1939.  
  1940.                        This page has been deliberately left
  1941.                          blank, except for this message.
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.  
  1953.  
  1954.  
  1955.  
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.  
  1963.  
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.                                   ShCmplx  3-12
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.                                     ShCrcChk
  1984.  
  1985.                           A File CRC16 Calculation Unit
  1986.  
  1987.  
  1988.         INTRODUCTION
  1989.              ShCrcChk interfaces two procedures, both of which calculates
  1990.         the CRC16 of a file whose name is provided as a string parameter.
  1991.  
  1992.              When the DOS COPY command is used, no true read-after-write
  1993.         verification is performed. The only way to assure that the re-
  1994.         cording was correct is to read the file after writing, and com-
  1995.         pare the output file, byte for byte, with the input. For very
  1996.         long files this can result in unacceptable delays.
  1997.  
  1998.              A reasonable compromise between speed and reliability is to
  1999.         calculate the cyclic redundancy check (CRC) word of the input
  2000.         file as it is being copied, and then on completion of the copying
  2001.         operation, read back the output file and calculate its CRC. If
  2002.         the two compare, the probability that the two files differ is
  2003.         extremely small, especially if the two files are of the same
  2004.         size.
  2005.  
  2006.  
  2007.         OVERVIEW
  2008.              For those unfamiliar with CRCs, suffice to say that they are
  2009.         very powerful generalizations of the familiar 'parity check'
  2010.         schemes, such as those which have been used at least since the
  2011.         early days of digital magnetic tape recording.
  2012.  
  2013.              CRCs are calculated by performing iterative calculations,
  2014.         byte by byte, on a data block, using specific algebraic poly-
  2015.         nomials to determine the manner in which individual bits of each
  2016.         byte are to be used in the calculation. The determination of
  2017.         suitable polynomials is the subject of an extensive body of
  2018.         literature.
  2019.  
  2020.              The CCITT (for those who enjoy living life the hard way,
  2021.         CCITT is the designation for the International Consultative
  2022.         Committee for Telephone and Telegraph, a branch of the United
  2023.         Nations) has recommended the use of a specific generator poly-
  2024.         nomial for use in calculating the CRC for data blocks in asyn-
  2025.         chronous communications. This polynomial is
  2026.  
  2027.                              (X^16 + X^12 + X^5 + 1).
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.                                   ShCrcChk  4-1
  2035.  
  2036.  
  2037.  
  2038.              While its recommended use primarily deals with block trans-
  2039.         mission of data over asynchronous links (as in the X/Y/ZMODEM
  2040.         protocols), it has come into widespread use also as a generator
  2041.         polynomial for file-level CRC. This is therefore the generator
  2042.         polynomial which has been used for ShCrcChk.
  2043.  
  2044.              Those sufficiently interested and/or masochistic as to want
  2045.         to find additional information regarding the theory of CRC are
  2046.         referred to:
  2047.  
  2048.              1. SOBOLEWSKI, J.S., "Cyclic Redundancy Check", in Ralston,
  2049.         A. (ed.), Encyclopedia of Computer Science and Engineering (2nd
  2050.         Ed.), Van Nostrand Reinhold Co., 1983, p.434ff
  2051.  
  2052.              2. PLESS, V., "Introduction to the Theory of Error-
  2053.         Correcting Codes", John Wiley and Sons, 1982, p. 59ff
  2054.  
  2055.              Both of these references include bibliography for additional
  2056.         study.
  2057.  
  2058.  
  2059.         INTERFACED ELEMENTS
  2060.  
  2061.         Routines
  2062.         ========
  2063.         ____________________________
  2064.         CRCCALC
  2065.  
  2066.         Declaration:
  2067.              function CrcCalc(FileName : String) : word;
  2068.  
  2069.         Purpose:
  2070.               To calculate the CRC16 of a named file, assumed to exist.
  2071.  
  2072.         Example:
  2073.               if CrcCalc(MyFile) <> CrcShouldBe then begin
  2074.                 (*Take remedial action*)
  2075.                 end;
  2076.  
  2077.         Comments:
  2078.               MyFile is a file of any type, and may have any attributes
  2079.         including Hidden, ReadOnly, etc. A run time error will result,
  2080.         however, if the file does not exist.
  2081.  
  2082.  
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.  
  2092.                                   ShCrcChk  4-2
  2093.  
  2094.  
  2095.  
  2096.         ____________________________
  2097.         CRCCOPY
  2098.  
  2099.         Declaration:
  2100.              function CrcCopy(InFileName, OutFileName : String) : word;
  2101.  
  2102.         Purpose:
  2103.               Calculates the CRC16 value for file=InFileName, while
  2104.         copying it to file=OutFileName.
  2105.  
  2106.         Example:
  2107.               CrcShouldBe := CrcCopy(FileFromYou, MyFile);
  2108.               if CrcCopy(MyFile, '') <> CrcShouldBe then begin
  2109.                 (*Take remedial action*)
  2110.                 end;
  2111.  
  2112.         Comments:
  2113.               The output file name is optional. If OutFileName is speci-
  2114.         fied, InFileName is copied to OutFileName. If OutFileName is an
  2115.         empty string, CrcCopy behaves exactly like CrcCalc. In either
  2116.         case, the CRC16 value of InFileName is returned.
  2117.  
  2118.               Using CrcCopy simply to calculate the CRC16 of the input
  2119.         file will be marginally slower than using CrcCalc. In cases in
  2120.         which both functionalities are required, however, using CrcCopy
  2121.         exclusively will result in a somewhat smaller code segment.
  2122.  
  2123.  
  2124.  
  2125.  
  2126.  
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.                                   ShCrcChk  4-3
  2151.                                                          05/24/94 01:33pm
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.                        This page has been deliberately left
  2174.                          blank, except for this message.
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.  
  2193.  
  2194.  
  2195.  
  2196.  
  2197.  
  2198.  
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.  
  2206.  
  2207.  
  2208.  
  2209.                                   ShCrcChk  4-4
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.  
  2216.                                      ShDatPk
  2217.  
  2218.                              A Date Manipulation Unit
  2219.  
  2220.         INTRODUCTION
  2221.              ShDatPk is a set of routines intended to simplify the
  2222.         accurate manipulation of dates. These routines are based on
  2223.         Algorithm #398 and associated comments, from the Collected
  2224.         Algorithms of the ACM.
  2225.  
  2226.              Before proceeding, several definitions are necessary to
  2227.         provide the framework for understanding the various conversions
  2228.         possible through the use of the ShDatPk routines.
  2229.  
  2230.  
  2231.         GREGORIAN DATE  is the date system commonly used in modern
  2232.                        western nations. Established by Papal bull in
  2233.                        March 1582, it adjusted the calendar in use up to
  2234.                        that time in order to restore the vernal equinox
  2235.                        to March 21, the date on which it occurred at the
  2236.                        time of the First Council of Nicaea. This was
  2237.                        accomplished by suppressing the dates from the 5th
  2238.                        through the 14th (inclusive) of October, 1582.
  2239.                        While the Gregorian calendar was accepted quickly
  2240.                        throughout most of Europe, it was not adopted in
  2241.                        England and the Colonies until 1752. When YEAR,
  2242.                        MONTH, and/or DAY are passed or returned as
  2243.                        parameters in the ShDatPk  routines, the Gregorian
  2244.                        system is assumed.
  2245.  
  2246.         JULIAN DAY-NUMBER
  2247.         JULIAN DAY      is the representation of a given date as its
  2248.                        serial index, beginning on January 1, 4713 B.C.
  2249.                        The date chosen as the basis has astronomical
  2250.                        significance, and is widely recognized in the
  2251.                        scientific community. Proposed by the astronomer
  2252.                        Joseph Scaliger, it is named in memory of his
  2253.                        father and not, as often assumed, for Julius
  2254.                        Caesar. When used as a parameter by any of the
  2255.                        ShDatPk routines, it will be passed as a LongInt
  2256.                        representation of a 7 digit integer.
  2257.  
  2258.         JULIAN DATE     is the representation of a given date as its
  2259.                        serial index, taking January 1st  of the given
  2260.                        year as the base (=1). When used as a parameter by
  2261.                        any of the ShDatPk routines, both the serial index
  2262.                        and the year will be represented as simple
  2263.  
  2264.  
  2265.  
  2266.  
  2267.                                    ShDatPk  5-1
  2268.  
  2269.  
  2270.  
  2271.                        integers. (By the way, this one was named for
  2272.                        Julius Caesar).
  2273.  
  2274.         SMITHSONIAN DATE
  2275.                         is the representation of a given date as its
  2276.                        serial index, with November 18, 1858 as the base
  2277.                        (=1). While routines are not included for convert-
  2278.                        ing from or to the Smithsonian date, it is readily
  2279.                        calculated from the Julian Day as
  2280.  
  2281.                                  Smithsonian = Julian - 2400001
  2282.  
  2283.  
  2284.         INTERFACED ELEMENTS
  2285.  
  2286.         Types
  2287.         =====
  2288.              GregType  = record
  2289.                            Year  : LongInt;
  2290.                            Month,
  2291.                            Day   : byte;
  2292.                            end;
  2293.              Variables of this type contain a complete Gregorian date,
  2294.         and are passed to many of the routines in this unit.
  2295.  
  2296.              TimeType  = record
  2297.                            H,
  2298.                            M,
  2299.                            S   : byte;
  2300.                            end;
  2301.              Variables of this type contain a complete time record, and
  2302.         are passed to many of the routines in this unit.
  2303.  
  2304.  
  2305.         Constants
  2306.         =========
  2307.              DayStr  : array[0..6] of string[9] =
  2308.                            ('Sunday'   , 'Monday'   , 'Tuesday'  ,
  2309.                             'Wednesday', 'Thursday' , 'Friday'   ,
  2310.                             'Saturday' );
  2311.  
  2312.              MonthStr: array[1..12] of string[9] =
  2313.                            ('January'  , 'February' , 'March',
  2314.                             'April'    , 'May'      , 'June',
  2315.                             'July'     , 'August'   , 'September',
  2316.                             'October'  , 'November' , 'December');
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.                                    ShDatPk  5-2
  2326.  
  2327.  
  2328.  
  2329.         Routines
  2330.         ========
  2331.         ____________________________
  2332.         DOW
  2333.  
  2334.         Declaration:
  2335.              function DoW(Greg : GregType) : byte;
  2336.  
  2337.         Purpose:
  2338.              To compute the day of the week (Sunday = 0; Saturday = 6)
  2339.         from the Gregorian date.
  2340.  
  2341.         Examples:
  2342.              See TESTDATE.PAS
  2343.  
  2344.         Comments:
  2345.  
  2346.         See also:
  2347.  
  2348.  
  2349.         ____________________________
  2350.         GREG2ANSI
  2351.  
  2352.         Declaration:
  2353.              function Greg2ANSI(G : GregType) : string;
  2354.  
  2355.         Purpose:
  2356.              Given a Gregorian date, return the date as an ANSI date
  2357.         string (YYYYMMDD).
  2358.  
  2359.         Examples:
  2360.              See TESTDATE.PAS
  2361.  
  2362.         Comments:
  2363.              Note that the ANSI date format is both sortable and
  2364.         readable.
  2365.  
  2366.         See also:
  2367.              JDN2ANSI
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.                                    ShDatPk  5-3
  2384.  
  2385.  
  2386.  
  2387.         ____________________________
  2388.         GREG2JDATE
  2389.  
  2390.         Declaration:
  2391.              function Greg2JDate(Greg : GregType) : integer;
  2392.  
  2393.         Purpose:
  2394.              To compute the Julian date from the Gregorian date.
  2395.  
  2396.         Examples:
  2397.              See TESTDATE.PAS
  2398.  
  2399.         Comments:
  2400.              Do not confuse the Julian date with the Julian Day-Number.
  2401.         The Julian date, most commonly used in business applications, is
  2402.         the serial index of a date WITHIN A GIVEN YEAR. The Julian Day-
  2403.         Number is the serial index of a date from January 1, 4713 B.C.
  2404.  
  2405.         See also:
  2406.              JDate2Greg
  2407.  
  2408.  
  2409.         ____________________________
  2410.         GREG2JDN
  2411.  
  2412.         Declaration:
  2413.              function Greg2JDN(Greg : GregType) : LongInt;
  2414.  
  2415.         Purpose:
  2416.              To convert a Gregorian date into a Julian Day-Number.
  2417.  
  2418.         Examples:
  2419.              See TESTDATE.PAS
  2420.  
  2421.         Comments:
  2422.              The Julian Day-Number (JDN) is the basic form for date
  2423.         manipulation within this unit. Thus this function performs the
  2424.         primary conversion between dates in the customary form and
  2425.         equivalent dates suitable for manipulation by ShDatPk.
  2426.  
  2427.         See also:
  2428.              JDN2Greg
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.                                    ShDatPk  5-4
  2442.  
  2443.  
  2444.  
  2445.         ____________________________
  2446.         JDATE2GREG
  2447.  
  2448.         Declaration:
  2449.              procedure JDate2Greg(JDate, Year : Integer;
  2450.                                                     var Greg : GregType);
  2451.  
  2452.         Purpose:
  2453.              To compute the Gregorian date from the Julian date.
  2454.  
  2455.         Examples:
  2456.              See TESTDATE.PAS
  2457.  
  2458.         Comments:
  2459.              Do not confuse the Julian date with the Julian Day-Number.
  2460.         The Julian date, most commonly used in business applications, is
  2461.         the serial index of a date WITHIN A GIVEN YEAR. The Julian Day-
  2462.         Number is the serial index of a date from January 1, 4713 B.C.
  2463.  
  2464.         See also:
  2465.              Greg2JDate
  2466.  
  2467.  
  2468.         ____________________________
  2469.         JDN2ANSI
  2470.  
  2471.         Declaration:
  2472.              function JDN2ANSI(JDN : LongInt) : string;
  2473.  
  2474.         Purpose:
  2475.              Given a Julian Day-Number, return the JDN as an ANSI date
  2476.         string (YYYYMMDD).
  2477.  
  2478.         Examples:
  2479.              See TESTDATE.PAS
  2480.  
  2481.         Comments:
  2482.              Note that the ANSI date format is both sortable and
  2483.         readable.
  2484.  
  2485.         See also:
  2486.              Greg2ANSI
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.                                    ShDatPk  5-5
  2500.  
  2501.  
  2502.  
  2503.         ____________________________
  2504.         JDN2GREG
  2505.  
  2506.         Declaration:
  2507.              procedure JDN2Greg(JDN : LongInt; var Greg : GregType);
  2508.  
  2509.         Purpose:
  2510.              To compute the Gregorian date from the Julian Day-Number.
  2511.  
  2512.         Examples:
  2513.              See TESTDATE.PAS
  2514.  
  2515.         Comments:
  2516.              The Julian Day-Number (JDN) is the basic form for date
  2517.         manipulation within this unit. Thus this function performs the
  2518.         primary conversion between dates in ShDatPk internal form and
  2519.         equivalent dates in the customary form.
  2520.  
  2521.         See also:
  2522.              Greg2JDN
  2523.  
  2524.  
  2525.         ____________________________
  2526.         GREG2STR
  2527.  
  2528.         Declaration:
  2529.              function Greg2Str(G : GregType; Delim : string) : string;
  2530.  
  2531.         Purpose:
  2532.              Returns a Gregorian date record as a string of the form
  2533.         MMdDDdYYYY, where the separator, "d", is Delim[1].
  2534.  
  2535.         Examples:
  2536.              See TESTDATE.PAS
  2537.  
  2538.         Comments:
  2539.  
  2540.         See also:
  2541.  
  2542.  
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.                                    ShDatPk  5-6
  2558.  
  2559.  
  2560.  
  2561.         ____________________________
  2562.         JDN2STR
  2563.  
  2564.         Declaration:
  2565.              function JDN2Str(JDN : LongInt; Delim : string) : string;
  2566.  
  2567.         Purpose:
  2568.              Returns a Julian Day-Number as a string of the form
  2569.         MMdDDdYYYY, where the separator, "d", is Delim[1].
  2570.  
  2571.         Examples:
  2572.              See TESTDATE.PAS
  2573.  
  2574.         Comments:
  2575.  
  2576.         See also:
  2577.  
  2578.  
  2579.         ____________________________
  2580.         NOW
  2581.  
  2582.         Declaration:
  2583.              function Now  : LongInt;
  2584.  
  2585.         Purpose:
  2586.              Returns the system time as Seconds-Since-Midnight.
  2587.  
  2588.         Examples:
  2589.              See TESTDATE.PAS
  2590.  
  2591.         Comments:
  2592.  
  2593.         See also:
  2594.  
  2595.  
  2596.         ____________________________
  2597.         NOW2TIME
  2598.  
  2599.         Declaration:
  2600.              procedure Now2Time(var T : TimeType);
  2601.  
  2602.         Purpose:
  2603.              Returns the system time as a Time record.
  2604.  
  2605.         Examples:
  2606.              See TESTDATE.PAS
  2607.  
  2608.         Comments:
  2609.  
  2610.         See also:
  2611.  
  2612.  
  2613.  
  2614.  
  2615.                                    ShDatPk  5-7
  2616.  
  2617.  
  2618.  
  2619.         ____________________________
  2620.         NOWSTR
  2621.  
  2622.         Declaration:
  2623.              function NowStr(Delim : string; T24 : boolean) : string;
  2624.  
  2625.         Purpose:
  2626.              Returns the system time as a string of the form:
  2627.  
  2628.              HHdMMdSSss     if Delim is non-empty and T24 (24 hour time)
  2629.                            is false. The delimiter used, "d", is
  2630.                            Delim[1]. The suffix, "ss", is "am" or "pm" as
  2631.                            appropriate.
  2632.              HHdMMdSS       if Delim is non-empty and T24 (24 hour time)
  2633.                            is true. The delimiter used, "d", is Delim[1].
  2634.                            The time will be expressed in 24-hour form.
  2635.              HHMMSSss       if Delim is empty and T24 (24 hour time) is
  2636.                            false. The suffix, "ss", is "am" or "pm" as
  2637.                            appropriate.
  2638.              HHMM           if Delim is empty and T24 (24 hour time) is
  2639.                            true. The time will be expressed in 24-hour
  2640.                            (i.e., military) form.
  2641.  
  2642.         Examples:
  2643.              See TESTDATE.PAS
  2644.  
  2645.         Comments:
  2646.  
  2647.         See also:
  2648.  
  2649.  
  2650.         ____________________________
  2651.         SSM2TIME
  2652.  
  2653.         Declaration:
  2654.              procedure SSM2Time(SSM : LongInt; var T : TimeType);
  2655.  
  2656.         Purpose:
  2657.              Converts Seconds-Since-Midnight to a Time record.
  2658.  
  2659.         Examples:
  2660.              See TESTDATE.PAS
  2661.  
  2662.         Comments:
  2663.  
  2664.         See also:
  2665.  
  2666.  
  2667.  
  2668.  
  2669.  
  2670.  
  2671.  
  2672.  
  2673.                                    ShDatPk  5-8
  2674.  
  2675.  
  2676.  
  2677.         ____________________________
  2678.         SSM2TIMESTR
  2679.  
  2680.         Declaration:
  2681.              function SSM2TimeStr(SSM : LongInt; Delim : string;
  2682.                                                  T24 : boolean) : string;
  2683.  
  2684.         Purpose:
  2685.              Converts Seconds-Since-Midnight to a time string, of the
  2686.         form:
  2687.  
  2688.              HHdMMdSSss     if Delim is non-empty and T24 (24 hour time)
  2689.                            is false. The delimiter used, "d", is
  2690.                            Delim[1]. The suffix, "ss", is "am" or "pm" as
  2691.                            appropriate.
  2692.              HHdMMdSS       if Delim is non-empty and T24 (24 hour time)
  2693.                            is true. The delimiter used, "d", is Delim[1].
  2694.                            The time will be expressed in 24-hour form.
  2695.              HHMMSSss       if Delim is empty and T24 (24 hour time) is
  2696.                            false. The suffix, "ss", is "am" or "pm" as
  2697.                            appropriate.
  2698.              HHMM           if Delim is empty and T24 (24 hour time) is
  2699.                            true. The time will be expressed in 24-hour
  2700.                            (i.e., military) form.
  2701.  
  2702.         Examples:
  2703.              See TESTDATE.PAS
  2704.  
  2705.         Comments:
  2706.  
  2707.         See also:
  2708.  
  2709.  
  2710.         ____________________________
  2711.         TIME2SSM
  2712.  
  2713.         Declaration
  2714.              function Time2SSM(T : TimeType) : LongInt;
  2715.  
  2716.         Purpose:
  2717.              Converts a Time record to Seconds-Since-Midnight.
  2718.  
  2719.         Examples:
  2720.              See TESTDATE.PAS
  2721.  
  2722.         Comments:
  2723.  
  2724.         See also:
  2725.  
  2726.  
  2727.  
  2728.  
  2729.  
  2730.  
  2731.                                    ShDatPk  5-9
  2732.  
  2733.  
  2734.  
  2735.         ____________________________
  2736.         TIME2TIMESTR
  2737.  
  2738.         Declaratin:
  2739.              function Time2TimeStr(T : TimeType; Delim : string;
  2740.                                                  T24 : boolean) : string;
  2741.  
  2742.         Purpose:
  2743.              Converts a time record to a time string of the form:
  2744.  
  2745.              HHdMMdSSss     if Delim is non-empty and T24 (24 hour time)
  2746.                            is false. The delimiter used, "d", is
  2747.                            Delim[1]. The suffix, "ss", is "am" or "pm" as
  2748.                            appropriate.
  2749.              HHdMMdSS       if Delim is non-empty and T24 (24 hour time)
  2750.                            is true. The delimiter used, "d", is Delim[1].
  2751.                            The time will be expressed in 24-hour form.
  2752.              HHMMSSss       if Delim is empty and T24 (24 hour time) is
  2753.                            false. The suffix, "ss", is "am" or "pm" as
  2754.                            appropriate.
  2755.              HHMM           if Delim is empty and T24 (24 hour time) is
  2756.                            true. The time will be expressed in 24-hour
  2757.                            (military) form.
  2758.  
  2759.         Examples:
  2760.              See TESTDATE.PAS
  2761.  
  2762.         Comments:
  2763.  
  2764.         See also:
  2765.  
  2766.  
  2767.         ____________________________
  2768.         TODAY
  2769.  
  2770.         Declaration:
  2771.              function Today  : LongInt;
  2772.  
  2773.         Purpose:
  2774.              Returns the system date as a Julian Day-Number.
  2775.  
  2776.         Examples:
  2777.              See TESTDATE.PAS
  2778.  
  2779.         Comments:
  2780.  
  2781.         See also:
  2782.  
  2783.  
  2784.  
  2785.  
  2786.  
  2787.  
  2788.  
  2789.                                   ShDatPk  5-10
  2790.  
  2791.  
  2792.  
  2793.         ____________________________
  2794.         TODAY2ANSI
  2795.  
  2796.         Declaration:
  2797.              function Today2ANSI : string;
  2798.  
  2799.         Purpose:
  2800.              Returns the system date as an ANSI date string (YYYYMMDD).
  2801.  
  2802.         Examples:
  2803.              See TESTDATE.PAS
  2804.  
  2805.         Comments:
  2806.              Note that the ANSI date format is both sortable and
  2807.         readable.
  2808.  
  2809.         See also:
  2810.  
  2811.  
  2812.         ____________________________
  2813.         TODAY2GREG
  2814.  
  2815.         Declaration:
  2816.              procedure Today2Greg(var G : GregType);
  2817.  
  2818.         Purpose:
  2819.              Returns the system date as a Gregorian date record.
  2820.  
  2821.         Examples:
  2822.              See TESTDATE.PAS
  2823.  
  2824.         Comments:
  2825.  
  2826.         See also:
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.                                   ShDatPk  5-11
  2848.  
  2849.  
  2850.  
  2851.         ____________________________
  2852.         TODAYSTR
  2853.  
  2854.         Declaration:
  2855.              function TodayStr(Delim : string) : string;
  2856.  
  2857.         Purpose:
  2858.              Returns the system date as a string of the form MMdDDdYYYY,
  2859.         where the separator, "d", is Delim[1].}
  2860.  
  2861.         Examples:
  2862.              See TESTDATE.PAS
  2863.  
  2864.         Comments:
  2865.  
  2866.         See also:
  2867.  
  2868.  
  2869.  
  2870.  
  2871.  
  2872.  
  2873.  
  2874.  
  2875.  
  2876.  
  2877.  
  2878.  
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.                                   ShDatPk  5-12
  2906.                                                          05/24/94 01:33pm
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.                                     ShErrMsg
  2914.  
  2915.                          An Error Message Handeling Unit
  2916.  
  2917.  
  2918.         INTRODUCTION
  2919.              "Runtime error 152 at 12C4:0B23" really is not all that
  2920.         informative. How much better to see
  2921.  
  2922.                        Runtime error 152 - Drive not ready
  2923.                             Error at 1376:0003
  2924.  
  2925.              If ShErrMsg is included LAST in the USES statement of your
  2926.         program, any normal runtime errors will be reported along with a
  2927.         brief message suggesting the problem.
  2928.  
  2929.              During initialization, ShErrMsg installs a special exit
  2930.         routine into the exit procedure chain maintained by Turbo PASCAL.
  2931.         For the normal suite of runtime errors as listed in the manuals,
  2932.         this exit routine will display the error information in the ex-
  2933.         panded format shown above, with the explanatory message.
  2934.  
  2935.              Further, ShErrMsg interfaces replacements for T-PASCAL's
  2936.         HALT and RUNERROR procedures. These replacements, called HaltMsg
  2937.         and RunErrorMsg, permit the programmer to display any desired
  2938.         message along with the normal termination information reported by
  2939.         the corresponding T-PASCAL routine.
  2940.  
  2941.              ShErrMsg installs itself with checking ON; i.e., any errors
  2942.         occurring during execution of your program which would normally
  2943.         cause program termination will terminate with a message as de-
  2944.         scribed above. Should you wish it, you can turn this facility off
  2945.         and on again using the two procedures
  2946.  
  2947.                                      CheckOff
  2948.                                      CheckOn
  2949.  
  2950.              If CheckOff has been executed, error reporting will appear
  2951.         as if ShErrMsg had never been installed. The messages will not
  2952.         appear. HaltMsg and RunErrorMsg will behave exactly as if Halt or
  2953.         RunError had been called.
  2954.  
  2955.              If checking is enabled, either by default or through execu-
  2956.         tion of CheckOn, and procedure RunError is executed with an error
  2957.         code not part of the normal suite, the message "Unknown Error
  2958.         Code" will appear. RunErrorMsg will, of course, report whatever
  2959.         message you have provided as part of the call.
  2960.  
  2961.  
  2962.  
  2963.  
  2964.                                   ShErrMsg  6-1
  2965.  
  2966.  
  2967.  
  2968.         ERROR ADDRESS REPORTING
  2969.              If checking is enabled, or if RunErrorMsg is called (even if
  2970.         checking is disabled), the error address reported will appear
  2971.         slightly different than it normally would. ShErrMsg reports ad-
  2972.         dresses normalized; the segment address is adjusted so that the
  2973.         offset shown lies in the range
  2974.  
  2975.                                   0 <= Ofs <= $F
  2976.  
  2977.              If, however, you calculate the actual resulting 20-bit
  2978.         addresses, you will find that they are identical.
  2979.  
  2980.  
  2981.         INTERFACED ELEMENTS
  2982.  
  2983.         Routines
  2984.         ========
  2985.         ____________________________
  2986.         CHECKON
  2987.         CHECKOFF
  2988.  
  2989.         Declarations:
  2990.              procedure CheckOn;
  2991.              procedure CheckOff;
  2992.  
  2993.         Purpose:
  2994.              Enables/disables the error reporting facilities of ShErrMsg.
  2995.  
  2996.         Examples:
  2997.              ∙∙∙
  2998.              CheckOff; {Turn off error reporting}
  2999.              ∙∙∙
  3000.              CheckOn;  {Turn error reporting back on}
  3001.  
  3002.         Comment:
  3003.              The default state following initialization is CheckOn.
  3004.  
  3005.  
  3006.  
  3007.  
  3008.  
  3009.  
  3010.  
  3011.  
  3012.  
  3013.  
  3014.  
  3015.  
  3016.  
  3017.  
  3018.  
  3019.  
  3020.  
  3021.  
  3022.                                   ShErrMsg  6-2
  3023.  
  3024.  
  3025.  
  3026.         ____________________________
  3027.         HALTMSG
  3028.  
  3029.         Declarations:
  3030.              procedure HaltMsg(Code : word; Msg : string);
  3031.  
  3032.         Purpose:
  3033.              To stop execution of the program, returning an error code to
  3034.         DOS and optionally displaying a message.
  3035.  
  3036.         Examples:
  3037.              ∙∙∙
  3038.              HaltMsg(1000, 'Exiting on a problem in procedure FOO_BAZ');
  3039.  
  3040.         Comments:
  3041.              If Checking is ON, execution will stop with the message, and
  3042.         a return code of 1000 will be passed to DOS.
  3043.  
  3044.                     ErrorLevel 1000
  3045.                        Exiting on a problem in procedure FOO_BAZ
  3046.  
  3047.              If checking is OFF, execution will stop with no message, and
  3048.         a return code of 1000 will be passed to DOS.
  3049.  
  3050.              In either case, due to the way in which DOS is implemented,
  3051.         an
  3052.  
  3053.                                   IF ERRORLEVEL
  3054.  
  3055.         command will be sensitive ONLY TO THE LOW BYTE of the code. Thus,
  3056.         in the above example, DOS will see a return code of 232.
  3057.  
  3058.         See also:
  3059.              RunErrorMsg
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.                                   ShErrMsg  6-3
  3081.  
  3082.  
  3083.  
  3084.         ____________________________
  3085.         RUNERRORMSG
  3086.  
  3087.         Declarations:
  3088.              procedure RunErrorMsg(Code : integer; Msg : string);
  3089.  
  3090.         Purpose:
  3091.              To stop execution of the program with a runtime error
  3092.         message, optionally augmented by an additional information
  3093.         message, and returning an error code to DOS.
  3094.  
  3095.         Examples:
  3096.              ∙∙∙
  3097.              RunErrorMsg(1000, 'Problem in procedure FOO_BAZ');
  3098.  
  3099.         Comments:
  3100.              If Checking is ON, execution will stop with the following
  3101.         message, and a return code of 1000 will be passed to DOS.
  3102.  
  3103.                            Runtime error 1000 at 0C8F:0008
  3104.                               Problem in procedure FOO_BAZ
  3105.  
  3106.              If checking is OFF, execution will stop with the following
  3107.         message, and a return code of 1000 will be passed to DOS.
  3108.  
  3109.                            Runtime error 232 at 0000:C8F8
  3110.  
  3111.              In either case, due to the way in which DOS is implemented,
  3112.         an
  3113.  
  3114.                                   IF ERRORLEVEL
  3115.  
  3116.         command will be sensitive ONLY TO THE LOW BYTE of the code. Thus,
  3117.         in the above example, DOS will see a return code of 232.
  3118.  
  3119.              Note also that, if checking is turned off, the error address
  3120.         is not normalized.
  3121.  
  3122.         See also:
  3123.              HaltMsg
  3124.  
  3125.  
  3126.  
  3127.  
  3128.  
  3129.  
  3130.  
  3131.  
  3132.  
  3133.  
  3134.  
  3135.  
  3136.  
  3137.  
  3138.                                   ShErrMsg  6-4
  3139.                                                          05/24/94 01:33pm
  3140.  
  3141.  
  3142.  
  3143.  
  3144.  
  3145.  
  3146.                                     ShFinanc
  3147.  
  3148.                           A Financial Calculations Unit
  3149.  
  3150.         INTRODUCTION
  3151.              ShFinanc is a unit containing six functions necessary to
  3152.         perform most ordinary financial calculations. Specifically,
  3153.  
  3154.              CompPresVal    = compound present value,
  3155.  
  3156.              CompAmount     = compound amount,
  3157.  
  3158.              AnnuityPresVal
  3159.                             = annuity present value,
  3160.  
  3161.              AnnuityAmount  = annuity amount,
  3162.  
  3163.              NumPay         = number of payments corresponding to a given
  3164.                            annuity present value and interest rate, and
  3165.  
  3166.              IfromPresVal   = interest rate corresponding to a given
  3167.                            annuity present value and number of payments.
  3168.  
  3169.              The parameter list for the four functions dealing with
  3170.         annuities contain a switch which dictates whether the calcula-
  3171.         tions are to be carried out for an ordinary annuity (payments
  3172.         made at the end of each conversion period) or an annuity due
  3173.         (payments made at the beginning of each conversion period).
  3174.  
  3175.  
  3176.         INTERFACED ELEMENTS
  3177.  
  3178.         Types
  3179.         =====
  3180.              AnnType   = (Ordinary, Due);
  3181.  
  3182.         Constants
  3183.         =========
  3184.              finOK                     = 0;
  3185.              finErrParamTooSmall       = 200;
  3186.              finIntOutOfRange          = 201;
  3187.              finIllegalNumPeriods      = 202;
  3188.              finUnknownAnnuityType     = 203;
  3189.              finIllegalPresentValue    = 204;
  3190.              fin80x87error             = 205;
  3191.              finNoConvergence          = 206;
  3192.              finIndeterminateForm      = 207;
  3193.  
  3194.  
  3195.  
  3196.  
  3197.                                   ShFinanc  7-1
  3198.  
  3199.  
  3200.  
  3201.              {80x87 errors}
  3202.              finInvalidOperation       =  1;
  3203.              finDenormalizedOperand    =  2;
  3204.              finDivideByZero           =  4;
  3205.              finOverflow               =  8;
  3206.              finUnderflow              = 16;
  3207.  
  3208.              FW  = 17;
  3209.              DP  = 10;
  3210.              IW  =  6;
  3211.  
  3212.         Variables
  3213.         =========
  3214.              finError,
  3215.              fin87error  : word;
  3216.  
  3217.         Routines
  3218.         ========
  3219.         ____________________________
  3220.         ANNUITYAMOUNT
  3221.  
  3222.         Declaration:
  3223.              function AnnuityAmount(N : integer;
  3224.                                      I : Float;
  3225.                                      AType : AnnType) : Float;
  3226.  
  3227.         Purpose:
  3228.              To calculate the annuity amount of 1 for N periods at an
  3229.         interest rate of I.
  3230.  
  3231.         Examples:
  3232.  
  3233.         Comments:
  3234.              The annuity may be either ordinary or due, depending on the
  3235.         value of AType.
  3236.  
  3237.         See also:
  3238.              AnnuityPresVal      NumPay         IfromPresVal
  3239.  
  3240.  
  3241.  
  3242.  
  3243.  
  3244.  
  3245.  
  3246.  
  3247.  
  3248.  
  3249.  
  3250.  
  3251.  
  3252.  
  3253.  
  3254.  
  3255.                                   ShFinanc  7-2
  3256.  
  3257.  
  3258.  
  3259.         ____________________________
  3260.         ANNUITYPRESVAL
  3261.  
  3262.         Declaration:
  3263.              function AnnuityPresVal(N : integer;
  3264.                                      I : Float;
  3265.                                      AType : AnnType) : Float;
  3266.  
  3267.         Purpose:
  3268.              To calculate the annuity present value of 1 for N periods at
  3269.         an interest rate of I.
  3270.  
  3271.         Examples:
  3272.  
  3273.         Comments:
  3274.              The annuity may be either ordinary or due, depending on the
  3275.         value of AType.
  3276.  
  3277.         See also:
  3278.              AnnuityAmount       NumPay         IfromPresVal
  3279.  
  3280.  
  3281.         ____________________________
  3282.         COMPAMOUNT
  3283.  
  3284.         Declaration:
  3285.              function CompAmount(N : integer; I : Float;) : Float;
  3286.  
  3287.         Purpose:
  3288.              To calculate the compound amount of 1 for N periods at an
  3289.         interest rate of I.
  3290.  
  3291.         Examples:
  3292.  
  3293.         Comments:
  3294.  
  3295.         See also:
  3296.              CompPresVal
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.  
  3311.  
  3312.  
  3313.                                   ShFinanc  7-3
  3314.  
  3315.  
  3316.  
  3317.         ____________________________
  3318.         COMPPRESVAL
  3319.  
  3320.         Declaration:
  3321.              function CompPresVal(N : integer; I : Float;) : Float;
  3322.  
  3323.         Purpose:
  3324.              To calculate the compound present value of 1 for N periods
  3325.         at an interest rate of I.
  3326.  
  3327.         Examples:
  3328.  
  3329.         Comments:
  3330.  
  3331.         See also:
  3332.              CompAmount
  3333.  
  3334.  
  3335.         ____________________________
  3336.         FIN87ERRCODE
  3337.  
  3338.         Declaration:
  3339.              function fin87errCode : word;
  3340.  
  3341.         Purpose:
  3342.              If finErrCheckOff has been turned off and if finErrCode =
  3343.         fin80x87error, then fin87errCode will return the 80x87 error code
  3344.         resulting from the last call to a financial routine, and will
  3345.         reset the internal 80x87 error variable to 0 (finOK).
  3346.  
  3347.         Examples:
  3348.  
  3349.         Comments:
  3350.              fin87errCode should be called whenever a call to finErrCode
  3351.         returns a value of fin80x87error.
  3352.  
  3353.         See also:
  3354.              finErrChkOff   finErrCheckOn       finErrCode
  3355.              finErrMsg
  3356.  
  3357.  
  3358.  
  3359.  
  3360.  
  3361.  
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.                                   ShFinanc  7-4
  3372.  
  3373.  
  3374.  
  3375.         ____________________________
  3376.         FINERRCHECKON
  3377.  
  3378.         Declaration:
  3379.              procedure finErrCheckOn;
  3380.  
  3381.         Purpose:
  3382.              To turn error checking ON within the shFinanc unit.
  3383.  
  3384.         Examples:
  3385.  
  3386.         Comments:
  3387.              Following a call to finErrCheckOn, any errors occurring in
  3388.         any of the routines of shFinanc will cause program termination
  3389.         with an appropriate error message.
  3390.  
  3391.              The default value is ON.
  3392.  
  3393.         See also:
  3394.              fin87ErrCode   finErrCheckOff      finErrCode
  3395.              finErrMsg
  3396.  
  3397.  
  3398.         ____________________________
  3399.         FINERRCHECKOFF
  3400.  
  3401.         Declaration:
  3402.              procedure finErrCheckOff;
  3403.  
  3404.         Purpose:
  3405.              To turn error checking OFF within the shFinanc unit.
  3406.  
  3407.         Examples:
  3408.  
  3409.         Comments:
  3410.              Following a call to finErrCheckOff, any errors occurring in
  3411.         any of the routines of shFinanc will not cause program
  3412.         termination, but any error will be available through a call to
  3413.         finErrCode and the corresponding message will be available
  3414.         through a call to finErrMsg.
  3415.  
  3416.              The default value is ON.
  3417.  
  3418.         See also:
  3419.              fin87ErrCode   finErrCheckOn       finErrCode
  3420.              finErrMsg
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.  
  3429.                                   ShFinanc  7-5
  3430.  
  3431.  
  3432.  
  3433.         ____________________________
  3434.         FINERRCODE
  3435.  
  3436.         Declaration:
  3437.              function finErrCode : word;
  3438.  
  3439.         Purpose:
  3440.              If finErrCheckOff has been turned off, finErrCode will re-
  3441.         turn the error code resulting from the last call to a financial
  3442.         routine, and will reset the internal error variable to 0 (finOK).
  3443.  
  3444.         Examples:
  3445.  
  3446.         Comments:
  3447.              As with the Turbo Pascal function IoResult, finErrCode
  3448.         should be called after each call to a financial routine.
  3449.  
  3450.         See also:
  3451.              fin87ErrCode   finErrChkOff   finErrCheckOn
  3452.              finErrMsg
  3453.  
  3454.  
  3455.         ____________________________
  3456.         FINERRMSG
  3457.  
  3458.         Declaration:
  3459.              function finErrMsg(Code : word) : string;
  3460.  
  3461.         Purpose:
  3462.              To return the message corresponding to a given error code.
  3463.  
  3464.         Examples:
  3465.              The code
  3466.                        APV := AnnuityPresentValue(100, -0.95, Ordinary);
  3467.                        S := finErrMsg(finErrCode);
  3468.         will result in S conatining the string
  3469.  
  3470.                        'Interest parameter out of range.'
  3471.  
  3472.         Comments:
  3473.  
  3474.         See also:
  3475.              fin87errCode   finErrChkOff   finErrCheckOn
  3476.              finErrCode
  3477.  
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.                                   ShFinanc  7-6
  3488.  
  3489.  
  3490.  
  3491.         ____________________________
  3492.         IFROMPRESVAL
  3493.  
  3494.         Declaration:
  3495.              function IfromPresVal(PresVal : Float;
  3496.                                    N       : integer;
  3497.                                    AType   : AnnType;
  3498.                                    Err     : Float) : Float;
  3499.  
  3500.         Purpose:
  3501.              To calculate the interest rate of an annuity of 1 whose
  3502.         present value is PresVal for N payments.
  3503.  
  3504.         Examples:
  3505.  
  3506.         Comments:
  3507.              The annuity may be either ordinary or due, depending on the
  3508.         value of AType.
  3509.  
  3510.              Err is the maximum allowable absolute error of calculation.
  3511.         If the unit is compiled with {$N+}, then Err must be >= 1.0E-16.
  3512.         If compiled with {$N-}, then Err must be >= 1.0E-9.
  3513.  
  3514.         See also:
  3515.  
  3516.  
  3517.         ____________________________
  3518.         NUMPAY
  3519.  
  3520.         Declaration:
  3521.              function NumPay(PresVal,
  3522.                              I     :  Float;
  3523.                              AType :  AnnType) : integer;
  3524.  
  3525.         Purpose:
  3526.              To calculate the number of periods needed to retire a mort-
  3527.         gage of 1 whose present value is PresVal at an interest rate of I
  3528.         per period.
  3529.  
  3530.         Examples:
  3531.  
  3532.         Comments:
  3533.              The annuity may be either ordinary or due, depending on the
  3534.         value of AType.
  3535.  
  3536.         See also:
  3537.              AnnuityPresVal      IfromPresVal
  3538.  
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544.  
  3545.                                   ShFinanc  7-7
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.                        This page has been deliberately left
  3568.                          blank, except for this message.
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.  
  3596.  
  3597.  
  3598.  
  3599.  
  3600.  
  3601.  
  3602.  
  3603.                                   ShFinanc  7-8
  3604.  
  3605.  
  3606.  
  3607.  
  3608.  
  3609.  
  3610.                                      ShList
  3611.  
  3612.                              A List Manipulation Unit
  3613.  
  3614.  
  3615.         INTRODUCTION
  3616.              Lists, rings, and stacks are among the most common data
  3617.         structures used (after arrays). They are also probably among the
  3618.         worst offenders when it comes to "re-inventing the wheel." Many
  3619.         programmers build special purpose list manipulation routines each
  3620.         time a list is needed. Obviously, a generic list manipulation
  3621.         package is a valuable addition to the available "bag of tricks."
  3622.  
  3623.              ShList contains all of the routines necessary to establish
  3624.         and manipulate singly and doubly linked lists, rings, and stacks.
  3625.         The data associated with any given list, ring, or stack can be
  3626.         any standard or user defined data type. The structure of the data
  3627.         can change, but the total length of the data must remain con-
  3628.         stant. Thus, for example, variant records can be used.
  3629.  
  3630.              Stacks do not constitute a separate entity; their establish-
  3631.         ment and manipulation is accomplished by setting up a singly
  3632.         linked list, and restricting oneself to slPush and slPop respec-
  3633.         tively for data storage and retrieval.
  3634.  
  3635.              Rings also do not constitute a separate entity. Both the
  3636.         singly and doubly linked list are, in fact, treated as rings.
  3637.         When traversing a list of either type (e.g., using xxGetNext),
  3638.         retrieval will fail with the next call following retrieval of the
  3639.         last list element. If xxGetNext is called again, however, the
  3640.         element at the head of the list will be retrieved. Thus, the
  3641.         entity has all the functionality of a ring.
  3642.  
  3643.  
  3644.         NOMENCLATURE
  3645.              The names of the routines within ShList which apply to
  3646.         singly linked lists are prefixed with the letters "sl", as
  3647.         "slPut", "slAppend", etc. Those applying to doubly linked lists
  3648.         have a "dl" prefix.
  3649.  
  3650.              Many of the routines have identical functions, and differ
  3651.         only in the type of entity which they manipulate. Such routines
  3652.         have similar names, differing only in the prefix as described
  3653.         above; for example (slPut, dlPut), (slPush, dlPush). These will
  3654.         be discussed together in the following documentation.
  3655.  
  3656.  
  3657.  
  3658.  
  3659.  
  3660.  
  3661.                                    ShList  8-1
  3662.  
  3663.  
  3664.  
  3665.              In most cases, the call to a routine will have as one of its
  3666.         parameters an untyped "var" parameter called DataRec. The data to
  3667.         be placed on or retrieved from the list is passed to/from the
  3668.         routine through this parameter. Since it is an untyped parameter,
  3669.         it is up to you to make sure that the data being passed is of the
  3670.         proper length and structure. Examples are provided with the
  3671.         description of each routine.
  3672.  
  3673.  
  3674.                                !!CAUTIONARY NOTE!!
  3675.  
  3676.              MARK/RELEASE must not be used for heap management when
  3677.              using this unit. GETMEM/FREEMEM or NEW/DISPOSE must be
  3678.              used instead.
  3679.  
  3680.                            !!END OF CAUTIONARY NOTE!!
  3681.  
  3682.  
  3683.         INTERFACED ELEMENTS
  3684.  
  3685.         Types
  3686.         =====
  3687.              slNodePtr = ^slNode;
  3688.              slNode    = record
  3689.                            Data  : pointer;
  3690.                            Next  : slNodePtr;
  3691.                            end;
  3692.              dlNodePtr = ^dlNode;
  3693.              dlNode    = record
  3694.                            Data  : pointer;
  3695.                            Next,
  3696.                            Prev  : dlNodePtr;
  3697.                            end;
  3698.  
  3699.              These are the basic node structures of the nodes for singly
  3700.         and doubly linked nodes. They will be of no particular interest
  3701.         to you unless you need to modify the code of the unit.
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714.  
  3715.  
  3716.  
  3717.  
  3718.  
  3719.                                    ShList  8-2
  3720.  
  3721.  
  3722.  
  3723.              slList    = record
  3724.                            DataRecSize : word;
  3725.                            Count       : LongInt;
  3726.                            Head,
  3727.                            Tail,
  3728.                            Current     : slNodePtr;
  3729.                            end;
  3730.              dlList    = record
  3731.                            DataRecSize : word;
  3732.                            Count       : LongInt;
  3733.                            Head,
  3734.                            Tail,
  3735.                            Current     : dlNodePtr;
  3736.                            end;
  3737.  
  3738.              These are the structures of the singly and doubly linked
  3739.         lists, respectively. You will be passing a variable of one of
  3740.         these types to almost all of the routines in the unit. The actual
  3741.         details of the structure need not concern you, however, unless
  3742.         you need to modify the code of the unit.
  3743.  
  3744.  
  3745.              dlLessFunc = function(var DataRec1, DataRec2)  : boolean;
  3746.  
  3747.              This is the form of a function which you will need to con-
  3748.         struct if you are using the dlPutSorted routine. It is used to
  3749.         determine the sort order of your data records. Its use is identi-
  3750.         cal in concept to the "less" function of the TurboSort, TpSort,
  3751.         or OpSort units.
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.  
  3774.  
  3775.  
  3776.  
  3777.                                    ShList  8-3
  3778.  
  3779.  
  3780.  
  3781.         Routines
  3782.         ========
  3783.              Many of the routines have identical functions, and differ
  3784.         only in the type of entity which they manipulate. These will be
  3785.         discussed together in the following documentation.
  3786.  
  3787.              The following routines are interfaced in ShList. They are
  3788.         arranged alphabetically by basic function or routine name.
  3789.  
  3790.         ____________________________
  3791.         APPEND
  3792.  
  3793.         Declarations:
  3794.              function slAppend(var L : slList; var DataRec) : boolean;
  3795.              function dlAppend(var L : dlList; var DataRec) : boolean;
  3796.  
  3797.         Purpose:
  3798.              Appends a data record to an existing list. If the list is
  3799.         empty, Append simply places the record in the list.
  3800.  
  3801.         Comments:
  3802.              The list must have been initialized prior to calling Append.
  3803.         Append returns a value of "false" if insufficient heap space is
  3804.         available for allocation of the node and data record.
  3805.  
  3806.         Example:
  3807.              if not slAppend(MyList, MyDataRecord) then begin
  3808.                {Execute your recovery code}
  3809.                end;
  3810.  
  3811.         See Also:
  3812.              Put, PutPrev, PutSorted, Push
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.  
  3821.  
  3822.  
  3823.  
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.                                    ShList  8-4
  3836.  
  3837.  
  3838.  
  3839.         ____________________________
  3840.         COUNT
  3841.  
  3842.         Declarations:
  3843.              function slCount(L : slList) : LongInt;
  3844.              function dlCount(L : dlList) : LongInt;
  3845.  
  3846.         Purpose:
  3847.              Returns the number of items currently in the list.
  3848.  
  3849.         Comments:
  3850.              The item count is maintained continuously within the list
  3851.         structure, so it is not necessary to scan the list in order to
  3852.         generate the count.
  3853.  
  3854.         Example:
  3855.              for T1 := 1 to slCount(MyList) do begin
  3856.                if slPop(MyList, MyDataRec) then ;
  3857.                (* Now process the record *)
  3858.                end; {for T1 := ...}
  3859.  
  3860.              This code will process each record in the list, and the list
  3861.         will be left empty on loop exit.
  3862.  
  3863.  
  3864.         ____________________________
  3865.         FREE
  3866.  
  3867.         Declarations:
  3868.              procedure slFree(var L : slList);
  3869.              procedure dlFree(var L : dlList);
  3870.  
  3871.         Purpose:
  3872.              Releases the heap space allocated for a list and its data.
  3873.  
  3874.         Comments:
  3875.              This procedure should be called as soon as you have com-
  3876.         pleted your operations on the specified list. The list must be
  3877.         re-initialized if it is to be reused.
  3878.  
  3879.         Example:
  3880.              slFree(MyList);
  3881.  
  3882.              All heap space associated with "MyList" is released, follow-
  3883.         ing which all the internal pointers of "MyList" are set to "nil"
  3884.         and the associated data record length is set to zero.
  3885.  
  3886.         See Also:
  3887.              Init
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.                                    ShList  8-5
  3894.  
  3895.  
  3896.  
  3897.         ____________________________
  3898.         GETCURRENT
  3899.  
  3900.         Declarations:
  3901.              function slGetCurrent(var L : slList;
  3902.                                                   var DataRec) : boolean;
  3903.              function dlGetCurrent(var L : dlList;
  3904.                                                   var DataRec) : boolean;
  3905.  
  3906.         Purpose:
  3907.              Returns the data record at the current node and does not
  3908.         move the node pointer. Returns a function value of false if the
  3909.         list is empty or the current node pointer is nil.
  3910.  
  3911.         Comments:
  3912.              This is essentially a "reread" operation. Normally, the cur-
  3913.         rent node pointer will have been positioned during the course of
  3914.         some other operation (e.g., GetFirst) and the data record will
  3915.         have been returned as a result of that prior operation.
  3916.  
  3917.         Example:
  3918.              if not slGetCurrent(MyList, MyDataRec) then begin
  3919.                {Trying to read an empty list.}
  3920.                end;
  3921.  
  3922.         See Also:
  3923.              GetFirst GetNext GetLast GetPrev
  3924.  
  3925.  
  3926.         ____________________________
  3927.         GETFIRST
  3928.  
  3929.         Declarations:
  3930.              function slGetFirst(var L : slList; var DataRec) : boolean;
  3931.              function dlGetFirst(var L : dlList; var DataRec) : boolean;
  3932.  
  3933.         Purpose:
  3934.              Returns the data record at the head of the list. Sets the
  3935.         current node pointer to the head of the list. Returns a function
  3936.         value of false if the list is empty.
  3937.  
  3938.         Comments:
  3939.  
  3940.         Example:
  3941.              if not slGetFirst(MyList, MyDataRec) then begin
  3942.                {Trying to read an empty list.}
  3943.                end;
  3944.  
  3945.         See Also:
  3946.              GetCurrent GetNext GetLast GetPrev
  3947.  
  3948.  
  3949.  
  3950.  
  3951.                                    ShList  8-6
  3952.  
  3953.  
  3954.  
  3955.         ____________________________
  3956.         GETLAST
  3957.  
  3958.         Declarations:
  3959.              function slGetLast(var L : slList; var DataRec) : boolean;
  3960.              function dlGetLast(var L : dlList; var DataRec) : boolean;
  3961.  
  3962.         Purpose:
  3963.              Returns the data record at the tail of the list. Sets the
  3964.         current node pointer to the tail of the list. Returns a function
  3965.         value of false if the list is empty.
  3966.  
  3967.         Comments:
  3968.  
  3969.         Example:
  3970.              if not slGetLast(MyList, MyDataRec) then begin
  3971.                {Trying to read an empty list.}
  3972.                end;
  3973.  
  3974.         See Also:
  3975.              GetCurrent GetFirst GetNext GetPrev
  3976.  
  3977.  
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.  
  3991.  
  3992.  
  3993.  
  3994.  
  3995.  
  3996.  
  3997.  
  3998.  
  3999.  
  4000.  
  4001.  
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.                                    ShList  8-7
  4010.  
  4011.  
  4012.  
  4013.         ____________________________
  4014.         GETNEXT
  4015.  
  4016.         Declarations:
  4017.              function slGetNext(var L : slList; var DataRec) : boolean;
  4018.              function dlGetNext(var L : dlList; var DataRec) : boolean;
  4019.  
  4020.         Purpose:
  4021.              Returns the next data record in the list. Sets the current
  4022.         node pointer to the record retrieved. Returns a function value of
  4023.         false if the list is empty or if the last record successfully
  4024.         retrieved was at the list tail. In this latter case, calling
  4025.         slGetNext or dlGetNext again will retrieve the head of the list.
  4026.  
  4027.         Comments:
  4028.  
  4029.         Example:
  4030.           {The following example assumes boolean short-circuiting ($B-)}
  4031.              if (not slGetNext(MyList, MyDataRec))
  4032.                {slGetNext false means an empty list or end of list}
  4033.                and slGetNext(MyList, MyDataRec) then begin
  4034.                {processing the head of the list}
  4035.                end
  4036.              else begin
  4037.                {processing the normal "next" element in the list}
  4038.                end;
  4039.  
  4040.         See Also:
  4041.              GetCurrent GetFirst GetLast GetPrev
  4042.  
  4043.  
  4044.  
  4045.  
  4046.  
  4047.  
  4048.  
  4049.  
  4050.  
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.  
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.  
  4066.  
  4067.                                    ShList  8-8
  4068.  
  4069.  
  4070.  
  4071.         ____________________________
  4072.         GETPREV
  4073.  
  4074.         Declarations:
  4075.              function dlGetPrev(var L : dlList; var DataRec) : boolean;
  4076.  
  4077.         Purpose:
  4078.              Same as dlGetNext, but in the opposite direction. Returns
  4079.         the previous data record in the list. Sets the current node
  4080.         pointer to the record retrieved. Returns a function value of
  4081.         false if the list is empty or if the last record successfully
  4082.         retrieved was at the list head. In this latter case, calling
  4083.         dlGetPrev again will retrieve the tail of the list.
  4084.  
  4085.         Comments:
  4086.              Note that the GetPrev operation can only be performed on
  4087.         doubly linked lists. There is no equivalent operation for singly
  4088.         linked lists.
  4089.  
  4090.         Example:
  4091.           {The following example assumes boolean short-circuiting ($B-)}
  4092.              if (not dlGetPrev(MyList, MyDataRec))
  4093.                {dlGetPrev false means an empty list or top of list}
  4094.                and dlGetPrev(MyList, MyDataRec) then begin
  4095.                {processing the tail of the list}
  4096.                end
  4097.              else begin
  4098.                {processing the normal "prior" element in the list}
  4099.                end;
  4100.  
  4101.         See Also:
  4102.              GetCurrent GetFirst GetLast GetNext
  4103.  
  4104.  
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.  
  4112.  
  4113.  
  4114.  
  4115.  
  4116.  
  4117.  
  4118.  
  4119.  
  4120.  
  4121.  
  4122.  
  4123.  
  4124.  
  4125.                                    ShList  8-9
  4126.  
  4127.  
  4128.  
  4129.         ____________________________
  4130.         LISTINIT
  4131.  
  4132.         Declarations:
  4133.              procedure slListInit(var L : slList; RecSize : word);
  4134.              procedure dlListInit(var L : dlList; RecSize : word);
  4135.  
  4136.         Purpose:
  4137.              Initializes a singly or doubly linked list, as appropriate.
  4138.  
  4139.         Comments:
  4140.              The list initialization routines initialize only the vari-
  4141.         ables of type slList or dlList. They perform no memory alloca-
  4142.         tion. Memory allocation is performed only by the various PUT
  4143.         routines.
  4144.  
  4145.              The ListInit routines **must** be called before any attempt
  4146.         is made to place any data in, or retrieve any data from any
  4147.         LIST-type variable. Also, once an initialized list has received
  4148.         data, ListInit **must not** be called prior to a call to Free.
  4149.         Failure to observe either of these warnings will produce
  4150.         unpredictable but probably disastrous results.
  4151.  
  4152.         Example:
  4153.              slListInit(MyList, SizeOf(MyDataRec));
  4154.  
  4155.              Initializes MyList, establishing it to accept data records
  4156.         of length SizeOf(MyDataRec).
  4157.  
  4158.         See Also:
  4159.              Free
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.  
  4175.  
  4176.  
  4177.  
  4178.  
  4179.  
  4180.  
  4181.  
  4182.  
  4183.                                    ShList  8-10
  4184.  
  4185.  
  4186.  
  4187.         ____________________________
  4188.         POP
  4189.  
  4190.         Declarations:
  4191.              function slPop(var L : slList; var DataRec) : boolean;
  4192.              function dlPop(var L : dlList; var DataRec) : boolean;
  4193.  
  4194.         Purpose:
  4195.              Returns the data record at the head of the list, then deal-
  4196.         locates the space associated with the data record and node, then
  4197.         adjusts xxList.Head and xxList.Current to point to the new list
  4198.         head. Returns a function value of false if the list is empty.
  4199.  
  4200.         Comments:
  4201.  
  4202.         Example:
  4203.              while slPop(MyList, MyDataRec) do begin
  4204.                {process the retrieved record}
  4205.                end;
  4206.  
  4207.              This code will retrieve each record on the list and free up
  4208.         the space associated with each, as it is retrieved. You will end
  4209.         up with an empty list.
  4210.  
  4211.         See Also:
  4212.              Push Free
  4213.  
  4214.  
  4215.         ____________________________
  4216.         PUSH
  4217.  
  4218.         Declarations:
  4219.              function slPush(var L : slList; var DataRec) : boolean;
  4220.              function dlPush(var L : dlList; var DataRec) : boolean;
  4221.  
  4222.         Purpose:
  4223.              Pushes a data record onto the top of the list. Returns a
  4224.         function value of false if there is insufficient heap space to
  4225.         accommodate the list node and data record.
  4226.  
  4227.         Comments:
  4228.  
  4229.         Example:
  4230.              if not slPush(MyList, MyDataRec) then begin
  4231.                {perform recovery operations}
  4232.                end;
  4233.  
  4234.         See Also:
  4235.              Append Put PutPrev PutSorted Pop
  4236.  
  4237.  
  4238.  
  4239.  
  4240.  
  4241.                                    ShList  8-11
  4242.  
  4243.  
  4244.  
  4245.         ____________________________
  4246.         PUT
  4247.  
  4248.         Declarations:
  4249.              function slPut(var L : slList; var DataRec) : boolean;
  4250.              function dlPut(var L : dlList; var DataRec) : boolean;
  4251.  
  4252.         Purpose:
  4253.              Inserts a data record following the current node; returns
  4254.         with Current pointer pointing to the new node. Returns a function
  4255.         value of false if there is insufficient heap space to accommodate
  4256.         the list node and data record.
  4257.  
  4258.         Comments:
  4259.  
  4260.         Example:
  4261.              if not slPut(MyList, MyDataRec) then begin
  4262.                {perform recovery operations}
  4263.                end;
  4264.  
  4265.         See Also:
  4266.              Append Push PutPrev PutSorted Pop
  4267.  
  4268.  
  4269.         ____________________________
  4270.         PUTPREV
  4271.  
  4272.         Declarations:
  4273.              function dlPutPrev(var L : dlList; var DataRec) : boolean;
  4274.  
  4275.         Purpose:
  4276.              Inserts a data record ahead of the current node; returns
  4277.         with current pointer directed to the new node. Returns a function
  4278.         value of false if there is insufficient heap space to accommodate
  4279.         the list node and data record.
  4280.  
  4281.         Comments:
  4282.              Note that the PutPrev operation can only be performed on
  4283.         doubly linked lists. There is no equivalent operation for singly
  4284.         linked lists.
  4285.  
  4286.         Example:
  4287.              if not dlPutPrev(MyList, MyDataRec) then begin
  4288.                {perform recovery operations}
  4289.                end;
  4290.  
  4291.         See Also:
  4292.              Append GetPrev Push Put PutSorted
  4293.  
  4294.  
  4295.  
  4296.  
  4297.  
  4298.  
  4299.                                    ShList  8-12
  4300.  
  4301.  
  4302.  
  4303.         ____________________________
  4304.         PUTSORTED
  4305.  
  4306.         Declarations:
  4307.              function dlPutSorted(var L : dlList; var DataRec;
  4308.                                            Less : dlLessFunc) : boolean;
  4309.         Purpose:
  4310.              Inserts a data record into the list in sorted order, as
  4311.         determined by the user-defined boolean function LESS. Returns a
  4312.         function value of false if there is insufficient heap space to
  4313.         accommodate the list node and data record.
  4314.  
  4315.         Comments:
  4316.              The function LESS is a user-defined boolean function whose
  4317.         declaration **must** be of the form
  4318.  
  4319.              function Less(var Rec1, Rec2) :boolean;
  4320.  
  4321.         and **must** be compiled under the FAR model.
  4322.  
  4323.              Note that the PutSorted operation can only be performed on
  4324.         doubly linked lists. There is no equivalent operation for singly
  4325.         linked lists.
  4326.  
  4327.              Note also that, to build the sorted list in descending order
  4328.         rather than ascending, it is only necessary to reverse the sense
  4329.         of the inequality in the comparison function LESS.
  4330.  
  4331.         Example:
  4332.              {$F+}
  4333.              function MyLess(var MyRec1, MyRec2) : boolean;
  4334.                begin
  4335.                  MyLess := (MyRecType(MyRec1).FieldA <
  4336.                              MyRecType(MyRec2).FieldA);
  4337.                  end;
  4338.              {$F-}
  4339.              ...
  4340.              if not dlPutSorted(MyList, MyDataRec, @MyLess) then begin
  4341.                {do something}
  4342.                end;
  4343.  
  4344.              Incorrect!!! The @-symbol cannot be used here.
  4345.  
  4346.  
  4347.              if not dlPutSorted(MyList, MyDataRec, MyLess) then begin
  4348.                {do something}
  4349.                end;
  4350.  
  4351.              Correct. Only the function name is passed.
  4352.  
  4353.         See Also:
  4354.  
  4355.  
  4356.  
  4357.                                    ShList  8-13
  4358.  
  4359.  
  4360.  
  4361.              Append GetPrev Push Put PutPrev
  4362.  
  4363.  
  4364.         ____________________________
  4365.         SPACEUSED
  4366.  
  4367.         Declarations:
  4368.              function slSpaceUsed(L : slList) : LongInt;
  4369.              function dlSpaceUsed(L : dlList) : LongInt;
  4370.  
  4371.         Purpose:
  4372.              Returns the total amount of heap space currently allocated
  4373.         to the list and its data.
  4374.  
  4375.         Comments:
  4376.  
  4377.         Example:
  4378.              WriteLn(slSpaceUsed(MyList), ' total bytes used');
  4379.  
  4380.         See Also:
  4381.              Count
  4382.  
  4383.  
  4384.         Undocumented interfaced elements
  4385.         ================================
  4386.              These elements are intended for debugging during SkyHawk
  4387.         development, or are for internal use.
  4388.  
  4389.              function Ptr2Str(P : pointer) : string;
  4390.  
  4391.  
  4392.  
  4393.  
  4394.  
  4395.  
  4396.  
  4397.  
  4398.  
  4399.  
  4400.  
  4401.  
  4402.  
  4403.  
  4404.  
  4405.  
  4406.  
  4407.  
  4408.  
  4409.  
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.                                    ShList  8-14
  4416.                                                          05/24/94 01:33pm
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.                                     ShLngStr
  4424.  
  4425.                          A Long String Manipulation Unit
  4426.  
  4427.  
  4428.         INTRODUCTION
  4429.              ShLngStr is a unit which provides the ability to manipulate
  4430.         long strings (up to 65517 characters in length) using Turbo Pas-
  4431.         cal. As such, it owes a debt to the Tp/OpASCIIZ units published
  4432.         by TurboPower Software. Unlike the ASCIIZ manipulation units,
  4433.         however, it carries its dynamic string length information in a
  4434.         WORD at the beginning of the string. As such, it owes a debt to
  4435.         the TpWrdStr unit written by Ken Henderson.
  4436.  
  4437.              Both TpWrdStr and Tp/OpASCIIZ require a careful tradeoff on
  4438.         the part of the user. They both typically allocate an "array of
  4439.         char" in the data segment, in which the string data are stored;
  4440.         thus they both define a MaxSize constant which must be carefully
  4441.         balanced between providing a maximum string length long enough to
  4442.         get the job done, and one which is small enough to avoid using up
  4443.         the entire data segment.
  4444.  
  4445.              ShLngStr avoids this problem. ShLngStr stores all of its
  4446.         string data on the heap. When a variable is declared to be of
  4447.         type LongString, this declaration establishes only a pointer in
  4448.         the data segment. The LongString must then be initialized prior
  4449.         to use. This initialization establishes a maximum allowable
  4450.         string length, which may now vary from one LongString to the
  4451.         next. Only the amount of heap space required for the initialized
  4452.         maximum length is used. In this respect, the analog of a string
  4453.         declaration of, for example, "var string[127];" has been pre-
  4454.         served. Any of the procedures and functions in this unit will
  4455.         observe the "declared" maximum length, and will adjust their
  4456.         behavior appropriately
  4457.  
  4458.              Thus, although a MaxLongString constant is included in the
  4459.         unit, its value is set to the maximum allowable value (65517) and
  4460.         is used only by lsInit.
  4461.  
  4462.              Notwithstanding any of the above, the code in ShLngStr is
  4463.         completely our own. Any bugs or deficiencies cannot be blamed on
  4464.         anyone other than Madison & Associates.
  4465.  
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.                                   ShLngStr  9-1
  4475.  
  4476.  
  4477.  
  4478.         OVERVIEW
  4479.              There are currently approximately 80 procedures and func-
  4480.         tions available within the ShLngStr unit. With few exceptions,
  4481.         each procedure has a corresponding function; e.g., procedure
  4482.         lsStr2LongString which converts a string to a LongString has a
  4483.         corresponding function lsStr2LongStringF. It is important to
  4484.         remember that the functions which return a LongString are return-
  4485.         ing a pointer value rather than the contents of the LongString
  4486.         itself. Failure to account for this can result in rather startl-
  4487.         ing results on occasion.
  4488.  
  4489.              Function results (i.e., these pointers) are stored in a ring
  4490.         buffer which is allocated as needed, and is only reallocated when
  4491.         the ring pointer comes back around to the specific element. By
  4492.         default, the number of elements in the ring is set to 25. This
  4493.         should be sufficient for most purposes; should it prove insuffi-
  4494.         cient, set the typed constant RingSize to a larger value and re-
  4495.         compile. Alternatively, RingSize can be increased at execution
  4496.         time to a maximum value of 100; it should NOT be decreased at
  4497.         execution time, however. It can be set to a maximum of 100
  4498.         without affecting the size of the data segment.
  4499.  
  4500.              Since the data associated with function (pointer) returns
  4501.         are accessible only through elements in the ring buffer, and
  4502.         since the heap space used to store these data will be released
  4503.         when the ring element is required for reuse, it is important that
  4504.         these data be used as quickly as possible. They ain't gonna be
  4505.         around forever!
  4506.  
  4507.              Thus, the rule of thumb should be "when in doubt, use
  4508.         procedure calls."
  4509.  
  4510.                                !!CAUTIONARY NOTE!!
  4511.  
  4512.              MARK/RELEASE must not be used for heap management when
  4513.              using this unit. GETMEM/FREEMEM or NEW/DISPOSE must be
  4514.              used instead.
  4515.  
  4516.                            !!END OF CAUTIONARY NOTE!!
  4517.  
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.  
  4531.  
  4532.                                   ShLngStr  9-2
  4533.  
  4534.  
  4535.  
  4536.         INTERFACED ELEMENTS
  4537.  
  4538.         Types
  4539.         =====
  4540.  
  4541.              NOTE: Because of the way in which LongStringType is
  4542.              defined, if the ShLngStr unit is recompiled, range
  4543.              checking MUST be turned off ({$R-}). Note also that
  4544.              redefining the lsData field as array[1..MaxLongString]
  4545.              will cause other problems. This redefinition is defi-
  4546.              nitely NOT RECOMMENDED!
  4547.  
  4548.              LongStringType  = record
  4549.                                  Length,                {Dynamic length}
  4550.                                  dLength : word;   {"Declared" length}
  4551.                                  lsData  : array[1..1] of char;
  4552.                                  end;
  4553.              The record structure allocated on the heap for the storage
  4554.         of LongString data.
  4555.  
  4556.              LongString      = ^LongStringType;
  4557.              The type expected as actual parameters to the routines in
  4558.         this unit; also, the type returned by most of the functions.
  4559.  
  4560.              lsCompType      = (Less, Equal, Greater);
  4561.              The type returned by the LongString comparison functions.
  4562.  
  4563.              lsDelimSetType  = set of char;
  4564.              The type of the set of characters which the GetNext routines
  4565.         will use as word delimiters.
  4566.  
  4567.              CharSet         = set of Char;
  4568.  
  4569.  
  4570.         Constants
  4571.         =========
  4572.              RingSize : byte = 25;
  4573.              The number of elements in the ring buffer, used to store
  4574.         pointers returned by function calls of type LongString. This
  4575.         value may be freely increased to a maximum value of 100 during
  4576.         program execution, if necessary. Decreasing it, however, could
  4577.         result in orphan blocks allocated on the heap, with no way to
  4578.         recover them.
  4579.  
  4580.              lsDelimSet  : lsDelimSetType = [#0..#32];
  4581.              The typed constant used by the GetNext routines to determine
  4582.         the end of a substring to be returned. It may be freely changed
  4583.         during program execution.
  4584.  
  4585.  
  4586.  
  4587.  
  4588.  
  4589.  
  4590.                                   ShLngStr  9-3
  4591.  
  4592.  
  4593.  
  4594.              MaxLongString = 65517;
  4595.              The maximum length of a LongString.
  4596.  
  4597.              lsNotFound          = 0;
  4598.              Returned by the lsPos functions if a substring is not found.
  4599.  
  4600.              lsOK                = 0;
  4601.              The last LongString operation was completed successfully.
  4602.  
  4603.              lsInitError         = 250;
  4604.              System initialization has not been performed due to an
  4605.         unspecified error.
  4606.  
  4607.              lsStringTooLong     = 251;
  4608.              An attempt has been made to initialize a LongString to a
  4609.         length in excess of MaxLongString.
  4610.  
  4611.              lsAllocError        = 252;
  4612.              Not enough heap space was available to allocate the
  4613.         LongString.
  4614.  
  4615.              lsRingAllocError         = 253;
  4616.              Not enough heap space was available to allocate the
  4617.         LongString from the ring buffer.
  4618.  
  4619.  
  4620.         Nomenclature
  4621.         ============
  4622.              All interfaced routines in ShLngStr have "ls" as the first
  4623.         two characters of their name.
  4624.  
  4625.              In the descriptive listings which follow, all routines hav-
  4626.         ing similar functionality are grouped, and all routines within a
  4627.         group have names which differ only in their respective suffixes;
  4628.         e.g.,
  4629.  
  4630.                         lsDelAll
  4631.                         lsDelAllF
  4632.                         lsDelAllStr
  4633.                         lsDelAllStrF
  4634.                         lsDelAllUC
  4635.                         lsDelAllUCF
  4636.                         lsDelAllStrUC
  4637.                         lsDelAllStrUCF
  4638.  
  4639.              These routines delete all occurrences of an entity from a
  4640.         LongString. The basic procedure, lsDelAll, takes three parameters
  4641.         of type LongString; respectively, the input LongString containing
  4642.         the data to be scanned, the input LongString containing the
  4643.         entity to be deleted from the first, and the output LongString
  4644.  
  4645.  
  4646.  
  4647.  
  4648.                                   ShLngStr  9-4
  4649.  
  4650.  
  4651.  
  4652.         which is a copy of the input data LongString with all occurrences
  4653.         of the second parameter deleted.
  4654.  
  4655.              The "F" suffixes on the second, fourth, sixth, and eighth
  4656.         names indicate a function call returning the output LongString.
  4657.  
  4658.              The "Str" suffix on the third, fourth, seventh, and eighth
  4659.         names indicates that the entity to be deleted is a string rather
  4660.         than a LongString.
  4661.  
  4662.              The "UC" suffix on the fifth through the eighth names
  4663.         indicate that searching and deletion will be performed all in
  4664.         upper case; the searching will not be case sensitive.
  4665.  
  4666.              Some functions exist which do not have the "F" suffix. In
  4667.         each such case, the returned value is a normal Turbo Pascal data
  4668.         type; specifically, WORD or STRING.
  4669.  
  4670.              In the following, the ordering is alphabetic by primary
  4671.         routine name.
  4672.  
  4673.  
  4674.         Routines
  4675.         ========
  4676.         ____________________________
  4677.         lsCENTER
  4678.  
  4679.         Declarations:
  4680.              procedure lsCenter
  4681.                   (A: LongString; Width: word; B: LongString);
  4682.              function lsCenterF
  4683.                   (A: LongString; Width: word): LongString;
  4684.  
  4685.         Purpose:
  4686.              Return a LongString centered in a LongString of blanks with
  4687.         specified width.
  4688.  
  4689.         Examples:
  4690.              If             A contains "abcdefg"
  4691.              then           lsCenter(A, 13, B);
  4692.              results in     B containing "   abcdefg   "
  4693.  
  4694.         Comments:
  4695.              If the length of A already exceeds Width, A will be returned
  4696.         unchanged.
  4697.  
  4698.         See Also:
  4699.              lsCenterCh
  4700.  
  4701.  
  4702.  
  4703.  
  4704.  
  4705.  
  4706.                                   ShLngStr  9-5
  4707.  
  4708.  
  4709.  
  4710.         ____________________________
  4711.         lsCENTERCH
  4712.  
  4713.         Declarations:
  4714.              procedure lsCenterCh
  4715.                   (A: LongString; Ch: Char; Width: word; B: LongString);
  4716.              function lsCenterChF
  4717.                   (A: LongString; Ch: Char; Width: word): LongString;
  4718.  
  4719.         Purpose:
  4720.              Return a LongString centered in a LongString of Ch with spe-
  4721.         cified width.
  4722.  
  4723.         Examples:
  4724.              If             A contains "abcdefg"
  4725.              then           lsCenterCh(A, '+', 13, B);
  4726.              results in     B containing "+++abcdefg+++"
  4727.  
  4728.         Comments:
  4729.              If the length of A already exceeds Width, A will be returned
  4730.         unchanged.
  4731.  
  4732.         See Also:
  4733.              lsCenter
  4734.  
  4735.  
  4736.         ____________________________
  4737.         lsCHARSTR
  4738.  
  4739.         Declarations:
  4740.              procedure lsCharStr
  4741.                   (Ch: Char; Len: word; A: LongString);
  4742.              function lsCharStrF
  4743.                   (Ch: Char; Len: word): LongString;
  4744.  
  4745.         Purpose:
  4746.              Return a LongString of length Len filled with Ch.
  4747.  
  4748.         Examples:
  4749.              The call       lsCharStr('+', 10, A);
  4750.              results in     A containing "++++++++++"
  4751.  
  4752.         Comments:
  4753.              If Len is greater than the maximum length of A, the returned
  4754.         LongString will be equal in length to the maximum length of A.
  4755.  
  4756.         See Also:
  4757.  
  4758.  
  4759.  
  4760.  
  4761.  
  4762.  
  4763.  
  4764.                                   ShLngStr  9-6
  4765.  
  4766.  
  4767.  
  4768.         ____________________________
  4769.         lsCOMP
  4770.  
  4771.         Declarations:
  4772.              function lsComp
  4773.                   (A1, A2: LongString): lsCompType;
  4774.  
  4775.         Purpose:
  4776.              Compares A1 to A2, returning LESS, EQUAL, or GREATER.
  4777.  
  4778.         Examples:
  4779.                 For a normal COMPARE,
  4780.                         case lsComp(LS1, LS2) of
  4781.                           LESS    : {Do This}
  4782.                           EQUAL   : {Do That}
  4783.                           GREATER : {Do The Other}
  4784.                           end; {case lsComp}
  4785.  
  4786.                 For a case-insensitive COMPARE,
  4787.                         case lsComp(lsUpcaseF(LS1), lsUpcaseF(LS2)) of
  4788.                           LESS    : {Do This}
  4789.                           EQUAL   : {Do That}
  4790.                           GREATER : {Do The Other}
  4791.                           end; {case lsComp}
  4792.  
  4793.         Comments:
  4794.              This function completely implements the analog of the string
  4795.         comparison operators of Turbo Pascal.
  4796.  
  4797.         See Also:
  4798.  
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.  
  4805.  
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.                                   ShLngStr  9-7
  4823.  
  4824.  
  4825.  
  4826.         ____________________________
  4827.         lsCONCAT
  4828.  
  4829.         Declarations:
  4830.              procedure lsConcat
  4831.                   (A, B, C: LongString);
  4832.              function lsConcatF
  4833.                   (A, B: LongString): LongString;
  4834.              procedure lsConcatLs2Str
  4835.                   (S: string; A: LongString; C: LongString);
  4836.              function lsConcatLs2StrF
  4837.                   (S: string; A: LongString): LongString;
  4838.              procedure lsConcatStr2Ls
  4839.                   (A: LongString; S: string; C: LongString);
  4840.              function lsConcatStr2LsF
  4841.                   (A: LongString; S: string): LongString;
  4842.  
  4843.         Purpose:
  4844.              Concatenate the second parameter to the end of the first.
  4845.  
  4846.         Examples:
  4847.              If             A contains "abcdefg"
  4848.              and            B contains "hijklmn"
  4849.              then           lsConcat(A, B, C);
  4850.              results in     C containing "abcdefghijklmn"
  4851.  
  4852.         Comments:
  4853.  
  4854.         See Also:
  4855.  
  4856.  
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.                                   ShLngStr  9-8
  4881.  
  4882.  
  4883.  
  4884.         ____________________________
  4885.         lsCOPY
  4886.  
  4887.         Declarations:
  4888.              procedure lsCopy
  4889.                   (A: LongString; Start, Len: word; B: LongString);
  4890.              function lsCopyF
  4891.                   (A: LongString; Start, Len: word): LongString;
  4892.  
  4893.         Purpose:
  4894.              Return a LongString substring of A. The substring begins at
  4895.         position Start of A and will be of length Len.
  4896.  
  4897.         Examples:
  4898.              If             A contains "abcdefg"
  4899.              then           lsCopy(A, 4, 3, B);
  4900.              results in     B containing "def"
  4901.  
  4902.              If             A contains "abcdefg"
  4903.              then           lsCopy(A, 4, 10, B);
  4904.              results in     B containing "defg"
  4905.  
  4906.         Comments:
  4907.              Start=1 for first char in A.
  4908.  
  4909.              If Start > lsLength(A), an empty LongString will be
  4910.         returned.
  4911.  
  4912.              If Start+Len exceeds the length of A, the returned
  4913.         LongString will be of length lsLength(A)-Start+1.
  4914.  
  4915.         See Also:
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.  
  4922.  
  4923.  
  4924.  
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.                                   ShLngStr  9-9
  4939.  
  4940.  
  4941.  
  4942.         ____________________________
  4943.         lsCOUNT
  4944.  
  4945.         Declarations:
  4946.              function lsCount
  4947.                   (A, Obj: LongString):  word;
  4948.              function lsCountStr
  4949.                   (A: LongString; Obj: string): word;
  4950.              function lsCountStrUC
  4951.                   (A: LongString; Obj: string): word;
  4952.              function lsCountUC
  4953.                   (A, Obj: LongString):  word;
  4954.  
  4955.         Purpose:
  4956.              Returns the total number of non-overlapping occurrences of
  4957.         Obj in A.
  4958.  
  4959.         Examples:
  4960.              if lsCountStrUC(MyLS, 'abc') <> NotFound then {Do something}
  4961.  
  4962.              If             A contains "abcdeabcdeabcde"
  4963.              and            Obj contains "BCD"
  4964.              then           lsCount(A, Obj)
  4965.              returns        NotFound ( = 0 )
  4966.              but            lsCountUC(A, Obj)
  4967.              returns        3
  4968.  
  4969.         Comments:
  4970.              If Obj is not a substring of A, returns NotFound (i.e., 0).
  4971.  
  4972.         See Also:
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.                                   ShLngStr  9-10
  4997.  
  4998.  
  4999.  
  5000.         ____________________________
  5001.         lsDELALL
  5002.  
  5003.         Declarations:
  5004.              procedure lsDelAll
  5005.                   (A, Obj, B: LongString);
  5006.              function lsDelAllF
  5007.                   (A, Obj: LongString):  LongString;
  5008.              procedure lsDelAllStr
  5009.                   (A: LongString; Obj: string; B: LongString);
  5010.              function lsDelAllStrF
  5011.                   (A: LongString; Obj: string): LongString;
  5012.              procedure lsDelAllStrUC
  5013.                   (A: LongString; Obj: string; B: LongString);
  5014.              function lsDelAllStrUCF
  5015.                   (A: LongString; Obj: string): LongString;
  5016.              procedure lsDelAllUC
  5017.                   (A, Obj, B: LongString);
  5018.              function lsDelAllUCF
  5019.                   (A, Obj: LongString):  LongString;
  5020.  
  5021.         Purpose:
  5022.              Deletes all occurrences of Obj in A.
  5023.  
  5024.         Examples:
  5025.              See below.
  5026.  
  5027.         Comments:
  5028.              Should the deletion of Obj from A result in a new occurrence
  5029.         of Obj in A, the new occurrence will not be deleted, e.g.,
  5030.  
  5031.              If             A contains 'aabcbcabcd'
  5032.              and            Obj contains 'abc'
  5033.              then           lsDelAll(A, Obj, B);
  5034.              results in     B containing 'abcd'
  5035.              and not        'd'
  5036.  
  5037.              To delete all occurrences including such incidental
  5038.         occurrences, one would use, e.g.,
  5039.  
  5040.                             repeat
  5041.                               lsDelAll(A, Obj, A);
  5042.                               until lsCount(A, Obj) = 0;
  5043.  
  5044.         See Also:
  5045.              lsRepAll   lsCount
  5046.  
  5047.  
  5048.  
  5049.  
  5050.  
  5051.  
  5052.  
  5053.  
  5054.                                   ShLngStr  9-11
  5055.  
  5056.  
  5057.  
  5058.         ____________________________
  5059.         lsDELETE
  5060.  
  5061.         Declarations:
  5062.              procedure lsDelete
  5063.                   (A: LongString; Start, Len: word; B: LongString);
  5064.              function lsDeleteF
  5065.                   (A: LongString; Start, Len: word): LongString;
  5066.  
  5067.         Purpose:
  5068.              Delete Len characters of A, starting at position Start.
  5069.  
  5070.         Examples:
  5071.              If             A contains "abcdefg"
  5072.              then           lsDelete(A, 4, 3, B);
  5073.              results in     B containing "abcg"
  5074.  
  5075.              If             A contains "abcdefg"
  5076.              then           lsDelete(A, 4, 10, B);
  5077.              results in     B containing "abc"
  5078.  
  5079.         Comments:
  5080.              If Start is greater than the length of A, B = A on output.
  5081.  
  5082.         See Also:
  5083.              lsDelAll   lsRepAll
  5084.  
  5085.  
  5086.         ____________________________
  5087.         lsDISPOSE
  5088.  
  5089.         Declarations:
  5090.              procedure lsDispose
  5091.                   (var A: LongString);
  5092.  
  5093.         Purpose:
  5094.              Dispose of A, releasing its heap space.
  5095.  
  5096.         Examples:
  5097.              The call       lsDispose(A);
  5098.              results in     All heap space associated with A is released
  5099.              and            A = nil
  5100.  
  5101.         Comments:
  5102.  
  5103.         See Also:
  5104.              lsInit
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.  
  5111.  
  5112.                                   ShLngStr  9-12
  5113.  
  5114.  
  5115.  
  5116.         ____________________________
  5117.         lsGETNEXT
  5118.  
  5119.         Declarations:
  5120.              procedure lsGetNext
  5121.                   (LS1, LS2: LongString);
  5122.              function lsGetNextF
  5123.                   (LS1: LongString): LongString;
  5124.              procedure lsGetNextStr
  5125.                   (LS1: LongString; var S2: string);
  5126.              function lsGetNextStrF
  5127.                   (LS1: LongString): string;
  5128.  
  5129.         Purpose:
  5130.              Returns the next substring of LS1 which is delimited by a
  5131.         member of lsDelimSet.
  5132.  
  5133.         Examples:
  5134.              If             A contains "abc def ghi jkl"
  5135.              then the two calls
  5136.                             lsGetNext(A, B);
  5137.                             lsGetNext(A, B);
  5138.              result in      A containing " ghi jkl"
  5139.              and            B containing "def"
  5140.  
  5141.         Comments:
  5142.              On return, LS1 is returned untrimmed, but with the first
  5143.         matching substring deleted.
  5144.  
  5145.         See Also:
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.  
  5157.  
  5158.  
  5159.  
  5160.  
  5161.  
  5162.  
  5163.  
  5164.  
  5165.  
  5166.  
  5167.  
  5168.  
  5169.  
  5170.                                   ShLngStr  9-13
  5171.  
  5172.  
  5173.  
  5174.         ____________________________
  5175.         lsINIT
  5176.  
  5177.         Declarations:
  5178.              function lsInit
  5179.                   (var A: LongString; L: word): boolean;
  5180.  
  5181.         Purpose:
  5182.              "Declares" a LongString of maximum declared length L and
  5183.         establishes space for it on the heap.
  5184.  
  5185.         Examples:
  5186.              The call       if lsInit(A, 750) then {Do something};
  5187.              results in     a. A returned function value of "true"
  5188.                             b. 754 bytes being allocated on the heap.
  5189.                                (750 bytes for the character string,
  5190.                                 4 overhead bytes.)
  5191.                             c. A containing a pointer to the heap space.
  5192.  
  5193.              The call       lsInit(A, 65518);   {MaxLongString = 65517}
  5194.              results in     a. A returned function value of "false"
  5195.                             b. No space allocation on the heap.
  5196.                             c. A = nil
  5197.  
  5198.         Comments:
  5199.              Returns false if L is greater than MaxLongString.
  5200.  
  5201.              If there is insufficient heap space to accommodate the
  5202.         LongString, the program will terminate with a run-time error of
  5203.         250 (if lsInit has been called directly) or 251 (if lsInit has
  5204.         been called while attempting to allocate space on the ring
  5205.         buffer.
  5206.  
  5207.         See Also:
  5208.              lsDispose
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.                                   ShLngStr  9-14
  5229.  
  5230.  
  5231.  
  5232.         ____________________________
  5233.         lsIOFF
  5234.  
  5235.         Declarations:
  5236.              procedure lsIoff;
  5237.  
  5238.         Purpose:
  5239.              Turns I/O checking off during execution of lsReadLn and
  5240.         lsWriteLn.
  5241.  
  5242.         Examples:
  5243.                   lsIoff;
  5244.                   lsReadLn(MyFile, MyLS);
  5245.                   if lsIoResult <> 0 then {Do something}
  5246.                   lsIon;
  5247.  
  5248.         Comments:
  5249.              lsIoff, lsIon, and lsIoResult MUST be used for LongString
  5250.         I/O operations in place of $I-, $I+, and IoResult.
  5251.  
  5252.              Emulates at execution time the action of the $I- compiler
  5253.         directive, but only for LongString I/O. The default state is
  5254.         "on".
  5255.  
  5256.              If I/O checking is off lsIoResult MUST be called after each
  5257.         call to lsReadLn or lsWriteLn. If I/O checking is on, and if an
  5258.         I/O error occurs, the program will terminate with a run-time
  5259.         error. This action duplicates the action of the IoResult function
  5260.         for normal I/O.
  5261.  
  5262.         See Also:
  5263.              lsIon     lsIoResult
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.  
  5277.  
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.  
  5285.  
  5286.                                   ShLngStr  9-15
  5287.  
  5288.  
  5289.  
  5290.         ____________________________
  5291.         lsION
  5292.  
  5293.         Declarations:
  5294.              procedure lsIon;
  5295.  
  5296.         Purpose:
  5297.              Turns I/O checking on during execution of lsReadLn and
  5298.         lsWriteLn.
  5299.  
  5300.         Examples:
  5301.                   lsIoff;
  5302.                   lsReadLn(MyFile, MyLS);
  5303.                   if lsIoResult <> 0 then {Do something}
  5304.                   lsIon;
  5305.  
  5306.         Comments:
  5307.              lsIoff, lsIon, and lsIoResult MUST be used for LongString
  5308.         I/O operations in place of $I-, $I+, and IoResult.
  5309.  
  5310.              Emulates at execution time the action of the $I+ compiler
  5311.         directive, but only for LongString I/O. The default state is
  5312.         "on".
  5313.  
  5314.              If I/O checking is off lsIoResult MUST be called after each
  5315.         call to lsReadLn or lsWriteLn. If I/O checking is on, and if an
  5316.         I/O error occurs, the program will terminate with a run-time
  5317.         error. This action duplicates the action of the IoResult function
  5318.         for normal I/O.
  5319.  
  5320.         See Also:
  5321.              lsIoff    lsIoResult
  5322.  
  5323.  
  5324.  
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.  
  5341.  
  5342.  
  5343.  
  5344.                                   ShLngStr  9-16
  5345.  
  5346.  
  5347.  
  5348.         ____________________________
  5349.         lsIORESULT
  5350.  
  5351.         Declarations:
  5352.              function lsIoResult: word;
  5353.  
  5354.         Purpose:
  5355.              Returns the IoResult of the last lsReadLn or lsWriteLn
  5356.         performed, and clears the internal variable used to store the
  5357.         value.
  5358.  
  5359.         Examples:
  5360.                   lsIoff;
  5361.                   lsReadLn(MyFile, MyLS);
  5362.                   if lsIoResult <> 0 then {Do something}
  5363.                   lsIon;
  5364.  
  5365.         Comments:
  5366.              lsIoff, lsIon, and lsIoResult MUST be used for LongString
  5367.         I/O operations in place of $I-, $I+, and IoResult.
  5368.  
  5369.              If I/O checking is off lsIoResult MUST be called after each
  5370.         call to lsReadLn or lsWriteLn. If I/O checking is on, and if an
  5371.         I/O error occurs, the program will terminate with a run-time
  5372.         error. This action duplicates the action of the IoResult function
  5373.         for normal I/O.
  5374.  
  5375.         See Also:
  5376.              lsIoff    lsIon
  5377.  
  5378.  
  5379.  
  5380.  
  5381.  
  5382.  
  5383.  
  5384.  
  5385.  
  5386.  
  5387.  
  5388.  
  5389.  
  5390.  
  5391.  
  5392.  
  5393.  
  5394.  
  5395.  
  5396.  
  5397.  
  5398.  
  5399.  
  5400.  
  5401.  
  5402.                                   ShLngStr  9-17
  5403.  
  5404.  
  5405.  
  5406.         ____________________________
  5407.         lsINSERT
  5408.  
  5409.         Declarations:
  5410.              procedure lsInsert
  5411.                   (A, Obj: LongString; Start: word; B: LongString);
  5412.              function lsInsertF
  5413.                   (A, Obj: LongString; Start: word): LongString;
  5414.              procedure lsInsertStr
  5415.                   (A: LongString; Obj: string; Start: word;
  5416.                                                           B: LongString);
  5417.              function lsInsertStrF
  5418.                   (A: LongString; Obj: string; Start: word): LongString;
  5419.  
  5420.         Purpose:
  5421.              Insert Obj into A at position Start returning a new
  5422.         LongString.
  5423.  
  5424.         Examples:
  5425.              If             A contains "abcdef"
  5426.              and            Obj contains "ABC"
  5427.              then           lsInsert(A, Obj, 4, B);
  5428.              results in     B containing "abcABCdef"
  5429.  
  5430.         Comments:
  5431.              If Start > lsLength(A), no action is taken.
  5432.  
  5433.         See Also:
  5434.              lsDelete
  5435.  
  5436.  
  5437.  
  5438.  
  5439.  
  5440.  
  5441.  
  5442.  
  5443.  
  5444.  
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.  
  5454.  
  5455.  
  5456.  
  5457.  
  5458.  
  5459.  
  5460.                                   ShLngStr  9-18
  5461.  
  5462.  
  5463.  
  5464.         ____________________________
  5465.         lsLEFTPAD
  5466.  
  5467.         Declarations:
  5468.              procedure lsLeftPad
  5469.                   (A: LongString; Len: word; B: LongString);
  5470.              function lsLeftPadF
  5471.                   (A: LongString; Len: word): LongString;
  5472.  
  5473.         Purpose:
  5474.              Left-pad the LongString in A to length Len with blanks,
  5475.         returning a new LongString.
  5476.  
  5477.         Examples:
  5478.              If             A contains "abc"
  5479.              then           lsLeftPad(A, 5, B);
  5480.              results in     B containing "  abc"
  5481.  
  5482.         Comments:
  5483.              If Len < lsLength(A), A is returned truncated without
  5484.         padding.
  5485.  
  5486.         See Also:
  5487.              lsLeftPadCh     lsPad           lsPadCh
  5488.  
  5489.  
  5490.         ____________________________
  5491.         lsLEFTPADCH
  5492.  
  5493.         Declarations:
  5494.              procedure lsLeftPadCh
  5495.                   (A: LongString; Ch: Char; Len: word; B: LongString);
  5496.              function lsLeftPadChF
  5497.                   (A: LongString; Ch: Char; Len: word): LongString;
  5498.  
  5499.         Purpose:
  5500.              Left-pad the LongString in A to length Len with Ch,
  5501.         returning a new LongString.
  5502.  
  5503.         Examples:
  5504.              If             A contains "abc"
  5505.              then           lsLeftPad(A, '+', 5, B);
  5506.              results in     B containing "++abc"
  5507.  
  5508.         Comments:
  5509.  
  5510.         See Also:
  5511.              lsLeftPad       lsPad           lsPadCh
  5512.  
  5513.  
  5514.  
  5515.  
  5516.  
  5517.  
  5518.                                   ShLngStr  9-19
  5519.  
  5520.  
  5521.  
  5522.         ____________________________
  5523.         lsLENGTH
  5524.  
  5525.         Declarations:
  5526.              function lsLength
  5527.                   (A: LongString): word;
  5528.  
  5529.         Purpose:
  5530.              Return the length of a LongString. A must have been
  5531.         initialized.
  5532.  
  5533.         Examples:
  5534.              If             A contains "Cogito, ergo sum."
  5535.              then           lsLength(A)
  5536.              returns        17
  5537.  
  5538.         Comments:
  5539.  
  5540.         See Also:
  5541.  
  5542.  
  5543.         ____________________________
  5544.         lsLOCASE
  5545.  
  5546.         Declarations:
  5547.              procedure lsLocase
  5548.                   (A, B: LongString);
  5549.              function lsLocaseF
  5550.                   (A: LongString): LongString;
  5551.  
  5552.         Purpose:
  5553.              Locase the LongString in A, returning a new LongString.
  5554.  
  5555.         Examples:
  5556.              If             A contains "ABCdefGHIjkl"
  5557.              then           lsLocase(A, B);
  5558.              results in     B containing "abcdefghijkl"
  5559.  
  5560.         Comments:
  5561.  
  5562.         See Also:
  5563.              lsUpcase
  5564.  
  5565.  
  5566.  
  5567.  
  5568.  
  5569.  
  5570.  
  5571.  
  5572.  
  5573.  
  5574.  
  5575.  
  5576.                                   ShLngStr  9-20
  5577.  
  5578.  
  5579.  
  5580.         ____________________________
  5581.         lsLONGSTRING2STR
  5582.  
  5583.         Declarations:
  5584.              function lsLongString2Str
  5585.                   (A: LongString): string;
  5586.  
  5587.         Purpose:
  5588.              Convert a LongString to a Turbo string.
  5589.  
  5590.         Examples:
  5591.              If             A (LongString) contains "abcdef"
  5592.              then           lsLongString2Str(A)
  5593.              returns        'abcdef' (string)
  5594.  
  5595.         Comments:
  5596.              If lsLength(A) > 255, the returned string will be truncated
  5597.         to length 255.
  5598.  
  5599.         See Also:
  5600.              lsStr2LongString
  5601.  
  5602.  
  5603.         ____________________________
  5604.         lsPAD
  5605.  
  5606.         Declarations:
  5607.              procedure lsPad
  5608.                   (A: LongString; Len: word; B: LongString);
  5609.              function lsPadF
  5610.                   (A: LongString; Len: word): LongString;
  5611.  
  5612.         Purpose:
  5613.              Right-pad the LongString in A to length Len with blanks,
  5614.         returning a new LongString.
  5615.  
  5616.         Examples:
  5617.              If             A contains "abc"
  5618.              then           lsPad(A, 5, B);
  5619.              results in     B containing "abc  "
  5620.  
  5621.              but if         lsInit(C, 5) = true
  5622.              then           lsPad(A, 8, C);
  5623.              also results in  C containing "abc  "
  5624.  
  5625.         Comments:
  5626.  
  5627.         See Also:
  5628.              lsPadCh         lsLeftPad       lsLeftPadCh
  5629.  
  5630.  
  5631.  
  5632.  
  5633.  
  5634.                                   ShLngStr  9-21
  5635.  
  5636.  
  5637.  
  5638.         ____________________________
  5639.         lsPADCH
  5640.  
  5641.         Declarations:
  5642.              procedure lsPadCh
  5643.                   (A: LongString; Ch: Char; Len: word; B: LongString);
  5644.              function lsPadChF
  5645.                   (A: LongString; Ch: Char; Len: word): LongString;
  5646.  
  5647.         Purpose:
  5648.              Right-pad the LongString in A to length Len with Ch,
  5649.         returning a new LongString.
  5650.  
  5651.         Examples:
  5652.              If             A contains "abc"
  5653.              then           lsPadCh(A, '+', 5, B);
  5654.              results in     B containing "abc++"
  5655.  
  5656.              but if         lsInit(C, 5) = true
  5657.              then           lsPadCh(A, '+', 8, C);
  5658.              also results in  C containing "abc++"
  5659.  
  5660.         Comments:
  5661.  
  5662.         See Also:
  5663.              lsPad           lsLeftPad       lsLeftPadCh
  5664.  
  5665.  
  5666.  
  5667.  
  5668.  
  5669.  
  5670.  
  5671.  
  5672.  
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.  
  5682.  
  5683.  
  5684.  
  5685.  
  5686.  
  5687.  
  5688.  
  5689.  
  5690.  
  5691.  
  5692.                                   ShLngStr  9-22
  5693.  
  5694.  
  5695.  
  5696.         ____________________________
  5697.         lsPOS
  5698.  
  5699.         Declarations:
  5700.              function lsPos
  5701.                   (Obj, A: LongString): word;
  5702.              function lsPosStr
  5703.                   (Obj: string; A: LongString): word;
  5704.              function lsPosUC
  5705.                   (Obj, A: LongString): word;
  5706.              function lsPosStrUC
  5707.                   (Obj: string; A: LongString): word;
  5708.  
  5709.         Purpose:
  5710.              Return the position of Obj in A, returning NotFound if not
  5711.         found.
  5712.  
  5713.         Examples:
  5714.              If             A contains "abcdeabcdeabcde"
  5715.              and            Obj contains "BCD"
  5716.              then           lsPos(A, Obj)
  5717.              returns        NotFound ( = 0 )
  5718.              but            lsPosUC(A, Obj)
  5719.              returns        2
  5720.  
  5721.         Comments:
  5722.  
  5723.         See Also:
  5724.  
  5725.  
  5726.         ____________________________
  5727.         lsPOSSET
  5728.  
  5729.         Declaration:
  5730.              function lsPosSet(A : CharSet; S : LongString) : word;
  5731.  
  5732.         Purpose:
  5733.              Returns the position of the first occurrence of any member
  5734.         of A in S.
  5735.  
  5736.         Comments:
  5737.              This function is primarily intended for internal use.
  5738.  
  5739.         Examples:
  5740.                   If   S = 'X1Y2C3Z4B'
  5741.                   and  A = ['A','B','C']
  5742.                   then lsPosSet(A, S) will return 5.
  5743.  
  5744.         See also:
  5745.  
  5746.  
  5747.  
  5748.  
  5749.  
  5750.                                   ShLngStr  9-23
  5751.  
  5752.  
  5753.  
  5754.         ____________________________
  5755.         R
  5756.  
  5757.         Declaration:
  5758.              function R(Rexp : Float; Count : integer) : Float;
  5759.  
  5760.         Purpose:
  5761.              Returns Rexp correctly rounded to Count places to the right
  5762.         of the decimal point.
  5763.  
  5764.         Examples:
  5765.              R(1.23456, 2) returns 1.23
  5766.              R(1.23456, 3) returns 1.235)
  5767.  
  5768.         Comments:
  5769.  
  5770.         See also:
  5771.  
  5772.  
  5773.         ____________________________
  5774.         lsREADLN
  5775.  
  5776.         Declarations:
  5777.              procedure lsReadLn
  5778.                   (var F: Text; A: LongString);
  5779.  
  5780.         Purpose:
  5781.              Read a LongString from a text file.
  5782.  
  5783.         Examples:
  5784.              lsReadLn(MyFile, A);
  5785.  
  5786.         Comments:
  5787.              If the "declared" length of A (set by lsInit) is less than
  5788.         the actual length of the line in the text file, the incoming
  5789.         string will be truncated to the "declared" length of A and the
  5790.         file will be positioned at the beginning of the next line (the
  5791.         exact analog of a normal Turbo PASCAL string ReadLn).
  5792.  
  5793.              If I/O checking is off lsIoResult MUST be called after each
  5794.         call to lsReadLn or lsWriteLn. If I/O checking is on, and if an
  5795.         I/O error occurs, the program will terminate with a run-time
  5796.         error. This action duplicates the action of the IoResult function
  5797.         for normal I/O.
  5798.  
  5799.         See Also:
  5800.              lsIoff    lsIon     lsIoResult     lsWriteLn
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.  
  5807.  
  5808.                                   ShLngStr  9-24
  5809.  
  5810.  
  5811.  
  5812.         ____________________________
  5813.         lsREPALL
  5814.  
  5815.         Declarations:
  5816.              procedure lsRepAll
  5817.                   (A, Obj, Obj1, B: LongString);
  5818.              function lsRepAllF
  5819.                   (A, Obj, Obj1: LongString):  LongString;
  5820.              procedure lsRepAllStr
  5821.                   (A: LongString; Obj, Obj1: string; B: LongString);
  5822.              function lsRepAllStrF
  5823.                   (A: LongString; Obj, Obj1: string): LongString;
  5824.              procedure lsRepAllStrUC
  5825.                   (A: LongString; Obj, Obj1: string; B: LongString);
  5826.              function lsRepAllStrUCF
  5827.                   (A: LongString; Obj, Obj1: string): LongString;
  5828.              procedure lsRepAllUC
  5829.                   (A, Obj, Obj1, B: LongString);
  5830.              function lsRepAllUCF
  5831.                   (A, Obj, Obj1: LongString): LongString;
  5832.  
  5833.         Purpose:
  5834.              Replaces all occurrences of Obj in A with Obj1.
  5835.  
  5836.         Examples:
  5837.              If             A contains 'aabcbcabcd'
  5838.              and            Obj contains 'abc'
  5839.              and            Obj1 contains '12345'
  5840.              then           lsRepAll(A, Obj, Obj1, B);
  5841.              results in     B containing 'a12345bc12345d'
  5842.  
  5843.         Comments:
  5844.              Should the replacement of Obj by Obj1 in A result in a new
  5845.         occurrence of Obj in A, the new occurrence will not be replaced.
  5846.         To do so, except under rather unusual conditions, could result in
  5847.         a non-terminating condition.
  5848.  
  5849.         See Also:
  5850.              lsDelAll
  5851.  
  5852.  
  5853.  
  5854.  
  5855.  
  5856.  
  5857.  
  5858.  
  5859.  
  5860.  
  5861.  
  5862.  
  5863.  
  5864.  
  5865.  
  5866.                                   ShLngStr  9-25
  5867.  
  5868.  
  5869.  
  5870.         ____________________________
  5871.         lsSIZEOF
  5872.  
  5873.         Declarations:
  5874.              function lsSizeOf
  5875.                   (A: LongString): word;
  5876.  
  5877.         Purpose:
  5878.              Returns the total heap space required for A, including the
  5879.         two control words. A must have been initialized.
  5880.  
  5881.         Examples:
  5882.              See below.
  5883.  
  5884.         Comments:
  5885.              lsSizeOf MUST be used to determine the effective size of a
  5886.         LongString. Any attempt to use SizeOf(A) will return a value of
  5887.         4; any attempt to use SizeOf(A^) will return a value of 5.
  5888.         Neither is particularly informative!
  5889.  
  5890.              Remember that, just as
  5891.                               SizeOf(StringVariable)
  5892.         returns a value one greater than the declared length of
  5893.         StringVariable, so
  5894.                            lsSizeOf(LongStringVariable)
  5895.         will return a value four greater than the "declared" length of
  5896.         LongStringVariable.
  5897.  
  5898.              If A has not been initialized, the results are
  5899.         unpredictable.
  5900.  
  5901.         See Also:
  5902.              lsLength
  5903.  
  5904.  
  5905.  
  5906.  
  5907.  
  5908.  
  5909.  
  5910.  
  5911.  
  5912.  
  5913.  
  5914.  
  5915.  
  5916.  
  5917.  
  5918.  
  5919.  
  5920.  
  5921.  
  5922.  
  5923.  
  5924.                                   ShLngStr  9-26
  5925.  
  5926.  
  5927.  
  5928.         ____________________________
  5929.         lsSTR2LONGSTRING
  5930.  
  5931.         Declarations:
  5932.              procedure lsStr2LongString
  5933.                   (S: string; A: LongString);
  5934.              function lsStr2LongStringF
  5935.                   (S: string): LongString;
  5936.  
  5937.         Purpose:
  5938.              Convert a Turbo string into a LongString.
  5939.  
  5940.         Examples:
  5941.              If             S (string) contains "abcdef"
  5942.              then           lsStr2LongString(S, A);
  5943.              results in     A (LongString) containing "abcdef"
  5944.  
  5945.         Comments:
  5946.  
  5947.         See Also:
  5948.              lsLongString2Str
  5949.  
  5950.  
  5951.         ____________________________
  5952.         lsSYSINIT
  5953.  
  5954.         Declarations:
  5955.              procedure lsSysInit;
  5956.  
  5957.         Purpose:
  5958.              Initializes the LongString system.
  5959.  
  5960.         Examples:
  5961.  
  5962.         Comments:
  5963.              This procedure MUST be called prior to calling any other
  5964.         subroutines in the LongString package.
  5965.  
  5966.         See also:
  5967.              lsSysDeInit
  5968.  
  5969.  
  5970.  
  5971.  
  5972.  
  5973.  
  5974.  
  5975.  
  5976.  
  5977.  
  5978.  
  5979.  
  5980.  
  5981.  
  5982.                                   ShLngStr  9-27
  5983.  
  5984.  
  5985.  
  5986.         ____________________________
  5987.         lsSYSDEINIT
  5988.         Purpose:
  5989.              De-initializes the LongString package, releasing all the
  5990.         associated heap space.
  5991.  
  5992.         Examples:
  5993.  
  5994.         Comments:
  5995.              Call this procedure if you wish to recover the heap space
  5996.         used by the package. If called, it will be necessary to call
  5997.         lsSysInit again, prior to calling and of the package subroutines.
  5998.         It is not necessary to call this procedure on program exit.
  5999.  
  6000.         See also:
  6001.              lsSysInit
  6002.  
  6003.  
  6004.  
  6005.         ____________________________
  6006.         lsTRANSFER
  6007.  
  6008.         Declarations:
  6009.              procedure lsTransfer
  6010.                   (A, B: LongString);
  6011.  
  6012.         Purpose:
  6013.              Transfers the contents of A into B.
  6014.  
  6015.         Examples:
  6016.              B^ := A^;
  6017.              INCORRECT!! This construct will give unpredictable but guar-
  6018.         anteed incorrect results.
  6019.  
  6020.              lsTransfer(A, B);
  6021.              Correct. ALWAYS use lsTransfer to move the contents of one
  6022.         LongString into another.
  6023.  
  6024.         Comments:
  6025.  
  6026.         See Also:
  6027.  
  6028.  
  6029.  
  6030.  
  6031.  
  6032.  
  6033.  
  6034.  
  6035.  
  6036.  
  6037.  
  6038.  
  6039.  
  6040.                                   ShLngStr  9-28
  6041.  
  6042.  
  6043.  
  6044.         ____________________________
  6045.         lsTRIM
  6046.  
  6047.         Declarations:
  6048.              procedure lsTrim
  6049.                   (A, B: LongString);
  6050.              function lsTrimF
  6051.                   (A: LongString): LongString;
  6052.  
  6053.         Purpose:
  6054.              Return a LongString with leading and trailing white space
  6055.         removed.
  6056.  
  6057.         Examples:
  6058.              If             A contains "  Cogito, ergo sum.      "
  6059.              then           lsTrim(A, B);
  6060.              results in     B containing "Cogito, ergo sum."
  6061.  
  6062.         Comments:
  6063.              "White space" is any sequence of characters in the range
  6064.         #0..#32.
  6065.  
  6066.         See Also:
  6067.              lsTrimLead     lsTrimTrail
  6068.              lsTrimLeadSet  lsTrimSet      lsTrimTrailSet
  6069.  
  6070.  
  6071.         ____________________________
  6072.         lsTRIMLEAD
  6073.  
  6074.         Declarations:
  6075.              procedure lsTrimLead
  6076.                   (A, B: LongString);
  6077.              function lsTrimLeadF
  6078.                   (A: LongString): LongString;
  6079.  
  6080.         Purpose:
  6081.              Return a LongString with leading white space removed.
  6082.  
  6083.         Examples:
  6084.              If             A contains "  Cogito, ergo sum.      "
  6085.              then           lsTrimLead(A, B);
  6086.              results in     B containing "Cogito, ergo sum.      "
  6087.  
  6088.         Comments:
  6089.              "White space" is any sequence of characters in the range
  6090.         #0..#32.
  6091.  
  6092.         See Also:
  6093.              lsTrim         lsTrimTrail
  6094.              lsTrimLeadSet  lsTrimSet      lsTrimTrailSet
  6095.  
  6096.  
  6097.  
  6098.                                   ShLngStr  9-29
  6099.  
  6100.  
  6101.  
  6102.         ____________________________
  6103.         lsTRIMTRAIL
  6104.  
  6105.         Declarations:
  6106.              procedure lsTrimTrail
  6107.                   (A, B: LongString);
  6108.              function lsTrimTrailF
  6109.                   (A: LongString): LongString;
  6110.  
  6111.         Purpose:
  6112.           Return a LongString with trailing white space removed.
  6113.  
  6114.         Examples:
  6115.              If             A contains "  Cogito, ergo sum.      "
  6116.              then           lsTrimTrail(A, B);
  6117.              results in     B containing "  Cogito, ergo sum."
  6118.  
  6119.         Comments:
  6120.              "White space" is any sequence of characters in the range
  6121.         #0..#32.
  6122.  
  6123.         See Also:
  6124.              lsTrim         lsTrimLead
  6125.              lsTrimLeadSet  lsTrimSet      lsTrimTrailSet
  6126.  
  6127.  
  6128.         ____________________________
  6129.         lsTRIMLEADSET
  6130.         Declaration:
  6131.              procedure lsTrimLeadSet
  6132.                   (A : LongString; CS : CharSet; B : LongString);
  6133.              function lsTrimLeadSetF
  6134.                   (A : LongString; CS : CharSet) : LongString;
  6135.  
  6136.         Purpose:
  6137.              Returns a LongString with leading characters in CS stripped.
  6138.  
  6139.         Examples:
  6140.              See the file TESTLSTR.PAS
  6141.  
  6142.         Comments:
  6143.              CS contains an arbitrary set of characters.
  6144.  
  6145.         See also:
  6146.              lsTrimSet lsTrimTrailSet
  6147.              lsTrim    lsTrimLead     lsTrimTrail
  6148.  
  6149.  
  6150.  
  6151.  
  6152.  
  6153.  
  6154.  
  6155.  
  6156.                                   ShLngStr  9-30
  6157.  
  6158.  
  6159.  
  6160.         ____________________________
  6161.         lsTRIMSET
  6162.  
  6163.         Declaration:
  6164.              procedure lsTrimSet
  6165.                   (A : LongString; CS : CharSet; B : LongString);
  6166.              function lsTrimSetF
  6167.                   (A  : LongString; CS : CharSet) : LongString;
  6168.  
  6169.         Purpose:
  6170.              Returns a LongString with leading and trailing characters in
  6171.         CS stripped.
  6172.  
  6173.         Examples:
  6174.              See the file TESTLSTR.PAS
  6175.  
  6176.         Comments:
  6177.              CS contains an arbitrary set of characters.
  6178.  
  6179.         See also:
  6180.              lsTrimLeadSet  lsTrimTrailSet
  6181.              lsTrim         lsTrimLead     lsTrimTrail
  6182.  
  6183.  
  6184.         ____________________________
  6185.         lsTRIMTRAILSET
  6186.  
  6187.         Declaration:
  6188.              procedure lsTrimTrailSet
  6189.                   (A : LongString; CS : CharSet; B : LongString);
  6190.              function lsTrimTrailSetF
  6191.                   (A : LongString; CS : CharSet) : LongString;
  6192.  
  6193.         Purpose:
  6194.              Returns a LongString with trailing characters in CS
  6195.         stripped.
  6196.  
  6197.         Examples:
  6198.              See the file TESTLSTR.PAS
  6199.  
  6200.         Comments:
  6201.              CS contains an arbitrary set of characters.
  6202.  
  6203.         See also:
  6204.              lsTrimLeadSet  lsTrimSet
  6205.              lsTrim         lsTrimLead     lsTrimTrail
  6206.  
  6207.  
  6208.  
  6209.  
  6210.  
  6211.  
  6212.  
  6213.  
  6214.                                   ShLngStr  9-31
  6215.  
  6216.  
  6217.  
  6218.         ____________________________
  6219.         lsUPCASE
  6220.  
  6221.         Declarations:
  6222.              procedure lsUpcase
  6223.                   (A, B: LongString);
  6224.              function lsUpcaseF
  6225.                   (A: LongString): LongString;
  6226.  
  6227.         Purpose:
  6228.              Upcase the LongString in A, returning a new LongString.
  6229.  
  6230.         Examples:
  6231.              If             A contains "ABCdefGHIjkl"
  6232.              then           lsUpcase(A, B);
  6233.              results in     B containing "ABCDEFGHIJKL"
  6234.  
  6235.         Comments:
  6236.  
  6237.         See Also:
  6238.              lsLocase
  6239.  
  6240.  
  6241.         ____________________________
  6242.         lsWRITELN
  6243.  
  6244.         Declarations:
  6245.              procedure lsWriteLn
  6246.                   (var F: Text; A: LongString);
  6247.  
  6248.         Purpose:
  6249.              Write a LongString to a text file.
  6250.  
  6251.         Examples:
  6252.              lsWriteLn(MyFile, A);
  6253.  
  6254.         Comments:
  6255.              If I/O checking is off lsIoResult MUST be called after each
  6256.         call to lsReadLn or lsWriteLn. If I/O checking is on, and if an
  6257.         I/O error occurs, the program will terminate with a run-time
  6258.         error. This action duplicates the action of the IoResult function
  6259.         for normal I/O.
  6260.  
  6261.         See Also:
  6262.              lsIoff    lsIon     lsIoResult     lsReadLn
  6263.  
  6264.  
  6265.  
  6266.  
  6267.  
  6268.  
  6269.  
  6270.  
  6271.  
  6272.                                   ShLngStr  9-32
  6273.                                                          05/24/94 01:33pm
  6274.  
  6275.  
  6276.  
  6277.  
  6278.  
  6279.  
  6280.                                     ShUtilPk
  6281.  
  6282.                                   A Utility Unit
  6283.  
  6284.  
  6285.         INTRODUCTION
  6286.              ShUtilPk provides a number of miscellaneous utility routines
  6287.         which do not fit naturally into any of the other units of the
  6288.         SkyHawk collection.
  6289.  
  6290.  
  6291.         INTERFACED ELEMENTS
  6292.  
  6293.         Types
  6294.         =====
  6295.              DelimSetType = Set of Char;
  6296.              CharSet      = Set of Char;
  6297.  
  6298.         Constants
  6299.         =========
  6300.              DelimSet : DelimSetType = [#0..#32];
  6301.              The typed constant used by the GetNext routines to determine
  6302.         the end of a substring to be returned. It may be freely changed
  6303.         during program execution.
  6304.  
  6305.         Variables
  6306.         =========
  6307.              Two variables are interfaced, containing the video mode and
  6308.         video attribute of the system at the time the containing program
  6309.         was invoked. NEVER MODIFY THESE VARIABLES!
  6310.  
  6311.              StartingMode : Integer;
  6312.              {Initial video mode of the system (Mono, CO80, BW40, ...)}
  6313.  
  6314.              StartingAttr : Byte;
  6315.              {Initial video attribute of the system}
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.  
  6331.                                   ShUtilPk  10-1
  6332.  
  6333.  
  6334.  
  6335.         Routines
  6336.         ========
  6337.         ____________________________
  6338.         BETWS
  6339.  
  6340.         Declaration:
  6341.              function BetwS(Lower, Item, Upper  : LongInt) : boolean;
  6342.  
  6343.         Purpose:
  6344.              Performs a SIGNED test of the condition that
  6345.  
  6346.                               Lower <= Item <= Upper
  6347.  
  6348.         returning TRUE if and only if the condition is met.
  6349.  
  6350.         Comments:
  6351.              Lower, Item, and Upper can be any combination of 1, 2, and
  6352.         4-byte entities.
  6353.  
  6354.              Note that
  6355.                   BetwU($EA, $EA, $FA) = true
  6356.              whereas
  6357.                   BetwS($EA, $EA, $FA) = false
  6358.  
  6359.         Examples:
  6360.              See TESTBETW.PAS
  6361.  
  6362.         See also:
  6363.              BetwU
  6364.  
  6365.  
  6366.  
  6367.  
  6368.  
  6369.  
  6370.  
  6371.  
  6372.  
  6373.  
  6374.  
  6375.  
  6376.  
  6377.  
  6378.  
  6379.  
  6380.  
  6381.  
  6382.  
  6383.  
  6384.  
  6385.  
  6386.  
  6387.  
  6388.  
  6389.                                   ShUtilPk  10-2
  6390.  
  6391.  
  6392.  
  6393.         ____________________________
  6394.         BETWU
  6395.  
  6396.         Declaration:
  6397.              function BetwU(Lower, Item, Upper  : LongInt) : boolean;
  6398.  
  6399.         Purpose:
  6400.              Performs an UNSIGNED test of the condition that
  6401.  
  6402.                               Lower <= Item <= Upper
  6403.  
  6404.         returning TRUE if and only if the condition is met.
  6405.  
  6406.         Comments:
  6407.              Lower, Item, and Upper can be any combination of 1, 2, and
  6408.         4-byte entities.
  6409.  
  6410.              Note that
  6411.                   BetwU($EA, $EA, $FA) = true
  6412.              whereas
  6413.                   BetwS($EA, $EA, $FA) = false
  6414.  
  6415.         Examples:
  6416.              See TESTBETW.PAS
  6417.  
  6418.         See also:
  6419.              BetwS
  6420.  
  6421.  
  6422.         ____________________________
  6423.         DELALL
  6424.  
  6425.         Declaration:
  6426.              procedure DelAll(S1, DS : String; S2);
  6427.              function DelAllF(S1, DS : string) : string;
  6428.  
  6429.         Purpose:
  6430.              In string S1 delete all occurrences of DS.
  6431.  
  6432.         Comments:
  6433.  
  6434.         Examples:
  6435.              See the file TESTUTIL.PAS
  6436.  
  6437.         See also:
  6438.              RepAll
  6439.  
  6440.  
  6441.  
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.                                   ShUtilPk  10-3
  6448.  
  6449.  
  6450.  
  6451.         ____________________________
  6452.         GETNEXT
  6453.  
  6454.         Declaration:
  6455.              procedure GetNext(var S1, S2 : String);
  6456.              function GetNextF(var S1 : String) : String;
  6457.  
  6458.         Purpose:
  6459.              Returns the next leading substring of S1 which is delimited
  6460.         by a member of DelimSet.
  6461.  
  6462.         Comments:
  6463.              S1 is returned with the sub-string stripped off, but not
  6464.         trimmed. S2 or the function value is trimmed.
  6465.  
  6466.              If S1 is empty on entry, both S1 and S2 (or the function
  6467.         value) will be empty on return.
  6468.  
  6469.         Examples:
  6470.              See the file TESTUTIL.PAS
  6471.  
  6472.         See also:
  6473.  
  6474.  
  6475.  
  6476.  
  6477.  
  6478.  
  6479.  
  6480.  
  6481.  
  6482.  
  6483.  
  6484.  
  6485.  
  6486.  
  6487.  
  6488.  
  6489.  
  6490.  
  6491.  
  6492.  
  6493.  
  6494.  
  6495.  
  6496.  
  6497.  
  6498.  
  6499.  
  6500.  
  6501.  
  6502.  
  6503.  
  6504.  
  6505.                                   ShUtilPk  10-4
  6506.  
  6507.  
  6508.  
  6509.         ____________________________
  6510.         HEX
  6511.  
  6512.         Declaration:
  6513.              function HEX(A : LongInt) : String;
  6514.  
  6515.         Purpose:
  6516.              Converts any INTEGER-type variable into a string
  6517.         correspnoding to the hex value.
  6518.  
  6519.         Comments:
  6520.              The parameter A may be of any Integer type (ShortInt, Byte,
  6521.         Integer, Word, or LongInt
  6522.  
  6523.              HEX will return either a 2, 4, or 8 character string,
  6524.         depending on whether the actual value of the parameter (rather
  6525.         than its type) is representable by a
  6526.  
  6527.                             1 byte value (ShortInt, Byte)
  6528.                             2 byte value (Integer, Word)
  6529.                             4 byte value (LongInt)
  6530.  
  6531.              Note that a negative value will always be returned as an 8
  6532.         character string.
  6533.  
  6534.         Examples:
  6535.              See the file TESTUTIL.PAS
  6536.  
  6537.         See also:
  6538.  
  6539.  
  6540.         ____________________________
  6541.         HIWORD
  6542.  
  6543.         Declaration:
  6544.              function HiWord(LI : LongInt) : Word;
  6545.  
  6546.         Purpose:
  6547.              Returns the high order word of a LongInt.
  6548.  
  6549.         Comments:
  6550.              This function is the analog of the system function HI, per-
  6551.         forming the analogous operation on a LongInt to that performed by
  6552.         HI on an INTEGER or WORD.
  6553.  
  6554.         Examples:
  6555.              See the file TESTUTIL.PAS
  6556.  
  6557.         See also:
  6558.              LoWord
  6559.  
  6560.  
  6561.  
  6562.  
  6563.                                   ShUtilPk  10-5
  6564.  
  6565.  
  6566.  
  6567.         ____________________________
  6568.         LI
  6569.  
  6570.         Declaration:
  6571.              function LI(Ilo, Ihi : Word) : LongInt;
  6572.  
  6573.         Purpose:
  6574.              Converts two Word variables to a LongInt
  6575.  
  6576.         Comments:
  6577.  
  6578.         Examples:
  6579.              See the file TESTUTIL.PAS
  6580.  
  6581.         See also:
  6582.  
  6583.  
  6584.         ____________________________
  6585.         LOWORD
  6586.  
  6587.         Declaration:
  6588.              function LoWord(LI : LongInt) : Word;
  6589.  
  6590.         Purpose:
  6591.              Returns the low order word of a LongInt.
  6592.  
  6593.         Comments:
  6594.              This function is the analog of the system function LO, per-
  6595.         forming the analogous operation on a LongInt to that performed by
  6596.         LO on an INTEGER or WORD.
  6597.  
  6598.         Examples:
  6599.              See the file TESTUTIL.PAS
  6600.  
  6601.         See also:
  6602.              HiWord
  6603.  
  6604.  
  6605.  
  6606.  
  6607.  
  6608.  
  6609.  
  6610.  
  6611.  
  6612.  
  6613.  
  6614.  
  6615.  
  6616.  
  6617.  
  6618.  
  6619.  
  6620.  
  6621.                                   ShUtilPk  10-6
  6622.  
  6623.  
  6624.  
  6625.         ____________________________
  6626.         PMOD
  6627.  
  6628.         Declaration:
  6629.              function Pmod(X, Modulus : LongInt) : LongInt;
  6630.  
  6631.         Purpose:
  6632.              Returns the remainder of X on division by MODULUS as a
  6633.         positive number, regardless of the sign of X.
  6634.  
  6635.         Comments:
  6636.              Recall that, e.g., -1 is congruent to (modulus-1). Thus, for
  6637.         example, Pmod(-2, 7) will return 5 as the function value.
  6638.  
  6639.         Examples:
  6640.              (-2 mod 5) = -2
  6641.              Pmod(-2, 5) = 3
  6642.              See the file TESTUTIL.PAS
  6643.  
  6644.         See also:
  6645.  
  6646.  
  6647.         ____________________________
  6648.         POSSET
  6649.  
  6650.         Declaration:
  6651.              function PosSet(A : CharSet; S : string) : byte;
  6652.  
  6653.         Purpose:
  6654.              Returns the position of the first occurrence of any member
  6655.         of A in S.
  6656.  
  6657.         Comments:
  6658.              This function is intended primarily for internal use by
  6659.         ShUtilPk and ShCmdLin.
  6660.  
  6661.         Examples:
  6662.                   If   S = 'X1Y2C3Z4B'
  6663.                   and  A = ['A','B','C']
  6664.                   then PosSet(A, S) will return 5.
  6665.              See the file TESTUTIL.PAS
  6666.  
  6667.         See also:
  6668.  
  6669.  
  6670.  
  6671.  
  6672.  
  6673.  
  6674.  
  6675.  
  6676.  
  6677.  
  6678.  
  6679.                                   ShUtilPk  10-7
  6680.  
  6681.  
  6682.  
  6683.         ____________________________
  6684.         REPALL
  6685.  
  6686.         Declaration:
  6687.              procedure RepAll(S1, FS, SS : String; var S2 : string);
  6688.              function RepAllF(S1, FS, SS : string) : string;
  6689.  
  6690.         Purpose:
  6691.              In string S1 replace all occurrences of FS with SS
  6692.  
  6693.         Comments:
  6694.  
  6695.         Examples:
  6696.              See the file TESTUTIL.PAS
  6697.  
  6698.         See also:
  6699.              DelAll
  6700.  
  6701.  
  6702.         ____________________________
  6703.         SEARCHENVIRONMENT
  6704.  
  6705.         Declaration:
  6706.              function SearchEnvironment(Code : String) : String;
  6707.  
  6708.         Purpose:
  6709.              Searches the environment space for "CODE" and returns the
  6710.         corresponding string.
  6711.  
  6712.         Comments:
  6713.              If the CODE string has not been set with a SET statement,
  6714.         the function will return an empty string.
  6715.  
  6716.         Examples:
  6717.              If the DOS command
  6718.                                  SET GORP=FooBaz
  6719.         has been executed, then
  6720.                             SearchEnvironment('GORP')
  6721.         will return
  6722.                                      'FooBaz'
  6723.  
  6724.         See also:
  6725.  
  6726.  
  6727.  
  6728.  
  6729.  
  6730.  
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.  
  6737.                                   ShUtilPk  10-8
  6738.  
  6739.  
  6740.  
  6741.         ____________________________
  6742.         STARSTRING
  6743.  
  6744.         Declaration:
  6745.              function StarString(Pattern, Target : String) : Boolean;
  6746.  
  6747.         Purpose:
  6748.              This function performs a generalization of the wildcard
  6749.         string matching usually performed by DOS.
  6750.  
  6751.         Comments:
  6752.              The mask is presented in Pattern, and the string to be
  6753.         scanned is presented in Target. The function will return TRUE or
  6754.         FALSE as the target does or does not match the mask.
  6755.  
  6756.              A '*' wild card can be placed anywhere within the mask, and
  6757.         will represent its usual 'zero or more of any characters'. Scan-
  6758.         ning will not be terminated at that point, however, but will con-
  6759.         tinue. Thus, '*B*EFG' will match 'ABCDEFG', but '*B*EGF' will
  6760.         not. Similarly, '*ABC*' will match, but '*ABC' will not.
  6761.  
  6762.              A '?' wild card can also be placed anywhere within the mask,
  6763.         and will also represent its usual 'one occurrance of any char-
  6764.         acter'.
  6765.  
  6766.         Examples:
  6767.                   StarString('*B*EFG', 'ABCDEFG')
  6768.                                                             returns TRUE.
  6769.  
  6770.                   StarString('*B*EGF', 'ABCDEFG')
  6771.                                                             returns FALSE
  6772.                            but would return TRUE using the DOS algorithm.
  6773.              See the file TESTUTIL.PAS
  6774.  
  6775.         See also:
  6776.  
  6777.  
  6778.  
  6779.  
  6780.  
  6781.  
  6782.  
  6783.  
  6784.  
  6785.  
  6786.  
  6787.  
  6788.  
  6789.  
  6790.  
  6791.  
  6792.  
  6793.  
  6794.  
  6795.                                   ShUtilPk  10-9
  6796.  
  6797.  
  6798.  
  6799.         ____________________________
  6800.         UNIQUEFILENAME
  6801.  
  6802.         Declaration:
  6803.              function UniqueFileName
  6804.                       (Path : String; AddExt : Boolean) : string;
  6805.  
  6806.         Purpose:
  6807.              Returns a file name which will be unique in the directory
  6808.         specified by PATH.
  6809.  
  6810.         Comments:
  6811.              On return, the file name will be appended to PATH to give a
  6812.         fully qualified path.
  6813.  
  6814.              If AddExt is TRUE, an extension of .$$$ will be appended,
  6815.         else only the file name will be returned. In either case, the
  6816.         returned entity is guaranteed to be unique.
  6817.  
  6818.         Examples:
  6819.              See the file TESTUTIL.PAS
  6820.  
  6821.         See also:
  6822.  
  6823.  
  6824.         ____________________________
  6825.         WHOAMI
  6826.  
  6827.         Declaration:
  6828.              function WhoAmI : String;
  6829.  
  6830.         Purpose:
  6831.              Returns the fully qualified path to the currently executing
  6832.         file.
  6833.  
  6834.         Comments:
  6835.              Can be used with DOS 3.x or above, ONLY.
  6836.  
  6837.         Examples:
  6838.              See the file TESTUTIL.PAS
  6839.  
  6840.         See also:
  6841.  
  6842.  
  6843.  
  6844.  
  6845.  
  6846.  
  6847.  
  6848.  
  6849.  
  6850.  
  6851.  
  6852.  
  6853.                                  ShUtilPk  10-10
  6854.                                                          05/24/94 01:33pm
  6855.  
  6856.  
  6857.  
  6858.  
  6859.  
  6860.  
  6861.  
  6862.  
  6863.  
  6864.                                       Index
  6865.  
  6866.  
  6867.                80x87 errors....... 7.2     ComplexElement..... 3.3
  6868.                                            CompPresVal........ 7.4
  6869.                A                           Count.............. 8.3
  6870.                AnnType............ 7.1     CpPwrR............. 3.9
  6871.                AnnuityAmount...... 7.2     CpPwrRF............ 3.9
  6872.                AnnuityPresVal..... 7.3     CrcCalc............ 4.2
  6873.                                            CrcCopy............ 4.3
  6874.                B                           Cstr2Byte.......... 1.6
  6875.                BetwS............. 10.2     CSub.............. 3.10
  6876.                BetwU............. 10.2     CSubF............. 3.10
  6877.                                            Current............ 8.3
  6878.                C                           cxBadMagnitude..... 3.3
  6879.                C2P................ 3.3     cxDivByZero........ 3.3
  6880.                C2PF............... 3.3     cxHaltErr.......... 3.3
  6881.                CAbs............... 3.4     cxOK............... 3.3
  6882.                CAbsF.............. 3.4
  6883.                CAdd............... 3.4     D
  6884.                CAddF.............. 3.4     Data............... 8.2
  6885.                CConj.............. 3.5     DataRecSize........ 8.3
  6886.                CConjF............. 3.5     Day................ 5.2
  6887.                CDiv............... 3.5     DayStr............. 5.2
  6888.                CDivF.............. 3.5     DelAll............ 10.3
  6889.                CharSet. 2.2, 9.3, 10.1     DelAllF........... 10.3
  6890.                CheckOff........... 6.2     DelimSet.......... 10.1
  6891.                CheckOn............ 6.2     DelimSetType...... 10.1
  6892.                ClClose............ 2.3     dlAppend........... 8.4
  6893.                ClInit............. 2.3     dlCount............ 8.4
  6894.                ClParse............ 2.4     dLength............ 9.3
  6895.                Cmp2Str............ 3.6     dlFree............. 8.5
  6896.                CmplxDeInit........ 3.7     dlGetCurrent....... 8.6
  6897.                CmplxError......... 3.6     dlGetFirst......... 8.6
  6898.                CmplxInit.......... 3.7     dlGetLast.......... 8.7
  6899.                CmpP2Str........... 3.8     dlGetNext.......... 8.7
  6900.                CmpP2StrD.......... 3.8     dlGetPrev.......... 8.8
  6901.                CMul............... 3.9     dlLessFunc......... 8.3
  6902.                CMulF.............. 3.9     dlList............. 8.3
  6903.                Color Constants... 1.2,     dlListInit......... 8.9
  6904.                                    1.3     dlNode............. 8.2
  6905.                ColorName.......... 1.6     dlNodePtr.......... 8.2
  6906.                CompAmount......... 7.3     dlPop............. 8.10
  6907.                Complex............ 3.3     dlPush............ 8.11
  6908.                ComplexBaseType.... 3.3     dlPut............. 8.12
  6909.  
  6910.  
  6911.  
  6912.                                      index-xi
  6913.  
  6914.  
  6915.  
  6916.                dlPutPrev......... 8.12     HEX............... 10.4
  6917.                dlPutSorted....... 8.13     HiWord............ 10.5
  6918.                dlSpaceUsed....... 8.14
  6919.                DoW................ 5.3     I
  6920.                DP................. 7.2     IfromPresVal....... 7.7
  6921.                                            Im................. 3.3
  6922.                F                           IntVal............. 2.2
  6923.                fin87errCode....... 7.4     IW................. 7.2
  6924.                fin87error......... 7.2
  6925.                fin80x87error...... 7.1     J
  6926.                finDenormalizedOperand.     JDate2Greg......... 5.5
  6927.                                    7.2     JDN2ANSI........... 5.5
  6928.                finDivideByZero.... 7.2     JDN2Greg........... 5.6
  6929.                finErrCheckOff..... 7.5     JDN2Str............ 5.7
  6930.                finErrCheckOn...... 7.5
  6931.                finErrCode......... 7.6     L
  6932.                finErrMsg.......... 7.6     Length............. 9.3
  6933.                finError........... 7.2     LI................ 10.6
  6934.                finErrParamTooSmall....     LongString......... 9.3
  6935.                                    7.1     LongStringType..... 9.3
  6936.                finIllegalNumPeriods...     LoWord............ 10.6
  6937.                                    7.1     lsAllocError....... 9.4
  6938.                finIllegalPresentValue.     lsCenter........... 9.5
  6939.                                    7.1     lsCenterCh......... 9.6
  6940.                finIndeterminateForm...     lsCenterChF........ 9.6
  6941.                                    7.1     lsCenterF.......... 9.5
  6942.                finIntOutOfRange... 7.1     lsCharStr.......... 9.6
  6943.                finInvalidOperation....     lsCharStrF......... 9.6
  6944.                                    7.2     lsComp............. 9.7
  6945.                finNoConvergence... 7.1     lsCompType......... 9.3
  6946.                finOK.............. 7.1     lsConcat........... 9.7
  6947.                finOverflow........ 7.2     lsConcatF.......... 9.7
  6948.                finUnderflow....... 7.2     lsConcatLs2Str..... 9.7
  6949.                finUnknownAnnuityType..     lsConcatLs2StrF.... 9.7
  6950.                                    7.1     lsConcatStr2Ls..... 9.7
  6951.                FW................. 7.2     lsConcatStr2LsF.... 9.7
  6952.                                            lsCopy............. 9.8
  6953.                G                           lsCopyF............ 9.8
  6954.                GetNext........... 10.4     lsCount............ 9.9
  6955.                GetNextF.......... 10.4     lsCountStr......... 9.9
  6956.                GetSwitch.......... 2.6     lsCountStrUC....... 9.9
  6957.                Greg2ANSI.......... 5.3     lsCountUC.......... 9.9
  6958.                Greg2JDate......... 5.4     lsData............. 9.3
  6959.                Greg2JDN........... 5.4     lsDelAll.......... 9.10
  6960.                Greg2Str........... 5.6     lsDelAllF......... 9.10
  6961.                GregType........... 5.2     lsDelAllStr....... 9.10
  6962.                                            lsDelAllStrF...... 9.10
  6963.                H                           lsDelAllStrUC..... 9.10
  6964.                H.................. 5.2     lsDelAllStrUCF.... 9.10
  6965.                HaltMsg............ 6.3     lsDelAllUC........ 9.10
  6966.                Head............... 8.3     lsDelAllUCF....... 9.11
  6967.  
  6968.  
  6969.  
  6970.                                     index-xii
  6971.  
  6972.  
  6973.  
  6974.                lsDelete.......... 9.12     lsSysInit......... 9.27
  6975.                lsDeleteF......... 9.12     lsTransfer........ 9.28
  6976.                lsDelimSet......... 9.3     lsTrim............ 9.29
  6977.                lsDelimSetType..... 9.3     lsTrimF........... 9.29
  6978.                lsDispose......... 9.12     lsTrimLead........ 9.29
  6979.                lsGetNext......... 9.13     lsTrimLeadF....... 9.29
  6980.                lsGetNextF........ 9.13     lsTrimLeadSet..... 9.30
  6981.                lsGetNextStr...... 9.13     lsTrimLeadSetF.... 9.30
  6982.                lsGetNextStrF..... 9.13     lsTrimSet......... 9.31
  6983.                lsInit............ 9.13     lsTrimSetF........ 9.31
  6984.                lsInitError........ 9.4     lsTrimTrail....... 9.30
  6985.                lsInsert.......... 9.17     lsTrimTrailF...... 9.30
  6986.                lsInsertF......... 9.17     lsTrimTrailSet.... 9.31
  6987.                lsInsertStr....... 9.17     lsTrimTrailSetF... 9.31
  6988.                lsInsertStrF...... 9.17     lsUpcase.......... 9.32
  6989.                lsIoff............ 9.14     lsUpcaseF......... 9.32
  6990.                lsIon............. 9.15     lsWriteLn......... 9.32
  6991.                lsIoResult........ 9.16
  6992.                lsLeftPad......... 9.18     M
  6993.                lsLeftPadCh....... 9.19     M.................. 5.2
  6994.                lsLeftPadChF...... 9.19     MaxLongString...... 9.4
  6995.                lsLeftPadF........ 9.18     Month.............. 5.2
  6996.                lsLength.......... 9.20     MonthStr........... 5.2
  6997.                lsLocase.......... 9.20
  6998.                lsLocaseF......... 9.20     N
  6999.                lsLongString2Str.. 9.21     Name............... 2.2
  7000.                lsNotFound......... 9.4     Next............... 8.2
  7001.                lsOK............... 9.4     Now................ 5.7
  7002.                lsPad............. 9.21     Now2Time........... 5.7
  7003.                lsPadCh........... 9.22     NowStr............. 5.8
  7004.                lsPadChF.......... 9.22     NumPay............. 7.7
  7005.                lsPadF............ 9.21
  7006.                lsPos............. 9.22     O
  7007.                lsPosSet.......... 9.23     Orientation........ 1.3
  7008.                lsPosStr.......... 9.22
  7009.                lsPosStrUC........ 9.22     P
  7010.                lsPosUC........... 9.22     P2C............... 3.10
  7011.                lsReadLn.......... 9.24     P2CF.............. 3.10
  7012.                lsRepAll.......... 9.25     Pmod.............. 10.7
  7013.                lsRepAllF......... 9.25     PopSwitch.......... 2.6
  7014.                lsRepAllStr....... 9.25     PosSet............ 10.7
  7015.                lsRepAllStrF...... 9.25     Prev............... 8.2
  7016.                lsRepAllStrUC..... 9.25
  7017.                lsRepAllStrUCF.... 9.25     R
  7018.                lsRepAllUC........ 9.25     R................. 9.24
  7019.                lsRepAllUCF....... 9.25     Re................. 3.3
  7020.                lsRingAllocError... 9.4     ReadSwCh........... 2.7
  7021.                lsSizeOf.......... 9.25     RealVal............ 2.2
  7022.                lsStr2LongString.. 9.26     RepAll............ 10.8
  7023.                lsStr2LongStringF. 9.26     RepAllF........... 10.8
  7024.                lsStringTooLong.... 9.4     RingSize........... 9.3
  7025.  
  7026.  
  7027.  
  7028.                                     index-xiii
  7029.  
  7030.  
  7031.  
  7032.                RunErrorMsg........ 6.3     StartingMode...... 10.1
  7033.                RxC............... 3.11     StrVal............. 2.2
  7034.                RxCF.............. 3.11     SwRec.............. 2.2
  7035.                                            SwVal.............. 2.2
  7036.                S
  7037.                S.................. 5.2     T
  7038.                SearchEnvironment. 10.8     Tail............... 8.3
  7039.                SelectColors....... 1.4     Time2SSM........... 5.9
  7040.                SetSwCh............ 2.8     Time2TimeStr...... 5.10
  7041.                slAppend........... 8.4     TimeType........... 5.2
  7042.                slCount............ 8.4     Today............. 5.10
  7043.                slFree............. 8.5     Today2ANSI........ 5.11
  7044.                slGetCurrent....... 8.6     Today2Greg........ 5.11
  7045.                slGetFirst......... 8.6     TodayStr.......... 5.12
  7046.                slGetLast.......... 8.7
  7047.                slGetNext.......... 8.7     U
  7048.                slList............. 8.3     UniqueFileName.... 10.9
  7049.                slListInit......... 8.9
  7050.                slNode............. 8.2     V
  7051.                slNodePtr.......... 8.2     ValueType.......... 2.2
  7052.                slPop............. 8.10     VtInt.............. 2.2
  7053.                slPush............ 8.11     VtReal............. 2.2
  7054.                slPut............. 8.12     VtStr.............. 2.2
  7055.                slSpaceUsed....... 8.14
  7056.                SSM2Time........... 5.8     W
  7057.                SSM2TimeStr........ 5.9     WhoAmI........... 10.10
  7058.                StarString........ 10.9
  7059.                StartingAttr...... 10.1     Y
  7060.                                            Year............... 5.2
  7061.  
  7062.  
  7063.  
  7064.  
  7065.  
  7066.  
  7067.  
  7068.  
  7069.  
  7070.  
  7071.  
  7072.  
  7073.  
  7074.  
  7075.  
  7076.  
  7077.  
  7078.  
  7079.  
  7080.  
  7081.  
  7082.  
  7083.  
  7084.  
  7085.  
  7086.                                     index-xiv
  7087.  
  7088.