home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / UTILS / IPRO162 / INSTPRO.MAN < prev    next >
Text File  |  1991-12-26  |  78KB  |  1,890 lines
  1.      
  2.      
  3.      
  4.      
  5.       
  6.      
  7.      
  8.      
  9.      
  10.      
  11.      
  12.      
  13.                        The Install-Pro Reference Manual
  14.      
  15.                         Version 1.62 December 25, 1991
  16.      
  17.                      Copyright 1991 DB/Soft Publishing Co.
  18.      
  19.                               All Rights Reserved
  20.      
  21.      
  22.      
  23.      
  24.      
  25.      
  26.      
  27.      
  28.      
  29.      
  30.      
  31.      
  32.                             DB/Soft Publishing Co.
  33.                             3200 Truxel Rd.
  34.                             #199 Sacramento, CA 95833
  35.      
  36.                             Sole Proprietor: Jeff Dunlop
  37.                             Voice: (916) 927-6951
  38.                             Data: (916) 927-2349
  39.                             Fidonet Address: 1:203/16
  40.      
  41.      
  42.      
  43.      
  44.      
  45.      
  46.      
  47.      
  48.      
  49.      
  50.      
  51.      
  52.      
  53.      
  54.      
  55.      
  56.      
  57.      
  58.      
  59.      
  60.             
  61.      
  62.      
  63.      
  64.       
  65.                                Table of Contents
  66.      
  67.      
  68.      
  69.       Introduction ..................................... 1
  70.       Program Requirements (Programmer) ................ 3
  71.       Program Requirements (User) ...................... 3
  72.       Distribution Files ............................... 3
  73.       Registration ..................................... 3
  74.       Shareware License ................................ 4
  75.       Shareware Warranty ............................... 4
  76.       Registered License ............................... 4
  77.       Registered Warranty .............................. 4
  78.       Registered Support ............................... 5
  79.       Frankness Clause ................................. 5
  80.       Disclaimer ....................................... 6
  81.       About Config.sys and Autoexec.bat ................ 6
  82.       Contacting the Author ............................ 6
  83.       Upgrade Policy ................................... 7
  84.       Script Syntax .................................... 7
  85.       Script Tokens .................................... 10
  86.           BANNER ....................................... 10
  87.           HELLO ........................................ 10
  88.           HELLOBREAK ................................... 11
  89.           USER ......................................... 11
  90.           SUBDIR ....................................... 14
  91.           FILE ......................................... 15
  92.                   Splitting Files ...................... 17
  93.           SPACE ........................................ 18
  94.           UNZIP ........................................ 19
  95.           RUN .......................................... 20
  96.           GOODBYE ...................................... 23
  97.           GOODBYEBREAK ................................. 23
  98.           FIRSTDISK .................................... 23
  99.           DISK ......................................... 24
  100.           END .......................................... 24
  101.           CHAIN ........................................ 25
  102.           AUTHORIZATION ................................ 25
  103.       Script Debugging ................................. 25
  104.       Error Messages ................................... 26
  105.       Critical Errors .................................. 29
  106.       Registration Keys ................................ 30
  107.      
  108.      
  109.      
  110.      
  111.      
  112.      
  113.      
  114.      
  115.      
  116.      
  117.      
  118.      
  119.             
  120.      
  121.      
  122.      
  123.       
  124.      ───────────────────────────────────────────────────────────────────────────
  125.                                     Introduction
  126.      ───────────────────────────────────────────────────────────────────────────
  127.      
  128.      
  129.      Once upon a time I wrote a program that was (and is) distributed
  130.      nationwide. This program, like most, needs to be installed on the
  131.      customers' hard drives.  I investigated every installation utility
  132.      that I could find, and came away convinced that none of them had been
  133.      done very well.  Under no circumstances could I justify $150, up to
  134.      $250, for any of them.
  135.      
  136.      I wrote Install-Pro.
  137.      
  138.      Install-Pro is a script driven professional installation program that
  139.      you as a programmer (or consultant) can use to install your
  140.      applications or information bases on your customers' computers. My
  141.      personal goal with this program was to never write an installation
  142.      again (heaven forbid a batch file!) which meant that the entire
  143.      installation procedure HAD to be configurable quickly and easily.  Any
  144.      application can be ready to install to multiple directories from
  145.      multiple disks in a matter of minutes.  A brief list of features
  146.      includes:
  147.      
  148.              -     Professional look and feel for a better first
  149.                    impression.
  150.      
  151.              -     You customize multiple welcome screens and good-bye
  152.                    screens to your own needs. (Welcome screen -  registered
  153.                    version only)
  154.      
  155.              -     Up to 999 installation disks.
  156.      
  157.              -     Unlimited installation files.
  158.      
  159.              -     Files may be split into up to 9 pieces for huge files
  160.                    spanning multiple disks.
  161.      
  162.              -     Files in the .zip format may be extracted.  All
  163.                    directories stored in a .zip file are automatically
  164.                    created.
  165.      
  166.              -     You define the directory prompts that the user sees.
  167.      
  168.              -     You define the default destination directories that the
  169.                    user sees.
  170.      
  171.              -     You optionally define the installation disk names (such
  172.                    as "Utilities Disk" or "Install Disk")
  173.      
  174.      
  175.      
  176.                           Install-Pro Reference Manual
  177.                                       - 1 -
  178.             
  179.      
  180.      
  181.      
  182.       
  183.              -     You optionally specify the disk space requirements
  184.                    associated with all portions of the installation,
  185.                    including optional portions.  (The user is given the
  186.                    option to try to continue with installation if short on
  187.                    disk space.)
  188.      
  189.              -     Up to 8 user-defined destination directories.
  190.      
  191.              -     Unlimited programmer-defined directories child to
  192.                    user-defined directories.
  193.      
  194.              -     Destination directories may either be optionally locked
  195.                    or the user may be allowed to change it.
  196.      
  197.              -     "Run" commands allow your installation to include custom
  198.                    auxiliary programs or batch files to complete special
  199.                    tasks. The installation diskette directory(s), any of
  200.                    the user-defined directories, and any other arguments
  201.                    you choose can be specified anywhere on the command
  202.                    line.
  203.      
  204.              -     Portions of an installation may be specified as
  205.                    optional, prompting the user whether the optional
  206.                    portion should be installed.
  207.      
  208.              -     Multi-Module installations handled seamlessly.
  209.      
  210.              -     Files may be automatically overwritten, prompted before
  211.                    overwriting a newer file, or prompted before overwriting
  212.                    any file.
  213.      
  214.              -     Supports VGA/EGA 50/43 line text modes if detected.
  215.      
  216.              -     Robust error handling, including a custom critical error
  217.                    handler that won't scare the dickens out of your users,
  218.                    and including descriptive fatal error messages (no "error
  219.                    14 at xxxx:yyyy" found in this program!)
  220.      
  221.      
  222.      
  223.      
  224.      
  225.      
  226.      
  227.      
  228.      
  229.      
  230.      
  231.      
  232.      
  233.      
  234.      
  235.                           Install-Pro Reference Manual
  236.                                       - 2 -
  237.             
  238.      
  239.      
  240.      
  241.       
  242.      ───────────────────────────────────────────────────────────────────────────
  243.                        Program Requirements (Programmer)
  244.      ───────────────────────────────────────────────────────────────────────────
  245.      
  246.            1. Text editor for creating and modifying the script file(s).
  247.               This text editor must not insert tab characters into your
  248.               screen definition lines.
  249.            2. MSDos 3.0 or higher.
  250.            3. IBM PC bios compatible MS-Dos computer with at least 200k
  251.               free ram.
  252.            4. Standard CGA or Hercules compatible video subsystem.
  253.      
  254.      ───────────────────────────────────────────────────────────────────────────
  255.                           Program Requirements (User)
  256.      ───────────────────────────────────────────────────────────────────────────
  257.      
  258.            1. MS-DOS 3.0 or higher.
  259.            2. IBM PC bios-compatible MS-DOS computer with 200k free ram
  260.               (more ram needed for RUN commands)
  261.            3. Standard CGA or Hercules compatible video subsystem.
  262.      
  263.      ───────────────────────────────────────────────────────────────────────────
  264.                               Distribution Files
  265.      ───────────────────────────────────────────────────────────────────────────
  266.      
  267.      Install-Pro comes distributed with the following files:
  268.      
  269.              instpro.exe - the executable
  270.              instpro.man - this reference manual
  271.              install.001 - sample script file #1
  272.              order.doc   - order form
  273.              read.me     - quick hello
  274.              example.001 - script examples to get you started
  275.              split.exe   - utility to chop files into pieces (eek!)
  276.              split.doc   - caveats and instructions for split
  277.      
  278.      If any of these files were missing, feel free to download the latest
  279.      version from the DB/Soft Online.  Also, when you distribute
  280.      Install-Pro with your applications, feel encouraged to rename it
  281.      'install.exe.'  I refrained from naming the executable that way to
  282.      avoid accidentally having it write over one of the other install.exe's
  283.      you may have lying around.
  284.      
  285.      ───────────────────────────────────────────────────────────────────────────
  286.                                  Registration
  287.      ───────────────────────────────────────────────────────────────────────────
  288.      
  289.      Upon receipt of the registration price of $32.50 (U.S. funds only) you
  290.      will be sent a disk with the most current version that will enable you
  291.      to display your application's name instead of my shareware notice. Use
  292.      
  293.      
  294.                           Install-Pro Reference Manual
  295.                                       - 3 -
  296.             
  297.      
  298.      
  299.      
  300.       
  301.      the file "order.doc" to order. Sorry, MC/Visa not accepted.
  302.      
  303.      ───────────────────────────────────────────────────────────────────────────
  304.                                Shareware License
  305.      ───────────────────────────────────────────────────────────────────────────
  306.      
  307.      You are free to distribute shareware copies of Install-Pro provided
  308.      that none of the included files are modified or removed, and provided
  309.      that no additional files are included in the archive.  Modifying the
  310.      archive format (from .zip to some other format perhaps more
  311.      convenient) is permitted.
  312.      
  313.      
  314.      ───────────────────────────────────────────────────────────────────────────
  315.                               Shareware Warranty
  316.      ───────────────────────────────────────────────────────────────────────────
  317.      
  318.      The shareware version of Install-Pro is guaranteed to take up disk
  319.      space. The author of this product is more than happy to hear about any
  320.      bugs or unexpected behavior through non-voice channels (netmail, US
  321.      Postal Service, or logging on to the DB/Soft BBS), but will not
  322.      guarantee that immediate bug fixes will be forthcoming.
  323.      
  324.      ───────────────────────────────────────────────────────────────────────────
  325.                               Registered License
  326.      ───────────────────────────────────────────────────────────────────────────
  327.      
  328.      You are free to make unlimited backup copies of this program for
  329.      archival purposes.  You may not distribute copies of this program
  330.      except under the following provisions:  You may at your choosing give
  331.      away or sell your program with its accompanying key to ONE party,
  332.      provided you destroy all copies of the software in your possession
  333.      after the time of the transaction.  The copies of the program that are
  334.      used to install your applications MUST NOT be distributed with the key
  335.      that enables script modifications.
  336.      
  337.      Pursuant to United States copyright laws and international copyright
  338.      aggreements, Install-Pro must be treated as if it were a book.  Just
  339.      as two people cannot read a book in front of separate computers, two
  340.      people must not simultaneously use the same registered copy of
  341.      Install-Pro.  The sole purpose of archival copies of Install-Pro is
  342.      to be for protection against hardware or diskette failure.
  343.      
  344.      ───────────────────────────────────────────────────────────────────────────
  345.                               Registered Warranty
  346.      ───────────────────────────────────────────────────────────────────────────
  347.      
  348.      The registered version (original copy) is warranted to meet in all key
  349.      aspects its defined behavior as listed in the documentation.  Key
  350.      aspects are those features without which the program will fail in some
  351.      
  352.      
  353.                           Install-Pro Reference Manual
  354.                                       - 4 -
  355.             
  356.      
  357.      
  358.      
  359.       
  360.      gross manner to transfer an application.  Minor specifications (such
  361.      as prompt lengths, etc.) are subject to change without notice.  The
  362.      final arbiter as to the interpretation of the documentation shall be
  363.      the author of the program. The sole remedy available to the purchaser
  364.      of Install-Pro shall be bug fixes or a refund, as determined by the
  365.      author.  Work-arounds (eg syntax modifications) for the purposes of
  366.      warranty consideration will be considered acceptable if they make
  367.      possible the same task that any bug renders impossible.  If verified
  368.      bugs are not corrected within 30 days of notification, and if the
  369.      purchaser is working in good faith to keep in contact with the author,
  370.      the purchaser at his option is entitled to a refund. Verified bugs are
  371.      those which the author is able to duplicate on machines that fall
  372.      within the equipment requirements list.
  373.      
  374.      Upgraded versions of Install-Pro will be handled in a slightly
  375.      different fashion.  Unless demonstrated otherwise, it is assumed by
  376.      the author that free upgrades obtained by the purchaser are so
  377.      obtained as a matter of the purchaser's convenience, and it is thus
  378.      assumed that the original, purchased copy of Install-Pro is not
  379.      defective.  It is further assumed that if a bug is discovered in a
  380.      free upgrade, the purchaser is still able to use his older version of
  381.      Install-Pro.  Therefore, unresolved bugs found in a free upgrade of
  382.      Install-Pro are not subject to a refund of monies paid should such
  383.      bugs remain unresolved after 30 days.  Any bugs found should still be
  384.      reported to the author, as he will give all bug reports due attention
  385.      in his attempts to resolve them.
  386.      
  387.      There is one exception to this previous provision.  If the author
  388.      represents an upgrade as a fix to a bug reported by the purchaser,
  389.      then the full original warranty shall be extended to cover the
  390.      upgrade.
  391.      
  392.      ───────────────────────────────────────────────────────────────────────────
  393.                               Registered Support
  394.      ───────────────────────────────────────────────────────────────────────────
  395.      
  396.      The registered version entitles the purchaser to unlimited support via
  397.      netmail, the DB/Soft BBS or via US Mail.  I am unable, however, to
  398.      provide telephone support.
  399.      
  400.      ───────────────────────────────────────────────────────────────────────────
  401.                                Frankness Clause
  402.      ───────────────────────────────────────────────────────────────────────────
  403.      
  404.      As you well know, it's darned difficult to get a publisher to stand
  405.      behind his product.  He usually guarantees the diskette (what a joke)
  406.      and hangs you out to dry.  If there is an error in the program, I will
  407.      do anything possible to correct it in a timely fashion.  I am also
  408.      very interested in any ambiguities or errors in this documentation.
  409.      Whatever problems you do find, I would appreciate a note.
  410.      
  411.      
  412.                           Install-Pro Reference Manual
  413.                                       - 5 -
  414.             
  415.      
  416.      
  417.      
  418.       
  419.      
  420.      ───────────────────────────────────────────────────────────────────────────
  421.                                   Disclaimer
  422.      ───────────────────────────────────────────────────────────────────────────
  423.      
  424.      While every effort has been made by the author to ensure the fitness
  425.      for use and integrity of Install-Pro, the author cannot and will not
  426.      accept responsibility for any damage, physical or otherwise, to any
  427.      equipment owned by the purchaser.  The author habitually recommends
  428.      that all customers back up their data regularly and frequently;  that
  429.      recommendation applies here as well.  The maximum remedy available to
  430.      the purchaser in the event of any type of dispute is the purchase cost
  431.      of the software.
  432.      
  433.      ───────────────────────────────────────────────────────────────────────────
  434.                        About Config.sys and Autoexec.bat
  435.      ───────────────────────────────────────────────────────────────────────────
  436.      
  437.      This is a controversial subject if I've ever seen one.  I have seen
  438.      opinions ranging from "My users are too stupid to know about these
  439.      things" to "No programmer had better touch it!"  I choose to leave it
  440.      up to you the programmer.  If you want to write a routine modifying
  441.      system files, have at it, and run it with the RUN command, described
  442.      later.
  443.      
  444.      ───────────────────────────────────────────────────────────────────────────
  445.                              Contacting the Author
  446.      ───────────────────────────────────────────────────────────────────────────
  447.      
  448.      If you have access to Fidonet netmail, contacting me at 1:203/16 will
  449.      get the fastest response.  The DB/Soft Online is available 24 hours a
  450.      day if netmail is not available to you - just leave a comment to the
  451.      sysop when logging off.  If you leave a netmail or snail-mail return
  452.      address, you won't have to call back for a response, I'll be happy to
  453.      drop the price of postage or a crash netmail message.  Failing that,
  454.      mailing me at 3200 Truxel Rd. #199 Sacramento CA 95833 will get a
  455.      prompt response, but will take about a week for the two-ended
  456.      delivery.  My voice number has been included on page one, but should
  457.      only be used by those interested in ordering the software.
  458.      
  459.      The following steps will greatly aid technical support and speed of
  460.      problem resolution:
  461.      
  462.           1. If a specific command is not working as expected, does your
  463.              usage of the command comply with its description in the
  464.              appropriate section of the documentation?
  465.      
  466.           2. To avoid my needing to resort to guesswork, send the exact
  467.              script that is not working for you with your question.
  468.      
  469.      
  470.      
  471.                           Install-Pro Reference Manual
  472.                                       - 6 -
  473.             
  474.      
  475.      
  476.      
  477.       
  478.           3. If logging onto the DB/Soft Online for technical support,
  479.              prepare your message in advance.  The Message Menu of the BBS
  480.              has an Upload feature that will allow you to upload your
  481.              message with most any protocol.  This will greatly reduce
  482.              connect time and increase accuracy.  Be sure to include your
  483.              entire script as part of the message, or as its own message.
  484.      
  485.           4. Be sure to indicate exactly which error messages, if any, are
  486.              accompanying unexpected behavior.
  487.      
  488.      ───────────────────────────────────────────────────────────────────────────
  489.                                 Upgrade Policy
  490.      ───────────────────────────────────────────────────────────────────────────
  491.      
  492.      "Once bought, always bought."  Purchasers of Install-Pro will be
  493.      entitled to free upgrades indefinitely.  I will notify you of the
  494.      first significant upgrade of Install-Pro after registration, and I
  495.      keep the current registered version of Install-Pro available for
  496.      download in the 'Registered User' file section of the DB/Soft Online.
  497.      
  498.      ───────────────────────────────────────────────────────────────────────────
  499.                                  Script Syntax
  500.      ───────────────────────────────────────────────────────────────────────────
  501.      
  502.      When install.exe is executed, the first file it looks for is
  503.      install.001 in the same directory as Install-Pro.  If install.001 is
  504.      not available, the program terminates. If install.001 is processed
  505.      successfully, and an additional installation disk is specified, then
  506.      the user will be prompted for the correct disk to insert to continue.
  507.      After the disk has been swapped, Install-Pro looks for install.002.
  508.      This continues until an END command is encountered in the current
  509.      script.
  510.      
  511.      Before beginning immediately with the syntax proper, an explanation of
  512.      how Install-Pro functions is in order:
  513.      
  514.      The concept of Install-Pro centers around what I call a label name. A
  515.      label name is simply an arbitrary name that you give to the
  516.      characteristics of a single installation directory. These
  517.      characteristics include the prompt that user is going to see when
  518.      asked where to put this directory, the default that the user is going
  519.      to see when prompted, the subdirectories that are going to be created
  520.      child to this directory, and the files that are going to be
  521.      transferred to this directory or one of its children. Since you the
  522.      programmer don't know what a user is going to name his installation
  523.      directory, a label name provides you with an alias to refer to it by.
  524.      Before you can refer to a label name, it must first exist.
  525.      
  526.      The USER token, discussed below, is the token that creates space for a
  527.      label name and all of its associated characteristics.  FILE, SUBDIR,
  528.      
  529.      
  530.                           Install-Pro Reference Manual
  531.                                       - 7 -
  532.             
  533.      
  534.      
  535.      
  536.       
  537.      UNZIP and RUN tokens that refer to a label must come after the USER
  538.      token that defines it.  It's that simple.
  539.      
  540.      
  541.                                INSTALL.001
  542.                                -----------
  543.      
  544.      The following is a brief overview of the syntax needed for
  545.      install.001:
  546.      
  547.      BANNER "Banner goes here"
  548.      HELLO "Welcome text goes here"
  549.              (additional HELLO lines)
  550.      HELLOBREAK
  551.      HELLO "More hello lines if you wish"
  552.      
  553.      [OPTION] USER <label name> "User prompt" [Default Destination] [NOMOD]
  554.              (additional USER lines)
  555.      
  556.      SUBDIR <label name> <child subdirectory>
  557.              (additional SUBDIR lines)
  558.      
  559.      FILE <label name> <filename> [UPGRADE or VERIFY]
  560.              (additional FILE lines)
  561.      
  562.      UNZIP <filename> [UPGRADE or VERIFY]
  563.              (additional UNZIP commands)
  564.      
  565.      RUN "command line in quotes"
  566.              (additional RUN commands)
  567.      
  568.      ; goodbye text if last floppy of installation
  569.      
  570.      GOODBYE "So-long text goes here"
  571.              (additional GOODBYE lines)
  572.      GOODBYEBREAK
  573.      GOODBYE "More good-bye lines if desired"
  574.      
  575.      SPACE <labelname> <nnnnn>
  576.      
  577.      DISK [diskname] -or- END -or- CHAIN
  578.      AUTHORIZATION <nnnnn>
  579.      
  580.      
  581.                                  INSTALL.002+
  582.                                  ------------
  583.      
  584.      
  585.      The syntax for install.002 through install.999 is slightly different,
  586.      as follows:
  587.      
  588.      
  589.                           Install-Pro Reference Manual
  590.                                       - 8 -
  591.             
  592.      
  593.      
  594.      
  595.       
  596.      
  597.      FILE <label name> <filename> [UPGRADE or VERIFY]
  598.              (additional FILE lines)
  599.      
  600.      UNZIP <filename> [UPGRADE or VERIFY]
  601.              (additional UNZIP commands)
  602.      
  603.      RUN "command line in quotes"
  604.              (additional RUN commands)
  605.      GOODBYE "So-long text goes here"
  606.              (additional GOODBYE lines)
  607.      DISK [diskname] -or- END -or- CHAIN
  608.      
  609.      
  610.      Please note that HELLO, BANNER and USER tokens are not allowed, as
  611.      they must get processed from the first disk.
  612.      
  613.      
  614.      
  615.      In both of these examples, the order that the tokens appear is the
  616.      most logical, but is not strictly required.  The following is a list
  617.      of token order requirements:
  618.      
  619.            1.    HELLO and BANNER tokens must appear before the first DISK
  620.                  token (if any) in install.001.
  621.      
  622.            2.    RUN commands are executed BEFORE disk swaps, but after all
  623.                  other processing.  This means that the files on the
  624.                  current installation diskette are guaranteed to exist for
  625.                  the current commands.  Furthermore, this guarantees that
  626.                  directories created with SUBDIR, files transferred with
  627.                  FILE, files unzipped with UNZIP, and directories created
  628.                  by the user with USER tokens will exist at the time of any
  629.                  RUN. Essentially, the final state of a particular
  630.                  installation disk exists for the RUN.
  631.      
  632.            3.    AUTHORIZATION nnnnn must occupy the last line of install.001
  633.                  (Registered versions only.)
  634.      
  635.            4.    DISK must occupy the line directly before AUTHORIZATION on
  636.                  install.001, or the last line on all other installation
  637.                  disks. In effect, DISK flushes the accumulated tokens into
  638.                  actual processing, and is followed by a disk swap.
  639.      
  640.            5.    FILE, SUBDIR, RUN and UNZIP lines MUST come AFTER the USER
  641.                  line that defines any label names used for these commands.
  642.      
  643.            6.    Lines with a preceding semicolon, or empty lines are
  644.                  ignored by Install-Pro.  An empty line is a line with all
  645.                  whitespace, with no tokens detected by the parser.
  646.      
  647.      
  648.                           Install-Pro Reference Manual
  649.                                       - 9 -
  650.             
  651.      
  652.      
  653.      
  654.       
  655.      
  656.            7.    FILE tokens transfer files on the CURRENT installation
  657.                  diskette when END or DISK [diskname] is encountered.  The
  658.                  filename specified with FILE must be on the same
  659.                  installation diskette as the FILE token.
  660.      
  661.            8.    The SPACE command must come after at least one USER
  662.                  command.
  663.      
  664.      ───────────────────────────────────────────────────────────────────────────
  665.                                  Script Tokens
  666.      ───────────────────────────────────────────────────────────────────────────
  667.      
  668.                                     BANNER
  669.                                     ------
  670.      
  671.      Syntax:  BANNER "Any text enclosed in quotes"
  672.      
  673.      The BANNER token identifies the line of text to be shown to the user
  674.      as the program name on the opening screen.  Up to 71 characters are
  675.      allowed, and a box surrounding the text auto-sizes for a neat
  676.      appearance.  If the particular text used creates unbalanced sides,
  677.      insert an extra space on the errant side to even things out.
  678.      
  679.      If quotes are omitted, only the first word after BANNER will be
  680.      detected. If no text is detected after BANNER, Install-Pro will abort
  681.      with an error message.
  682.      
  683.      BANNER overwrites any previous BANNER definitions.
  684.      
  685.      BANNER is recognized only in install.001, on any line previous to DISK
  686.      [diskname] (or AUTHORIZATION on single-disk installations.)  If BANNER
  687.      appears in install.002+, it will be ignored.
  688.      
  689.      If DISK or End-of-file are reached in install.001 and no BANNER has
  690.      been found, a very small message-less box will be formed - harmless
  691.      but unattractive.
  692.      
  693.      Shareware note:  Although the BANNER token will be recognized and
  694.      parsed, it is ignored in unregistered versions of Install-Pro. It
  695.      makes no difference if it is included or not.
  696.      
  697.      
  698.                                      HELLO
  699.                                      -----
  700.      
  701.      Syntax:  HELLO  "Any text enclosed in quotes"
  702.      
  703.      The HELLO token identifies a line of text to be shown to the user on
  704.      the welcome screen.  Each line may have a maximum length of 71
  705.      
  706.      
  707.                           Install-Pro Reference Manual
  708.                                       - 10 -
  709.             
  710.      
  711.      
  712.      
  713.       
  714.      characters.  Characters in excess of 71 are ignored (truncated.)  All
  715.      of the HELLO text lines are displayed in the order detected in a
  716.      single window, which automatically sizes itself to the length and
  717.      height of the combined HELLO display.  If you want empty lines
  718.      included, indicate this with a set of empty quotes ("").
  719.      
  720.      If quotes are omitted, only the first word after HELLO will be
  721.      detected.
  722.      
  723.      If no text is detected after HELLO ("" DOES qualify as text) then
  724.      Install-Pro will abort with a message.
  725.      
  726.      Up to 13 HELLO lines will fit on a single screen.  If more than 13
  727.      HELLO lines are defined without any intervening HELLOBREAK commands
  728.      (described below), the subsequent lines will be displayed on the next
  729.      screen.  Any number of HELLO screens (each autosizing, with a capacity
  730.      of up to 13 lines) can be defined.
  731.      
  732.      HELLO is recognized in install.001, on any line previous to DISK 2 (or
  733.      AUTHORIZATION on single-disk installations.)  If HELLO appears in
  734.      install.002+, it will be ignored.
  735.      
  736.      If DISK or End-of-file are reached in install.001 and no HELLO has
  737.      been found, a very small message-less box will be formed - harmless
  738.      but unattractive.
  739.      
  740.      Shareware note:  Although HELLO tokens will be recognized and parsed,
  741.      they are not displayed in unregistered versions of Install-Pro.  It
  742.      makes no difference if it is included or not.
  743.      
  744.      
  745.                                   HELLOBREAK
  746.                                   ----------
  747.      
  748.                          --- New with version 1.60 ---
  749.      
  750.      Syntax:  HELLOBREAK
  751.      
  752.      This command signifies that the following HELLO command is to be
  753.      displayed on a new screen.  Use this if you have special formatting
  754.      needs that require fewer than 13 lines to a screen.
  755.      
  756.                                      USER
  757.                                      ----
  758.      
  759.      Syntax:  [OPTION] USER <label> "prompt" [default directory] [NOMOD]
  760.      
  761.      This token is used to assign a prompt and a default destination to a
  762.      label that is specified by the programmer.  When the user inputs his
  763.      destination directory it will be associated with this label name. This
  764.      
  765.      
  766.                           Install-Pro Reference Manual
  767.                                       - 11 -
  768.             
  769.      
  770.      
  771.      
  772.       
  773.      token also creates the space needed for FILE, RUN and SUBDIR tokens to
  774.      function.
  775.      
  776.      [OPTION]:
  777.      
  778.              This modifies the behavior of the installation as follows:
  779.      
  780.                                --- New behavior with 1.61 ---
  781.      
  782.                      Before he is shown the destination directory Entry
  783.                      Screen, all OPTION USER lines will be resolved by
  784.                      displaying a form with radio buttons that allow the
  785.                      user to toggle on or off any or all of the optional
  786.                      label that have been defined.  Non-OPTIONal labels are
  787.                      not displayed on this form.  After the user accepts
  788.                      this form, any OPTIONal labels that he had selected
  789.                      are displayed on the destination directory entry
  790.                      screen along with all non-OPTIONal labels.
  791.      
  792.                      For each OPTIONal label, if the user toggles its
  793.                      button on, then all activities associated with the
  794.                      labelname allocated in this USER command will occur
  795.                      normally.
  796.      
  797.                      Any buttons toggled off will cause all of the
  798.                      activities (FILE, SUBDIR or UNZIP) associated with
  799.                      this labelname to be cancelled.
  800.      
  801.                                 --- New with version 1.58 ---
  802.      
  803.                      Any RUN commands that access an unaccepted OPTIONal
  804.                      label will be ignored.  This allows RUN commands to be
  805.                      conditional on specific portions of an installation
  806.                      being installed.
  807.      
  808.              Please note that using the OPTION modifier on a USER command
  809.              does not change the syntax of any other command in any way.
  810.      
  811.              If all aspects of an installation are made OPTIONal (not TOO
  812.              farfetched) and the user declines all of them, then nothing
  813.              will occur (although some messages, including your GOODBYE
  814.              screen, will still be displayed.)
  815.      
  816.      label:
  817.      
  818.              The label name can be any single word of up to 40 characters,
  819.              although less than ten characters is usually more than enough.
  820.              A typical label name might be prog_files, data_files, etc.
  821.      
  822.      prompt:
  823.      
  824.      
  825.                           Install-Pro Reference Manual
  826.                                       - 12 -
  827.             
  828.      
  829.      
  830.      
  831.       
  832.      
  833.              The user prompt can be up to 23 characters.  Examples of
  834.              typical prompts are "Help Files", or "Data Files".  The quotes
  835.              are required if more than one word is in the prompt.
  836.      
  837.      default directory:
  838.      
  839.              A default directory is optional.  If specified, the directory
  840.              must be in the form of a fully qualified DOS path, complete
  841.              with drive and semicolon.  Keep in mind your default will not
  842.              be checked for validity until it is accepted by the user.
  843.      
  844.                              --- New with 1.60 ---
  845.      
  846.      [NOMOD]:
  847.      
  848.              This optional modifier is used to disable the directory field
  849.              for this label in the destination entry screen.  This option
  850.              should be used if the application being installed relies on
  851.              specific directories existing.  To be able to use NOMOD,
  852.              [default directory] must be an explicitly defined valid path.
  853.              Note that the destination drive is still changeable.
  854.      
  855.      Up to 8 USER lines may be specified.  Any additional USER lines will
  856.      cause a less attractive entry screen to be displayed, since some of
  857.      the windows will start running into each other.
  858.      
  859.      The Destination Directory Entry screen that the list of USER prompts
  860.      generates autosizes around the prompts for the neatest appearance.
  861.      
  862.      If no labelname or user prompt are detected, Install-Pro will abort
  863.      with an error message.  Only the default destination is optional.
  864.      
  865.      USER lines may occur anywhere in install.001 prior to DISK or
  866.      End-of-file (in the absence of DISK.)
  867.      
  868.      
  869.      Example 1:
  870.      
  871.      USER prog_files "Program Files" C:\MYPROG
  872.      
  873.      This line would assign a "Program Files:" prompt and C:\MYPROG default
  874.      directory to the prog_files label.  The user would see a line on his
  875.      entry form similar to the following:
  876.      
  877.      Program Files                   C:\MYPROG
  878.      
  879.      
  880.      Example 2:
  881.      
  882.      
  883.      
  884.                           Install-Pro Reference Manual
  885.                                       - 13 -
  886.             
  887.      
  888.      
  889.      
  890.       
  891.      USER prog_files "Program Files" C:\MYPROG
  892.      OPTION USER sample_files "Sample Files" C:\MYPROG\SAMPLE
  893.      
  894.      This partial script would first ask the user if he wanted to install
  895.      Sample Files (the question includes the prompt as part of the text.)
  896.      If he responds yes, he would be presented with an entry form similar
  897.      to the following:
  898.      
  899.      Program Files                    C:\MYPROG
  900.      Sample Files                     C:\MYPROG\SAMPLE
  901.      
  902.      If he had responded no, then he would have seen the same entry screen
  903.      as in example #1.
  904.      
  905.      Example 3:
  906.      
  907.      USER prog_files "Program Files" C:\MYPROG NOMOD
  908.      
  909.      The user would be allowed to change the destination drive, but not the
  910.      path.  All files associated with prog_files would be transferred to
  911.      \MYPROG.
  912.      
  913.      
  914.                                     SUBDIR
  915.                                     ------
  916.      
  917.      Syntax: SUBDIR <label_name> <dirname>
  918.      
  919.      This optional token defines any directories that the programmer wishes
  920.      created as children to the user-specified directories. The specified
  921.      label name must match one of the label names defined under the USER
  922.      token, described above.  Any number of SUBDIR lines may be used in the
  923.      script.
  924.      
  925.      label_name:
  926.      
  927.              The label name specified here MUST have been previously
  928.              defined with a USER token.
  929.      
  930.      dirname:
  931.      
  932.              The directory structure is not required to start with a
  933.              leading backslash, but it may be less confusing if it does.
  934.              Either way, the directory will be created as a child as
  935.              expected.
  936.      
  937.      SUBDIR lines may exist anywhere in any install.??? file, but must
  938.      precede the first use of its created directory or the program will
  939.      error out with a Subdirectory Error.  SUBDIR must also come after the
  940.      USER line that defines the label name to which SUBDIR refers.
  941.      
  942.      
  943.                           Install-Pro Reference Manual
  944.                                       - 14 -
  945.             
  946.      
  947.      
  948.      
  949.       
  950.      
  951.      For example, assume the following partial script:
  952.      
  953.      USER label_1 "Data Files" C:\MYAPP\DATA
  954.      SUBDIR label_1 \MOREDATA
  955.      
  956.      If the user accepted the default, the C:\MYAPP\DATA directory would be
  957.      created.  Also, as a result of the SUBDIR line, the
  958.      C:\MYAPP\DATA\MOREDATA directory would be created.  Furthermore, if
  959.      the SUBDIR line had instead read:
  960.      
  961.      SUBDIR label_1 \MOREDATA\DATADATA
  962.      
  963.      all directories parent to DATADATA will created as well as DATADATA.
  964.      That is to say, you don't have to specify explicitly all directories
  965.      that you want created, just the entire chain that you want to be
  966.      ensured exists.  In a more extreme example to illustrate this point,
  967.      assume:
  968.      
  969.      USER label_1 "Data Files" C:\DATA
  970.      SUBDIR label_1 MORE\DATA\DATA\DATA
  971.      
  972.      All five of the specified directories would be created.
  973.      
  974.      CAUTION:  The DOS limit for subdirectory length is 65 characters,
  975.      including drive and colon.  Keep in mind the maximum user-entered
  976.      directory is up to 40 characters, leaving you up to 24 characters with
  977.      any margin of safety.  If the total exceeds 65 characters, DOS returns
  978.      a directory creation error.
  979.      
  980.                                      FILE
  981.                                      ----
  982.      
  983.      Syntax: FILE <label_name> <filename> [UPGRADE or VERIFY]
  984.      
  985.      This token defines a file that is to be transferred from the current
  986.      installation diskette.  The word following the FILE token must be a
  987.      label defined on one of the USER lines.
  988.      
  989.      label_name:
  990.      
  991.              The label name specified here MUST already have been created
  992.              with a USER token.
  993.      
  994.      filename:
  995.      
  996.              The filespec can take one of two forms.  First, it can be a
  997.              regular dos filename, in which case it would be transferred to
  998.              the directory associated with the specified label.  Or second,
  999.              it can include an optional directory chain child to the
  1000.      
  1001.      
  1002.                           Install-Pro Reference Manual
  1003.                                       - 15 -
  1004.             
  1005.      
  1006.      
  1007.      
  1008.       
  1009.              directory associated with the specified label, in which case
  1010.              it would be transferred to that child directory.  For that
  1011.              child directory to exist, it would be necessary to previously
  1012.              create it with a SUBDIR line, described previously. Any number
  1013.              of FILE lines can be specified.  Two examples follow:
  1014.      
  1015.                              --- New with 1.60 ---
  1016.      
  1017.      UPGRADE:
  1018.      
  1019.              This modifier indicates that any files newer than the file
  1020.              being transferred are to be overwritten only with permission
  1021.              from the user.  This modifier is reliant on the user's machine
  1022.              having a functional clock, and that the files on the user's
  1023.              machine reflect actual dates.
  1024.      
  1025.      VERIFY:
  1026.      
  1027.              This modifier directs Install-Pro to verify all file
  1028.              overwrites.
  1029.      
  1030.      Assume the following partial script:
  1031.      
  1032.      USER label_1 "Data Files" C:\DATA
  1033.      FILE label_1 main.exe
  1034.      FILE label_1 main2.exe
  1035.      
  1036.      This script would transfer main.exe and main2.exe from the root
  1037.      directory of the current installation diskette to the directory that
  1038.      the user entered when prompted with "Data Files", perhaps the default
  1039.      directory presented to him, "C:\DATA".
  1040.      
  1041.      Now, consider this more advanced example:
  1042.      
  1043.      USER label_1 "Data Files" C:\DATA
  1044.      SUBDIR label_1 \HELP
  1045.      FILE label_1 main.exe
  1046.      
  1047.      FILE label_1 main2.exe
  1048.      FILE label_1 help\help.dat
  1049.      
  1050.      Assuming that the user accepts the default C:\DATA, this script would
  1051.      transfer main.exe and main2.exe from the root directory of the current
  1052.      installation diskette to C:\DATA, just as in the previous example.
  1053.      Also, as child to the user-entered directory would be created a help
  1054.      directory, to which would be transferred help.dat.
  1055.      
  1056.      The final structure if all defaults were accepted by the user would
  1057.      be:
  1058.      
  1059.      
  1060.      
  1061.                           Install-Pro Reference Manual
  1062.                                       - 16 -
  1063.             
  1064.      
  1065.      
  1066.      
  1067.       
  1068.      C:\DATA\MAIN.EXE
  1069.      C:\DATA\MAIN2.EXE
  1070.      C:\DATA\HELP\HELP.DAT
  1071.      
  1072.      If no label or filename are detected, Install-Pro will abort with an
  1073.      error message.
  1074.                                 Splitting Files
  1075.                                 ---------------
  1076.      
  1077.      If you have files that just cannot fit onto a distribution diskette,
  1078.      Install-Pro has the ability to handle split files.  First an example
  1079.      of how to accomplish this:
  1080.      
  1081.      FILE label_1 main.ex1e
  1082.      FILE label_1 main.ex2e
  1083.      
  1084.      These two file lines would create a file called main.exe in the
  1085.      label_1 directory, from TWO files main.ex1 and main.ex2.  What
  1086.      Install-Pro does is looks to see if an extra character has been added
  1087.      to a filename.  If there is an extra character:
  1088.      
  1089.              1. The source filename is assigned an extension of the first
  1090.                 three characters of the filename's extension.  This file
  1091.                 should exist on the current distribution floppy.
  1092.      
  1093.              2. The destination filename has the third character replaced with
  1094.                 the fourth, and the fourth character removed.
  1095.      
  1096.      Please note that:
  1097.      
  1098.              1. main.ex1e and main.ex2f would not cause an append to occur.
  1099.                 The filenames (with the exception of the third character of
  1100.                 a four-character extension) MUST match.  In this case,
  1101.                 main.exe would be created from main.ex1, but main.exf would
  1102.                 NOT be created.
  1103.      
  1104.              2. The files MUST have the same label name assigned to each of
  1105.                 them.  If main.ex1e and main.ex2e were assigned different
  1106.                 labels, \directory1\main.exe would be created, but
  1107.                 \directory2\main.exe would NOT.
  1108.      
  1109.              3. I strongly urge that multiple split files of the SAME name
  1110.                 NOT be installed.  For example, if you had two huge, but
  1111.                 different, files called main.dat, and wanted them both
  1112.                 split using main.da1t and main.da2t for each of them, but
  1113.                 assigning different labels to them, the user COULD still
  1114.                 assign both labels to the same directory, with
  1115.                 unpredictable results.  This is an extreme example that I
  1116.                 don't think you will run into.
  1117.      
  1118.      
  1119.      
  1120.                           Install-Pro Reference Manual
  1121.                                       - 17 -
  1122.             
  1123.      
  1124.      
  1125.      
  1126.       
  1127.      
  1128.      The append/create decision is resolved as follows:
  1129.      
  1130.              1. If third character of the extension is a '1' and the fourth
  1131.                 character exists, the file is CREATED.
  1132.      
  1133.              2. If the third character is greater than a '1' and the fourth
  1134.                 character exists, the file is APPENDED.  Note that trying
  1135.                 to append to to a file that does not yet exist will cause
  1136.                 DOS to return a 'file not found' error, and is used to
  1137.                 prevent accidentally append filename.ex2t on top of an
  1138.                 existing file.  The practical limit to the number of splits
  1139.                 is up to 9.
  1140.      
  1141.              3. If the third character is a number, but no fourth character
  1142.                 exists, no split-file decision occurs - the file will be
  1143.                 created.
  1144.      
  1145.              4. Note that main.0011, for example, is perfectly legal.  What
  1146.                 it specifies is that main.001 is to be created, and that
  1147.                 it's the first file of a split file.   Main.0021 would be
  1148.                 appended to main.0011.
  1149.      
  1150.      
  1151.      This type of file transfer can be especially touchy if the order of
  1152.      files transferred and then appended is incorrect.  If you split files,
  1153.      I strongly recommend that you debug your script carefully and compare
  1154.      the created file with the original (using the DOS program 'COMP') to be
  1155.      sure that they are identical to before releasing your application.
  1156.      
  1157.      There is an accompanying utility called split.exe which will split
  1158.      your large files for you if needed.  It comes with its own
  1159.      documentation.
  1160.      
  1161.                                      SPACE
  1162.                                      -----
  1163.                      --- New syntax with version 1.60 ---
  1164.      
  1165.      Syntax: SPACE <label_name> <nnnnn>
  1166.      
  1167.      The syntax of SPACE has changed.  Each SPACE command must reference a
  1168.      defined label (via the USER command.)  After the user chooses his
  1169.      destination drive and directories in the entry screen, all labels that
  1170.      access each drive are added together to determine if enough free disk
  1171.      space exists.
  1172.      
  1173.      This token allows you to warn the user if his destination directory
  1174.      has less space available than needed for the installation.  Since it
  1175.      is often possible that the installation is occurring over a current
  1176.      installation, the lack of space is treated as a warning.  If, during
  1177.      
  1178.      
  1179.                           Install-Pro Reference Manual
  1180.                                       - 18 -
  1181.             
  1182.      
  1183.      
  1184.      
  1185.       
  1186.      the transfer of any of the files, disk space runs out, the user will
  1187.      be told of this.
  1188.      
  1189.      A non-positive number or the existence of any non-numeric characters
  1190.      where the number is expected will cause a program abort with a
  1191.      descriptive error message.
  1192.      
  1193.      The disk check(s) occur directly after the user has finished with the
  1194.      destination directory entry screen.  Any OPTIONal installation
  1195.      segments that are declined by the user are not counted when
  1196.      determining adequate disk space.
  1197.      
  1198.                                 UNZIP
  1199.                                 -----
  1200.      
  1201.      Syntax: UNZIP <labelname> <zipfile> [VERIFY or UPGRADE]
  1202.      
  1203.      This token specifies a zip file that needs to be uncompressed.  The
  1204.      following assumptions are made with this command:
  1205.      
  1206.              1. The zip file is to be deleted from the destination disk
  1207.                 after decompression.  (Under no circumstances is it
  1208.                 possible to delete a zip file on the distribution disk.)
  1209.      
  1210.              2. The base destination for the extracted files is to be the
  1211.                 same directory that the zip file is in.  That is,
  1212.                 subdirectory information stored in the zip file is to be
  1213.                 used relative to the current zip file directory.
  1214.      
  1215.              3. The filename's default extension is 'zip'.
  1216.      
  1217.              4. The file was compressed with a version of Phil Katz' PKZIP
  1218.                 1.10 or earlier (or a 100% compatible .zip file creator.)
  1219.                 All storage methods used by this archiver (Explode,
  1220.                 Unshrink, etc.) are supported.
  1221.      
  1222.              5. The file was NOT encrypted with a password.
  1223.      
  1224.      labelname:
  1225.      
  1226.              The label specified here must have been previously defined
  1227.              with a USER command.
  1228.      
  1229.      zipfile:
  1230.      
  1231.              The zipfile must have been transferred via a FILE command.
  1232.              The extension is optional.
  1233.      
  1234.                              --- New with 1.60 ---
  1235.      
  1236.      
  1237.      
  1238.                           Install-Pro Reference Manual
  1239.                                       - 19 -
  1240.             
  1241.      
  1242.      
  1243.      
  1244.       
  1245.      UPGRADE:
  1246.      
  1247.              This modifier indicates that any files newer than the file
  1248.              being transferred are to be overwritten only with permission
  1249.              from the user.  This modifier is reliant on the user's machine
  1250.              having a functional clock, and that the files on the user's
  1251.              machine reflect actual dates.
  1252.      
  1253.      
  1254.                              --- New with 1.60 ---
  1255.      VERIFY:
  1256.      
  1257.              This modifier directs Install-Pro to verify all file
  1258.              overwrites.
  1259.      
  1260.                              --- New with 1.60 ---
  1261.      
  1262.              Any directory information packed in a zip file is
  1263.              automatically created as needed during the unzip process.
  1264.              Under no circumstances will a file stored in a zip file with
  1265.              subdirectory information be unpacked into the current
  1266.              directory.
  1267.      
  1268.      
  1269.      
  1270.      Example:
  1271.      
  1272.      UNZIP label1 zipfile
  1273.      
  1274.      would unzip zipfile.zip in the directory associated with label1.
  1275.      
  1276.      Any number of UNZIP commands may be specified.
  1277.      
  1278.      If UNZIP refers to an OPTIONal label, the UNZIP will only occur if the
  1279.      user chose to include that part of the installation.
  1280.      
  1281.      Since an error extracting a zip file must be considered as dangerous
  1282.      as an error copying an installation file, crc or other unzip errors
  1283.      must be treated as fatal errors, with program abort, so double-check
  1284.      the integrity of your .zip files before distribution.
  1285.      
  1286.      
  1287.                                       RUN
  1288.                                       ---
  1289.      
  1290.      Syntax: RUN "any command line in quotes"
  1291.      
  1292.      This token defines a command line to be built to execute any special
  1293.      programs or batch files that are needed to customize an installation.
  1294.      One use for this might be to run a config.exe program that will bring
  1295.      
  1296.      
  1297.                           Install-Pro Reference Manual
  1298.                                       - 20 -
  1299.             
  1300.      
  1301.      
  1302.      
  1303.       
  1304.      the user straight into configuring the application he is installing.
  1305.      Another use might be to create application menu definition files that
  1306.      couldn't be built at install-time otherwise.
  1307.      
  1308.      Run works by one of two methods.  If the command specified on the
  1309.      command line has the extension ".EXE" or ".COM", the program is
  1310.      executed directly by Install-Pro.  If no .EXE or .COM extension is
  1311.      specified, your command is run by invoking a command processor shell
  1312.      and passing it the command line that you specify.  There must be
  1313.      enough memory to load both your program or command shell in addition
  1314.      to that used by Install-Pro - about 200k.  Run command lines of longer
  1315.      than one word must be enclosed in quotes.
  1316.      
  1317.      Any number of RUN command lines can be defined.
  1318.      
  1319.      Further, the directory(s) that the user enters at runtime are
  1320.      available on the RUN command lines.  Simply specify any label with a
  1321.      preceding exclamation point (!) and the user-entered directory will be
  1322.      directly substituted for that portion of the text.  The directory is
  1323.      inserted without any leading or trailing spaces, but the spaces on the
  1324.      RUN command line are UNTOUCHED. That means that the following RUN
  1325.      commands would work:
  1326.      
  1327.      RUN "dir !label_1"
  1328.      RUN "!label_1\myprog.exe"
  1329.      RUN "copy !label_1\this.fil !label_2"
  1330.      RUN "anydir\anyprog.exe"
  1331.      
  1332.      Finally, a special sequence, !home, signifies that you wish to specify
  1333.      the installation directory of the installation disk.  For obvious
  1334.      reasons, don't create any labels called 'home' with the USER command,
  1335.      or the !home sequence will no longer point at the home directory, but
  1336.      rather at the directory entered by the user for this labelname.
  1337.      
  1338.      RUN "!home\myprog.exe"
  1339.      
  1340.      would execute myprog from the installation directory of the
  1341.      installation disk.
  1342.      
  1343.      When a RUN command is executed, the screen is saved and cleared first.
  1344.      After it has completed, the screen is restored.
  1345.      
  1346.      If the command shell attempt fails, the user will be notified of the
  1347.      reason (usually memory) but the INSTALLATION WILL NOT ABORT.  If there
  1348.      is a critical part of your installation occurring with a RUN command,
  1349.      be sure to document it in your manual installation instructions for
  1350.      the user.
  1351.      
  1352.      A few points to keep in mind:
  1353.      
  1354.      
  1355.      
  1356.                           Install-Pro Reference Manual
  1357.                                       - 21 -
  1358.             
  1359.      
  1360.      
  1361.      
  1362.       
  1363.              1.  The error trapping is much more solid if Install-Pro
  1364.                  directly executes your program.  This is due to the fact
  1365.                  that if the command shell is used instead, success
  1366.                  constitutes the shell having successfully loaded.  Whether
  1367.                  enough ram existed for your program or your program was
  1368.                  found is not detectable by Install-Pro.  Whats worse, in
  1369.                  the case of older versions of the alternative command
  1370.                  processor 4dos, the command shell load process occurs in
  1371.                  two parts.  The first part of 4dos can load successfully
  1372.                  but fail to load the rest of itself and still return
  1373.                  success to Install-Pro.
  1374.      
  1375.              2.  Memory requirements for command shell RUN commands can be
  1376.                  significantly higher, especially if COMMAND.COM is the
  1377.                  target of COMSPEC (about 27k).
  1378.      
  1379.              3.  A single RUN command in .EXE mode is allowed up to 9
  1380.                  arguments. Additional arguments are ignored.  In command
  1381.                  shell mode, there is no limit to the number of arguments
  1382.                  allowed.
  1383.      
  1384.              4.  A single RUN command in .EXE mode is allowed a length of
  1385.                  up to 256 characters.  The length of any single argument
  1386.                  is restricted to 128 characters.  If argument zero (the
  1387.                  directory, path and filename of the executing program) is
  1388.                  longer than 128 characters, DOS will return an error
  1389.                  message back to Install-Pro.  If any other argument is
  1390.                  longer than 128 characters, the argument will be truncated
  1391.                  (undesirable, indeed.)
  1392.      
  1393.              5.  A single RUN command in command shell mode is allowed a
  1394.                  total length of up to 256 characters, but keep in mind
  1395.                  that the widely-used command interpreter COMMAND.COM will
  1396.                  only allow 128 characters total.  4dos, among others,
  1397.                  allows up to 256 characters.
  1398.      
  1399.              6.  I gave consideration to errorlevels from executed
  1400.                  programs (they are not available from shelled commands),
  1401.                  but considering the fact that the only recourse is to
  1402.                  report the errorlevel to the user as a 'possible error' or
  1403.                  alternatively to abort the installation, I abstained.
  1404.                  Registered users with special errorlevel needs are free to
  1405.                  contact me for a custom version of Install-Pro that will
  1406.                  handle errorlevels in one of these two fashions.
  1407.      
  1408.                              --- New with version 1.58 ---
  1409.      
  1410.              7.  RUN commands MAY access OPTIONal directories.  However, if
  1411.                  any of the optional directories listed in a RUN command
  1412.                  line were not accepted by the user (even if the directory
  1413.      
  1414.      
  1415.                           Install-Pro Reference Manual
  1416.                                       - 22 -
  1417.             
  1418.      
  1419.      
  1420.      
  1421.       
  1422.                  already exists), the command will be be ignored.  This
  1423.                  allows RUN commands to be conditional on whether an OPTION
  1424.                  was accepted.  If an OPTION is declined, you can be sure
  1425.                  that the associated RUN commands will not be executed.
  1426.      
  1427.                                     GOODBYE
  1428.                                     -------
  1429.      
  1430.      Syntax: GOODBYE "So-long text goes here"
  1431.      
  1432.      This token is used to build an end-of-install message to display to
  1433.      your users after successful completion of installation.  It can be up
  1434.      to 71 characters long, and like the HELLO lines, the GOODBYE text is
  1435.      displayed in an auto-sizing window.  If you want to specify an empty
  1436.      line, use GOODBYE "".  The lack of any GOODBYE lines would cause a
  1437.      small, empty box to appear, harmless but silly looking.  Somewhere
  1438.      near the bottom of the GOODBYE text, you should include something to
  1439.      the effect that a keypress will exit the program.
  1440.      
  1441.      Any number of GOODBYE lines can be defined, anywhere in the script
  1442.      file(s). After 14 GOODBYE lines have been encountered without an
  1443.      intervening GOODBYEBREAK command (described below), a page break is
  1444.      automatically inserted by Install-Pro.
  1445.      
  1446.      When an install.??? file is processed that is terminated with an END
  1447.      token, after all transfers have taken place, the GOODBYE messages are
  1448.      displayed, after which the program terminates.
  1449.      
  1450.                                  GOODBYEBREAK
  1451.                                  ------------
  1452.      
  1453.                       --- New with Version 1.60 ---
  1454.      
  1455.      Syntax: GOODBYEBREAK
  1456.      
  1457.      This token tells Install-Pro that the next GOODBYE line defined in the
  1458.      script is to appear at the top of a new page.
  1459.      
  1460.                                    FIRSTDISK
  1461.                                    ---------
  1462.      
  1463.      Syntax: FIRSTDISK [disk name]
  1464.      
  1465.      This token allows you to name the first disk of the installation
  1466.      something besides "Disk 1" (for example, "Install Disk").  Other than
  1467.      slightly changing screen appearance and prompts, this token does not
  1468.      affect the physical operation of Install-Pro in any way.  If no
  1469.      argument follows the FIRSTDISK token, the default of "Disk 1" will be
  1470.      used.  If this token is omitted, "Disk 1" will be used as well.
  1471.      
  1472.      
  1473.      
  1474.                           Install-Pro Reference Manual
  1475.                                       - 23 -
  1476.             
  1477.      
  1478.      
  1479.      
  1480.       
  1481.      FIRSTDISK MUST come before DISK in install.001 to have any affect.
  1482.      
  1483.                                      DISK
  1484.                                      ----
  1485.      
  1486.      Syntax: DISK [disk name]
  1487.      
  1488.      This token specifies that the user is to be prompted to insert the
  1489.      next numbered disk.  The extension of the script file increments with
  1490.      each successive disk.  For example, if the disk being processed is
  1491.      disk 1 with install.001, specifying DISK would cause the user to be
  1492.      prompted to insert disk #2. If the user presses enter and the disk in
  1493.      the drive in which install.exe exists does not have install.002 in the
  1494.      root directory, the user will be instructed to try again.  This loop
  1495.      repeats until the user inserts the correct disk (if you've ensured
  1496.      that the user received it) or until the user presses Escape, which
  1497.      would terminate the program.
  1498.      
  1499.      The optional [disk name] argument allows you to name the following
  1500.      disk something besides "Disk n".  Common uses are "Utilities Disk",
  1501.      "Fonts Disk" or what-have-you.  If you adopt this or another naming
  1502.      convention, be sure to look up the FIRSTDISK token for instructions on
  1503.      naming the FIRST disk (since the DISK token always names the FOLLOWING
  1504.      disk.)
  1505.      
  1506.      DISK MUST come before AUTHORIZATION in install.001
  1507.      
  1508.      
  1509.                                       END
  1510.                                       ---
  1511.      
  1512.      Syntax: END
  1513.      
  1514.      This token indicates that the end of the last installation script has
  1515.      been reached.  Just like DISK, END forces all information stored in
  1516.      all labels to be processed.  However, unlike DISK, when this
  1517.      processing is completed, the program displays the GOODBYE messages and
  1518.      exits.
  1519.      
  1520.      This token is mutually exclusive of the DISK token.  Whichever is
  1521.      encountered first on any given diskette will dictate the processing
  1522.      that will occur, and the other will be ignored.
  1523.      
  1524.      END MUST come before AUTHORIZATION in install.001.
  1525.      
  1526.      
  1527.      
  1528.      
  1529.      
  1530.      
  1531.      
  1532.      
  1533.                           Install-Pro Reference Manual
  1534.                                       - 24 -
  1535.             
  1536.      
  1537.      
  1538.      
  1539.       
  1540.                                      CHAIN
  1541.                                      -----
  1542.      
  1543.      Syntax: CHAIN
  1544.      
  1545.      This token indicates that the end of the last installation script has
  1546.      been reached, just like END.  When this token is reached, all
  1547.      work accumulated is processed.  Unlike END, however, CHAIN is a
  1548.      conditional installation terminator.  The user is presented with "Do
  1549.      you wish to install another module (Yes/No)".  If the user selects NO,
  1550.      then the GOODBYE screen is displayed and Install-Pro terminates.
  1551.      
  1552.      If the user selects YES, then he is prompted to insert Disk 1 of the
  1553.      next module and Install-Pro transfers control to another copy of
  1554.      itself on the new diskette, and the old copy of Install-Pro in memory
  1555.      is discarded.  Any GOODBYE screen will be handled by the new copy of
  1556.      Install-Pro.
  1557.      
  1558.      The actual filename that is looked for with CHAIN is the identical
  1559.      path and filename of the currently executing process.  So, if you have
  1560.      renamed one copy of Install-Pro to INSTALL.EXE, they all must be
  1561.      renamed that way.
  1562.      
  1563.      The traditional use for this type of termination is in the case of
  1564.      integrated accounting software, where it is unknown at runtime how
  1565.      many modules (General Ledger, System Manager, Accounts Receivable,
  1566.      etc.) have been purchased.
  1567.      
  1568.                                  AUTHORIZATION
  1569.                                  -------------
  1570.      
  1571.      Syntax: AUTHORIZATION 00000
  1572.      
  1573.      This token is only required on the last line of install.001.  Its
  1574.      function is solely to create a space for Install-Pro to write an
  1575.      authorization code. After you have run Install-Pro with your key on
  1576.      the command line, this line will be updated with the appropriate
  1577.      authorization code for the current script.
  1578.      
  1579.      If you are evaluating an unregistered copy of Install-Pro, you need
  1580.      not worry about this line. The authorization concept is used purely to
  1581.      ensure the integrity of registered versions.
  1582.      
  1583.      ───────────────────────────────────────────────────────────────────────────
  1584.                                Script Debugging
  1585.      ───────────────────────────────────────────────────────────────────────────
  1586.      
  1587.      Before you send your latest sale to your customers, you are going to
  1588.      want to make sure that the installation as you envision it is actually
  1589.      going to happen.  I have made a great effort to make all error
  1590.      
  1591.      
  1592.                           Install-Pro Reference Manual
  1593.                                       - 25 -
  1594.             
  1595.      
  1596.      
  1597.      
  1598.       
  1599.      messages as descriptive as possible.  In the cases of DOS returning an
  1600.      error, the error message is given verbatim back to you.  I have taken
  1601.      great lengths to make the parser as smart as possible; however, it is
  1602.      possible to make any parser look stupid with intentional or lucky
  1603.      entries (just leave a terminating curly bracket off a c function if
  1604.      you need proof.)  If you follow the syntax closely, the parser will
  1605.      make both Install-Pro and your application look great.  If you feel
  1606.      that your syntax is correct, or should be, but the parser seems to
  1607.      disagree with you, leave me a note through the channels described in
  1608.      "Contacting the Author."
  1609.      
  1610.      ───────────────────────────────────────────────────────────────────────────
  1611.                                 Error Messages
  1612.      ───────────────────────────────────────────────────────────────────────────
  1613.      
  1614.      The following are the standard error messages built into Install-Pro.
  1615.      The nature of these errors is such that Install-Pro cannot continue,
  1616.      so these error messages can probably be classified as Fatal Errors.
  1617.      Of course, the message the user sees doesn't include the word 'Fatal'
  1618.      for obvious reasons.  The message the user sees is similar to the one
  1619.      that follows:
  1620.      
  1621.           ┌────────────────────────────────────────────────────────────┐
  1622.           │                                                            │
  1623.           │     The following unrecoverable error has occurred:        │
  1624.           │                                                            │
  1625.           │                 Error opening install.001                  │
  1626.           │                                                            │
  1627.           │ Please refer to your documentation for manual installation │
  1628.           │ instructions if the problem cannot be corrected.           │
  1629.           │                                                            │
  1630.           │                Press a key to terminate...                 │
  1631.           └────────────────────────────────────────────────────────────┘
  1632.      
  1633.      Any application should be distributed with manual installation
  1634.      instructions to help alleviate the unexpected, hence the wordage of
  1635.      the error message.  The documentation that you provide your users
  1636.      should include a telephone number in case of installation
  1637.      difficulties, or in case manual procedures also didn't succeed.
  1638.      
  1639.      DOS version 3.0 or higher required
  1640.      
  1641.            A DOS version prior to 3.0 was detected.  Install-Pro requires
  1642.            MS-DOS 3.0 or later.
  1643.      
  1644.      Error opening install.001
  1645.      
  1646.            INSTALL.001 was not found in the same directory as Install-Pro,
  1647.            or there were no file handles available.
  1648.      
  1649.      
  1650.      
  1651.                           Install-Pro Reference Manual
  1652.                                       - 26 -
  1653.             
  1654.      
  1655.      
  1656.      
  1657.       
  1658.      Token was expected but not found: line nn
  1659.      
  1660.            A token was expected but not found on the indicated line. This
  1661.            usually means that one or more words is missing on this line.
  1662.      
  1663.      Memory allocation error
  1664.      
  1665.            A request for more memory was denied.  This is extremely
  1666.            unlikely to occur, as Install-Pro requires under 200k of free
  1667.            RAM.
  1668.      
  1669.      Error copying xxxxxxx
  1670.      
  1671.            DOS returned an error while trying to transfer the indicated
  1672.            file to the indicated destination.
  1673.      
  1674.      Cannot copy a file onto itself
  1675.      
  1676.            The user specified the installation diskette as the destination.
  1677.      
  1678.      Error creating directory: zzzzz
  1679.      
  1680.            DOS returned an error while trying to create the indicated
  1681.            directory.  The most likely cause is if the user tries to
  1682.            install the application to a directory that is the same name as
  1683.            an existing file.
  1684.      
  1685.      Authorization Error (registered versions only)
  1686.      
  1687.            Install-Pro detected an authorization code that did not match
  1688.            the accompanying script file (install.001).  Run Install-Pro
  1689.            again with your key to authorize your script.
  1690.      
  1691.      Executable integrity Error - bad executable
  1692.      
  1693.            Install-Pro detected internal errors in its executable file.
  1694.            This usually means that the file has become corrupted.  Restore
  1695.            an original from your backup and retry.
  1696.      
  1697.      Label not found: xxxxx, line nn
  1698.      
  1699.            The token in the <label name> position on the specified line
  1700.            does not correspond to a previously defined label name created
  1701.            with a USER line.
  1702.      
  1703.      Invalid Disk Space Number
  1704.      
  1705.            Either no token, or an invalid token, was detected after the
  1706.            SPACE token.
  1707.      
  1708.      
  1709.      
  1710.                           Install-Pro Reference Manual
  1711.                                       - 27 -
  1712.             
  1713.      
  1714.      
  1715.      
  1716.       
  1717.      Unexpected EOF - AUTHORIZATION, END or DISK expected
  1718.      
  1719.            If Install-Pro parses to the end of a script without finding
  1720.            some indication of how to terminate, it returns this error.
  1721.      
  1722.      Zip output file creation error
  1723.      
  1724.            An error was detected while trying to create a file embedded in
  1725.            a zip file.  The usual causes are out of disk space, an existing
  1726.            directory of the same name, or an embedded subdirectory that
  1727.            wasn't created with a SUBDIR command.
  1728.      
  1729.      Zip file open error
  1730.      
  1731.            The zip file was not found, or no file handles were available.
  1732.      
  1733.      Invalid zip file header
  1734.      
  1735.            An inconsistency was detected in the zip file.
  1736.      
  1737.      Zip file corrupted
  1738.      
  1739.            An extracted file's crc did not match its reported crc.
  1740.      
  1741.      Zip file encrypted
  1742.      
  1743.            Encrypted zip files (and the inherent password needed to build
  1744.            the decryption key) are not supported.
  1745.      
  1746.      USER must precede SPACE
  1747.      
  1748.            A label's disk space requirements are stored within the
  1749.            structure that is created when USER defines the associated
  1750.            label.
  1751.      
  1752.      Error chaining to new program
  1753.      
  1754.            An error was encountered while trying to load a new copy of
  1755.            Install-Pro.  Possible causes are insufficient memory or file
  1756.            not found.
  1757.      
  1758.      System Error - current directory not available
  1759.      
  1760.            Install-Pro requested from DOS the name of the current
  1761.            directory, but DOS returned an error.
  1762.      
  1763.      System Error - change directory failed
  1764.      
  1765.            An attempt by Install-Pro to change to another directory (to
  1766.            unzip a file) failed.
  1767.      
  1768.      
  1769.                           Install-Pro Reference Manual
  1770.                                       - 28 -
  1771.             
  1772.      
  1773.      
  1774.      
  1775.       
  1776.      
  1777.      Unexpected end of file
  1778.      
  1779.            The end of a zip file was encountered unexpectedly.
  1780.      
  1781.      Disk Write Error - target disk full?
  1782.      
  1783.            The majority of disk write errors are a full disk, but they
  1784.            could also be caused by hard disk failure or logical errors in
  1785.            the FAT table.
  1786.      
  1787.      Directories must be 65 characters or less
  1788.      
  1789.            The path entered by the user plus the SUBDIR attached to it
  1790.            exceeded DOS' maximum.  Don't define SUBDIRs longer than 20
  1791.            characters to be safe.
  1792.      
  1793.      UPGRADE and VERIFY are not supported with split files
  1794.      
  1795.            Split files cannot be designated for UPGRADE or VERIFY.  This is
  1796.            because the trailing portion of a split file has no way of
  1797.            knowing if its existing target was verified or not.
  1798.      
  1799.      Unsupported ZIP version
  1800.      
  1801.            A ZIP version of higher than 1.1 was detected in a zip file.
  1802.            Since no version of ZIP greater than 1.1 currently exists, this
  1803.            error may likely indicate zip file corruption.
  1804.      
  1805.      Invalid command
  1806.      
  1807.            The first token encountered on the indicated line in the script
  1808.            was not a valid command.
  1809.      
  1810.      ───────────────────────────────────────────────────────────────────────────
  1811.                                 Critical Errors
  1812.      ───────────────────────────────────────────────────────────────────────────
  1813.      
  1814.      Should a disk door be left open (or any other critical error trapped
  1815.      by DOS, for that matter) a Critical Error handler built into
  1816.      Install-Pro will take control and provide the user with a menu similar
  1817.      to this one:
  1818.      
  1819.      
  1820.      
  1821.      
  1822.      
  1823.      
  1824.      
  1825.      
  1826.      
  1827.      
  1828.                           Install-Pro Reference Manual
  1829.                                       - 29 -
  1830.             
  1831.      
  1832.      
  1833.      
  1834.       
  1835.                    ┌──────────[DOS Critical Error]──────────┐
  1836.                    │                                        │
  1837.                    │   [Abort]  [Retry]  [Ignore]  [Fail]   │
  1838.                    │                                        │
  1839.                    └────────────────────────────────────────┘
  1840.      
  1841.      If the user accepts retry, he will be in most cases safe.  Of course,
  1842.      if his computer picked the exact moment that he's installing your
  1843.      application to crash its hard drive, no Critical Error handler is
  1844.      going to recover very gracefully.
  1845.      
  1846.      
  1847.      ───────────────────────────────────────────────────────────────────────────
  1848.                                Registration Keys
  1849.      ───────────────────────────────────────────────────────────────────────────
  1850.      
  1851.      This section deals only with registered copies of Install-Pro.
  1852.      Shareware versions have no distribution protection built in
  1853.      whatsoever.
  1854.      
  1855.      With your registered Install-Pro diskette you received a key in the
  1856.      form of a series of characters.  This key protects copies of
  1857.      Install-Pro that are released with your applications from being used
  1858.      with scripts other than the one you defined.  This key is utilized
  1859.      simply by you the programmer including it with absolutely no
  1860.      accompanying punctuation whatsoever as the only argument on the
  1861.      install.exe command line.  The result is that the script is processed
  1862.      normally, with an authorization code created on the AUTHORIZATION
  1863.      line.  Observing this procedure ensures that your scripts never cause
  1864.      Install-Pro to abort with an Authorization Error message.  For
  1865.      development purposes, just create a batch file to save repeatedly
  1866.      typing in your key.  Then, when you release your product, the script
  1867.      has the latest AUTHORIZATION (see above) encoded in your script,
  1868.      enabling Install-Pro to only to work with the unmodified script.  This
  1869.      protects my product, as well as protects your installation from
  1870.      unwanted tampering.
  1871.      
  1872.      
  1873.      
  1874.      
  1875.      
  1876.      
  1877.      
  1878.      
  1879.      
  1880.      
  1881.      
  1882.      
  1883.      
  1884.      
  1885.      
  1886.      
  1887.                           Install-Pro Reference Manual
  1888.                                       - 30 -
  1889.       
  1890.