home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / dscar30.zip / DSCAR.DOC < prev    next >
Text File  |  1989-07-23  |  93KB  |  2,337 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                    dBASE Source Code Analyzer & Reporter
  15.             ───────────────────────────────────────────────────
  16.                   ..    .......    .......    ......     ......
  17.                   ..   ..    ..   ..    ..   ..    ..   ..    ..
  18.                   ..   ..         ..         ..    ..   ..    ..
  19.                   ..   ..         ..         ..    ..   ..    ..
  20.             ........   .......    ..         ........   .......
  21.            ..     ..         ..   ..         ..    ..   .. ..
  22.            ..     ..   ..    ..   ..    ..   ..    ..   ..  ..
  23.             ........   .......     .......   ..    ..   ..   ..
  24.             ───────────────────────────────────────────────────
  25.                                 Version 3.0
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.                     Designed and written by Ryan Katri
  39.  
  40.                            2575 Drake Hill Road
  41.                             Fortuna, CA  95540
  42.                               (707) 725-5559
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.                    Copyright (c) 1986-89 by Ryan Katri.
  58.                            All Rights Reserved.
  59.  
  60.  
  61.  
  62.      TABLE OF CONTENTS
  63.      ──────────────────────────────────────────────────────────────────────
  64.  
  65.      INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
  66.  
  67.      UNREGISTERED VERSION OF dSCAR. . . . . . . . . . . . . . . . . . . . 2
  68.  
  69.      ORDERING dSCAR . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
  70.  
  71.      SYSTEM REQUIREMENTS & DISTRIBUTION . . . . . . . . . . . . . . . . . 4
  72.  
  73.      INSTALLING THE FILES . . . . . . . . . . . . . . . . . . . . . . . . 5
  74.  
  75.      STARTING dSCAR . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
  76.  
  77.      THE MENU SCREEN. . . . . . . . . . . . . . . . . . . . . . . . . . . 7
  78.  
  79.      MENU OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
  80.              Diagramming. . . . . . . . . . . . . . . . . . . . . . . . . 9
  81.              Line Numbers . . . . . . . . . . . . . . . . . . . . . . . .11
  82.              Controls Only. . . . . . . . . . . . . . . . . . . . . . . .12
  83.              Errors Only. . . . . . . . . . . . . . . . . . . . . . . . .13
  84.              Suppress Comments. . . . . . . . . . . . . . . . . . . . . .13
  85.              Proc/Funct:. . . . . . . . . . . . . . . . . . . . . . . . .13
  86.              Lines 1 to END . . . . . . . . . . . . . . . . . . . . . . .13
  87.              X-Reference. . . . . . . . . . . . . . . . . . . . . . . . .14
  88.              Modules. . . . . . . . . . . . . . . . . . . . . . . . . . .15
  89.              Word Fix-Up. . . . . . . . . . . . . . . . . . . . . . . . .16
  90.              Your Reserved. . . . . . . . . . . . . . . . . . . . . . . .17
  91.              Comment Condition. . . . . . . . . . . . . . . . . . . . . .17
  92.              Screen . . . . . . . . . . . . . . . . . . . . . . . . . . .18
  93.              Printer. . . . . . . . . . . . . . . . . . . . . . . . . . .18
  94.              File . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
  95.              Output Print-Style . . . . . . . . . . . . . . . . . . . . .19             20
  96.              Non-stop Scroll. . . . . . . . . . . . . . . . . . . . . . .19
  97.              Analyze Another. . . . . . . . . . . . . . . . . . . . . . .19
  98.              Install Temporary. . . . . . . . . . . . . . . . . . . . . .20
  99.              Save Defaults. . . . . . . . . . . . . . . . . . . . . . . .20
  100.              Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
  101.              Begin Processing . . . . . . . . . . . . . . . . . . . . . .20
  102.  
  103.      BATCH MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
  104.  
  105.      MODULES PROCESSING QUEUE . . . . . . . . . . . . . . . . . . . . . .23
  106.  
  107.      CODING ERRORS dSCAR REPORTS  . . . . . . . . . . . . . . . . . . . .24
  108.  
  109.      ADDING RESERVED WORDS. . . . . . . . . . . . . . . . . . . . . . . .25
  110.  
  111.      OTHER FEATURES & TIPS. . . . . . . . . . . . . . . . . . . . . . . .27
  112.  
  113.      CONFIGURING dSCAR. . . . . . . . . . . . . . . . . . . . . . . . . .28
  114.              Miscellaneous Settings . . . . . . . . . . . . . . . . . . .29
  115.              Install Colors . . . . . . . . . . . . . . . . . . . . . . .33
  116.              Printer Setup and Reset. . . . . . . . . . . . . . . . . . .34
  117.  
  118.  
  119.  
  120.      INTRODUCTION
  121.      ──────────────────────────────────────────────────────────────────────
  122.  
  123.      dSCAR is a set of utilities for all versions of dBASE, FoxBase,
  124.      Clipper, FrontRunner, and other dBASE clones.  All of the utilities
  125.      are contained in one user interface and are turned on and off through
  126.      command line options or the dSCAR menu system.
  127.  
  128.      The dSCAR utilities perform a variety of tasks, with these being a few
  129.      of the highlights:
  130.  
  131.      ■ PRETTY-PRINTS SOURCE CODE -- Your code will be more readable
  132.        with these clean-up functions dSCAR performs:
  133.  
  134.              - Properly indents code, lining up all structural statements
  135.              - Changes variables and reserved words as specified to
  136.                UPPERCASE/lowercase/SIGNificant case/Proper case
  137.              - Can comment conditional statements if specified
  138.              - Optionally removes user comments from source code
  139.  
  140.      ■ UNCOVERS ERRORS -- dBASE and its clones do not catch all errors in
  141.        source code, especially structural errors.  dSCAR flags
  142.        those errors dBASE misses.
  143.  
  144.      ■ CREATES FLOW DIAGRAMS -- To aid in reading your source code,
  145.        dSCAR will add graphic flow diagrams lining up structural
  146.        statements (like DO WHILE...ENDDO, IF...ENDIF).
  147.  
  148.      ■ CONSTRUCTS VARIABLES CROSS-REFERENCES -- Two types of variables
  149.        cross-references can be created:
  150.  
  151.              - Local cross-references display the line numbers where
  152.                variables are found within a specific module.
  153.              - Global cross-references are for an entire system, and tell
  154.                which modules each variable is found in.
  155.  
  156.      ■ ADDS LINE NUMBERS -- Line numbering source code is necessary
  157.        for cross-references, yet it is also useful when analyzing
  158.        printouts and debugging code.
  159.  
  160.      ■ OUTPUTS TO SCREEN, FILE, AND PRINTER -- Send dSCAR output to a
  161.        variety of devices:
  162.  
  163.              - Screen output for quick checking of errors, with all
  164.                errors being highlighted in specified color.
  165.              - Printer output adds user-defined header on each page,
  166.                optionally include page number, module name, system name,
  167.                copyright notice, and more.  A table of contents is also
  168.                created if a whole system is being documented.
  169.              - File output so that you can execute your pretty-printed
  170.                code, or send to a file with printer codes intact for
  171.                later printing.
  172.  
  173.  
  174.  
  175.  
  176.                                    Page 1
  177.  
  178.  
  179.  
  180.      UNREGISTERED VERSION OF dSCAR
  181.      ──────────────────────────────────────────────────────────────────────
  182.  
  183.      The unregistered version of dSCAR is fully functional with no features
  184.      disabled.  The difference between the registered and unregistered
  185.      versions of dSCAR are the opening and closing screens.
  186.  
  187.      The unregistered version has two opening screens:  a title screen and
  188.      an information screen.  Pressing any key will page you through the
  189.      screens.  After these screens are displayed the dSCAR menu is
  190.      presented.
  191.  
  192.      The unregistered closing screen is displayed only if you operate dSCAR
  193.      for more than five minutes at a time.  The closing screen urges you to
  194.      register dSCAR and gives you the option of printing a registration
  195.      form by pressing the 'R' key.  Please do not use this registration
  196.      form unless the ORDER.EXE program is NOT included with the dSCAR
  197.      package you received.
  198.  
  199.      By registering dSCAR you get the latest version of dSCAR without the
  200.      opening and closing screens.  In addition you will receive a printed
  201.      manual and unlimited support by phone or by mail.  You will also be
  202.      informed of major dSCAR upgrades and be entitled to updating to newer
  203.      versions at a nominal charge.
  204.  
  205.      See the chapter "ORDERING dSCAR" (next page) for ordering
  206.      instructions.
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.                                    Page 2
  237.  
  238.  
  239.  
  240.      ORDERING dSCAR
  241.      ──────────────────────────────────────────────────────────────────────
  242.  
  243.      Use the ORDER.EXE program to print a registration form.  ORDER will
  244.      request the information needed to register:  your name, your company
  245.      name, your address, and other pertinent information.  In addition, it
  246.      will ask if you are overseas and if you will be sending a purchase
  247.      order.  Both incur additional costs.
  248.  
  249.      ORDER will compute sales tax if you are in California and add in the
  250.      extra cost of overseas shipping and purchase order handling.  The
  251.      total registration cost is displayed on the screen.  A check or money
  252.      order for that amount should be made out and mailed to:
  253.  
  254.                      Ryan Katri
  255.                      2575 Drake Hill Road
  256.                      Fortuna, CA  95540
  257.  
  258.      ORDER also allows the entry of optional comments.  If you have any
  259.      suggestions, complaints, or kudos about dSCAR, enter them in the
  260.      comment area.
  261.  
  262.      When all the information is collected, ORDER will print a registration
  263.      form.  Please include the form with your check, money order, or
  264.      purchase order.
  265.  
  266.  
  267.      This is the current price list for dSCAR v3.0 (prices are subject to
  268.      change):
  269.  
  270.              dSCAR with printed manual..........$ 49.95 each
  271.              dSCAR without printed manual.......$ 39.95 each
  272.              dSCAR Unlimited Site License.......$400.00
  273.  
  274.      Add the following if applicable:
  275.  
  276.              Sales tax in California............6% on dSCAR base price only
  277.              Purchase orders less than $100.00..$  5.00
  278.              Overseas shipping..................$  2.00
  279.  
  280.  
  281.      Do not compute sales tax on the purchase order handling and overseas
  282.      shipping costs.
  283.  
  284.  
  285.      Site licenses are unlimited within a single company.  dSCAR is
  286.      supplied on a single disk and with a single printed manual.
  287.      It is the responsibility of the purchaser to copy disks and print
  288.      or photocopy manuals.
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.                                    Page 3
  297.  
  298.  
  299.  
  300.      SYSTEM REQUIREMENTS & DISTRIBUTION
  301.      ──────────────────────────────────────────────────────────────────────
  302.  
  303.      dSCAR will run on any of the IBM-PC family of computers, including the
  304.      PC, PC/XT, PC/AT, and PS/2.  It should also run on most IBM-compatible
  305.      machines.
  306.  
  307.      If your computer will run dBASE or a dBASE-compatible compiler or
  308.      interpreter (such as FoxBase, Clipper, etc), then it should also work
  309.      with dSCAR.
  310.  
  311.      The unregistered version of dSCAR is distributed in either the .ZIP or
  312.      .ARC archive formats.  The following files should be included in this
  313.      archive:
  314.  
  315.              DSCAR.EXE    - the executable program
  316.              DSCAR.DOC    - dSCAR documentation
  317.              READ.ME      - important last-minute info you should read
  318.              ORDER.EXE    - program to create registration form
  319.              INSTALL.BAT  - installation batch file
  320.              USE_FOX.BAT  - part of installation for FoxBase
  321.              USE_CLIP.BAT - part of installation for Clipper
  322.              ASKYN.EXE    - used in installation batch file
  323.  
  324.      If you received dSCAR on a disk and not in an archive, say from an
  325.      associate or a software distributor, make sure that all of the above
  326.      files are present.  If any of these files are missing then you
  327.      received an incomplete package.
  328.  
  329.      The READ.ME file may contain some important information which did not
  330.      get into the manual, so it is recommended that you read this file.
  331.  
  332.      If you wish to distribute dSCAR to your associates, distribute only
  333.      DSCAR??.ZIP.  It is illegal to give away a copy of the registered
  334.      version of DSCAR.EXE.  The dSCAR program contained in the .ZIP file
  335.      contains a functional copy of dSCAR.  The only drawback is that it
  336.      bears two sign-on screens and a closing screen urging the user to
  337.      register.
  338.  
  339.      DSCAR.EXE is the only file necessary to run dSCAR.  All other files
  340.      are optional and dSCAR can operate independent of all of them.
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.                                    Page 4
  357.  
  358.  
  359.  
  360.      INSTALLING THE FILES
  361.      ──────────────────────────────────────────────────────────────────────
  362.  
  363.      To copy the dSCAR files over to another floppy disk or hard disk,
  364.      first log into the drive and directory you want to put dSCAR on. Then,
  365.      put the distribution disk in another drive and type:
  366.  
  367.                      <drive>:INSTALL <drive>:
  368.  
  369.      <drive> is the drive letter where the dSCAR distribution disk is
  370.      located.  If this is drive A:, you would type:
  371.  
  372.                      A:INSTALL A:
  373.  
  374.      Install performs two functions.  First, it copies DSCAR.EXE from the
  375.      distribution disk to the current drive and directory.  Secondly, it
  376.      asks if you are using Clipper or FoxBase.
  377.  
  378.      If you are using Clipper or FoxBase then the install program will
  379.      create a RESERVED file in the current directory.  The RESERVED file
  380.      contains language extensions for the cross-reference feature of dSCAR.
  381.      See the chapter titled "ADDING RESERVED WORDS" (page 25) for more
  382.      information.  For now you can ignore the RESERVED file.
  383.  
  384.      You do not have to use the install program to copy dSCAR.  DSCAR.EXE
  385.      is the only necessary file to operate dSCAR, and it may be copied to
  386.      other directories and disks using the Dos COPY command.  If you are
  387.      using a hard disk it is recommended you just put DSCAR.EXE in a
  388.      directory found in your path statement.
  389.  
  390.      If you wish to configure dSCAR at this point, turn to the chapter
  391.      heading "CONFIGURING dSCAR" (page 28).  It is recommended, however,
  392.      that you run and familiarize yourself with dSCAR before making any
  393.      changes in configuration.
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.                                    Page 5
  417.  
  418.  
  419.  
  420.      STARTING dSCAR
  421.      ──────────────────────────────────────────────────────────────────────
  422.  
  423.      To start dSCAR, at the DOS prompt type:
  424.  
  425.              DSCAR  <return>
  426.  
  427.      If dSCAR is in the current directory or one of your path statements,
  428.      the options menu will be displayed and the second line of the screen
  429.      will prompt:
  430.  
  431.              dBASE file to process: *.PRG
  432.  
  433.      '*.PRG' is the default file mask.  Press <return> if you want to get a
  434.      list of all of the files with a .PRG extension.  Or, type in the name
  435.      of the dBASE program file you wish to process.  Path designations are
  436.      acceptable.  <ESC> will exit dSCAR.
  437.  
  438.      A quicker way to bring up dSCAR is to include the file to process on
  439.      the command line.  The syntax is:
  440.  
  441.              DSCAR <filename>  <return>
  442.  
  443.      Where <filename> is the name of the dBASE file to be processed.
  444.  
  445.      Wildcards are acceptable in filenames.  If a wildcard is entered at
  446.      the 'dBASE file to process' prompt, dSCAR will open up a window
  447.      displaying a list of the files matching the filespec.  You can then
  448.      scan the list using the <Up Arrow>, <Down Arrow>, <Page Up>, <Page
  449.      Down>, <Home>, and <End> keys.  Pressing a letter 'A'-'Z' will move
  450.      the cursor to the first filename beginning with that letter.  <Return>
  451.      will select the file the cursor is positioned on.
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.                                    Page 6
  477.  
  478.  
  479.  
  480.      THE MENU SCREEN
  481.      ──────────────────────────────────────────────────────────────────────
  482.  
  483.      The dSCAR menu screen is divided into three areas:  the status lines,
  484.      the selection window, and the installation window.  Each of these
  485.      areas is explained in detail:
  486.  
  487.      ■ Status Lines
  488.  
  489.      The status lines are the top three lines of the screen.  They contain
  490.      the dSCAR version number and copyright notice, the file which is
  491.      selected to be processed, and the output device or filename.
  492.      A sample status line is shown:
  493.  
  494.              dSCAR v3.0 (Copyright (c) 1986-89 Ryan Katri)
  495.              dBASE file to process: MAIN.PRG
  496.                        Output file: (screen)
  497.  
  498.      The output file will show a filename if output is to a file.  It will
  499.      display '(printer)' or '(screen)' if output is to one of these two
  500.      devices.
  501.  
  502.      ■ Selection Window
  503.  
  504.      The selection window displays the options which may be turned on or
  505.      off.  The window looks like this:
  506.  
  507.              ╔═════════════════════════════════════════════════╗
  508.              ║     -FLOW CONTROLS-          -DOCUMENTATION-    ║
  509.              ║                                                 ║
  510.              ║    D  Diagramming          X  X-Reference       ║
  511.              ║    L  Line numbers         M  Modules           ║
  512.              ║    C  Controls only        W  Word fix-up       ║
  513.              ║    E  Errors only          Y  Your reserved     ║
  514.              ║    *  Suppress comments    &  Comment condition ║
  515.              ║    =  Proc/Funct:                               ║
  516.              ║    #  Lines 1 to END                            ║
  517.              ║                                                 ║
  518.              ║    -OUTPUT OPTIONS-            -ACTIONS-        ║
  519.              ║                                                 ║
  520.              ║    S  Screen               A  Analyze another   ║
  521.              ║    P  Printer              I  Install temporary ║
  522.              ║    F  File                 !  Save defaults     ║
  523.              ║    O  Output print-style   Q  Quit              ║
  524.              ║    N  Non-stop scroll                           ║
  525.              ║                                                 ║
  526.              ║            RETURN: Begin Processing             ║
  527.              ╚═════════════════════════════════════════════════╝
  528.  
  529.      Selected (turned on) options are highlighted.  'Flow Controls',
  530.      'Documentation', 'Output Options', and 'Actions' are the option
  531.      headings.
  532.  
  533.  
  534.  
  535.  
  536.                                    Page 7
  537.  
  538.  
  539.  
  540.      You can toggle options on and off by hitting the key next to the
  541.      option.  For example, to turn Diagramming on and off, hit the 'D' key.
  542.      Some options are not toggles, specifically those under the Actions
  543.      heading.  Pressing <return> will start processing the selected program
  544.      file.
  545.  
  546.      ■ Installation Window
  547.  
  548.      The installation window resembles the following:
  549.  
  550.              ┌───── CONFIGURATION ────┐
  551.              │                        │
  552.              │ Indent Count    : 3    │
  553.              │ Diagram Type    : G    │
  554.              │ Reserved Case   : U    │
  555.              │ Variables Case  : P    │
  556.              │ Printer Port    : 1    │
  557.              │ Screen Length   : 22   │
  558.              │ Printer Length  : 63   │
  559.              │ Printer Width   : 80   │
  560.              │ File Width      : 79   │
  561.              │ Module Extension: PRG  │
  562.              │ Print-Style Ext.: PRN  │
  563.              │ Output Extension: FLO  │
  564.              │ X-Ref Extension : XRF  │
  565.              │ Truncate Lines  : N    │
  566.              │                        │
  567.              ├──── RESERVED WORDS ────┤
  568.              │ # Own Reserved  : 4    │
  569.              └────────────────────────┘
  570.  
  571.      Contained under the Configuration heading of this window are many of
  572.      the settings you can control through dSCAR's configuration program.
  573.      These settings can be modified for a single dSCAR session, however, by
  574.      selecting the option Install Temporary.  Thus, you can on-the-fly
  575.      change many of dSCAR's setting, such as the printer port to use or the
  576.      indent count.  If you change these settings from the menu screen, they
  577.      are changed for that session only.  To make permanent changes you must
  578.      run dSCAR's built-in configuration program.
  579.  
  580.      The Reserved Words heading tells how many reserved words are defined.
  581.      This feature is explained in a later section.
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.                                    Page 8
  597.  
  598.  
  599.  
  600.      MENU OPTIONS
  601.      ──────────────────────────────────────────────────────────────────────
  602.  
  603.      ■ DIAGRAMMING -- 'D' key toggles on/off
  604.  
  605.      One of the most useful features of dSCAR is its ability to line up all
  606.      your control statements to make sure they are structurally sound.
  607.      This makes it easy, for example, to see where you might have an open
  608.      CASE or a missing IF.
  609.  
  610.      dBASE will not catch structural errors, yet structural errors usually
  611.      result in erratic operation of your program.  If your program is
  612.      making some weird returns or executing loops improperly, dSCAR can be
  613.      called upon to see if the problem is structural.  Most dBASE language
  614.      compilers (ie Clipper) will warn of structural errors themselves.
  615.  
  616.      Below is a sample of code before it has been processed with dSCAR's
  617.      Diagramming option:
  618.  
  619.        ┌─CODE BEFORE PROCESSING─────────────────────────────────────┐
  620.        │                                                            │
  621.        │ DO WHILE .T.                                               │
  622.        │    ACCEPT 'What is your name?' TO Myname                   │
  623.        │    IF UPPER(Myname) <> 'JOE'                               │
  624.        │       ? 'Only Joe is allowed access!'                      │
  625.        │       RETURN                                               │
  626.        │    ELSE                                                    │
  627.        │       ? 'Hello Joe'                                        │
  628.        │       DO CASE                                              │
  629.        │       CASE Myname = 'JOE'                                  │
  630.        │          ? 'You typed in uppercase'                        │
  631.        │       CASE Myname = 'joe'                                  │
  632.        │          ? 'You typed in lowercase'                        │
  633.        │          RETURN                                            │
  634.        │       ENDCASE                                              │
  635.        │    ENDIF                                                   │
  636.        │ ENDDO                                                      │
  637.        └────────────────────────────────────────────────────────────┘
  638.  
  639.      The resulting output with Diagramming on would look something like
  640.      this:
  641.  
  642.        ┌─GRAPHIC FLOW DIAGRAMS──────────────────────────────────────┐
  643.        │                                                            │
  644.        │ ╓DO WHILE .T.                                              │
  645.        │ ║    ACCEPT 'What is your name?' TO Myname                 │
  646.        │ ║   ┌IF UPPER(Myname) <> 'JOE'                             │
  647.        │ ║   │    ? 'Only Joe is allowed access!'                   │
  648.        │ ────────RETURN                                            │
  649.        │ ║   ├ELSE                                                  │
  650.        │ ║   │    ? 'Hello Joe'                                     │
  651.        │ ║   │   ╒DO CASE                                           │
  652.        │ ║   │   ╞CASE Myname = 'JOE'                               │
  653.  
  654.  
  655.  
  656.                                    Page 9
  657.  
  658.  
  659.  
  660.        │ ║   │   │    ? 'You typed in uppercase'                    │
  661.        │ ║   │   ╞CASE Myname = 'joe'                               │
  662.        │ ║   │   │    ? 'You typed in lowercase'                    │
  663.        │ ────────────RETURN                                        │
  664.        │ ║   │   ╘ENDCASE                                           │
  665.        │ ║   └ENDIF                                                 │
  666.        │ ╙ENDDO                                                     │
  667.        └────────────────────────────────────────────────────────────┘
  668.  
  669.      The above example assumes that graphic flow diagrams are selected.
  670.      Graphic diagrams use single and double lines to show how your
  671.      program's flow is structured.  Double lines are used for DO WHILE and
  672.      DO CASE statements, while single lines for IF statements.  Horizontal
  673.      lines are used to indicate where the flow jumps to when a RETURN,
  674.      LOOP, or EXIT is encountered.
  675.  
  676.      You can change from graphic flow diagrams to text diagrams through the
  677.      configuration or temporary installation.  Text diagrams are not as
  678.      attractive, but they are more informative if you are trying to figure
  679.      out the flow of a program.
  680.  
  681.      Here is what a text flow diagram looks like:
  682.  
  683.        ┌─TEXT FLOW DIAGRAMS─────────────────────────────────────────┐
  684.        │                                                            │
  685.        │ DO WHILE .T.                                               │
  686.        │ W    ACCEPT 'What is your name?' TO Myname                 │
  687.        │ W    IF UPPER(Myname) <> 'JOE'                             │
  688.        │ W   T    ? 'Only Joe is allowed access!'                   │
  689.        │ <--------RETURN                                            │
  690.        │ W    ELSE                                                  │
  691.        │ W   F    ? 'Hello Joe'                                     │
  692.        │ W   F    DO CASE                                           │
  693.        │ W   F    CASE Myname = 'JOE'                               │
  694.        │ W   F   1    ? 'You typed in uppercase'                    │
  695.        │ W   F    CASE Myname = 'joe'                               │
  696.        │ W   F   2    ? 'You typed in lowercase'                    │
  697.        │ <------------RETURN                                        │
  698.        │ W   F    ENDCASE                                           │
  699.        │ W    ENDIF                                                 │
  700.        │ ENDDO                                                      │
  701.        └────────────────────────────────────────────────────────────┘
  702.  
  703.      Notice that each control statement has a corresponding character to
  704.      represent it.  For example, a WHILE structure is lined up with a W.
  705.      Below is what each character in the text flow diagram represents:
  706.  
  707.           W - DO WHILE; terminates with ENDDO
  708.  
  709.           T - IF is true; terminates with ENDIF or ELSE
  710.  
  711.           F - ELSE is false; terminates with ENDIF
  712.  
  713.  
  714.  
  715.  
  716.                                    Page 10
  717.  
  718.  
  719.  
  720.           S - SCAN; terminates with ENDSCAN
  721.  
  722.           C - DO CASE; terminates with first CASE, OTHERWISE, or
  723.                ENDCASE
  724.  
  725.           # - Number of the case statement; terminates with next
  726.               CASE, OTHERWISE, or ENDCASE
  727.  
  728.           O - OTHERWISE; terminates with ENDCASE
  729.  
  730.           P - PRINTJOB; terminates with END PRINTJOB
  731.  
  732.           L - FOR; terminates with NEXT
  733.  
  734.      If you don't quite understand these, try running some of your dBASE
  735.      code through dSCAR with Diagramming on and you will get the picture.
  736.  
  737.      If you want runnable code that is simply indented without the flow
  738.      diagramming, then turn Diagramming off.  Code processed with all flow
  739.      control options turned off is still indented and can be executed by
  740.      dBASE and interpreted by a compiler.
  741.  
  742.      ■ LINE NUMBERS -- 'L' key toggles on/off
  743.  
  744.      Line Numbering will add line numbers to your source code.  If
  745.      Variables Cross-Reference is on, then it is recommended to have Line
  746.      Numbering on, as the variables are referenced with the corresponding
  747.      line numbers.
  748.  
  749.      There are two ways to line number.  The default method is to have each
  750.      complete line of source code assigned its own number.  The second
  751.      method gives each continuation line its own number.  For example, if a
  752.      long line of code will not fit on a single line, dSCAR will
  753.      automatically break it up into several lines using the dBASE
  754.      continuation feature; each continued line would be assigned a new line
  755.      number.
  756.  
  757.      An example of numbering if each complete line of source code is to
  758.      have a single line number:
  759.  
  760.        ┌─SINGLE NUMBER FOR CONTINUATION LINES───────────────────────┐
  761.        │                                                            │
  762.        │  1 do while .not. eof()                                    │
  763.        │  2    replace first with mfirst, last with mlast,;         │
  764.        │  2     company with mcompany, phone with mphone,;          │
  765.        │  2     address1 with maddress1, address2 with maddress2    │
  766.        │  3    skip                                                 │
  767.        │  4 enddo                                                   │
  768.        └────────────────────────────────────────────────────────────┘
  769.  
  770.      An example of numbering if continuation lines are assigned new
  771.      numbers:
  772.  
  773.  
  774.  
  775.  
  776.                                    Page 11
  777.  
  778.  
  779.  
  780.        ┌─NEW NUMBERS FOR CONTINUATION LINES─────────────────────────┐
  781.        │                                                            │
  782.        │  1 do while .not. eof()                                    │
  783.        │  2    replace first with mfirst, last with mlast,;         │
  784.        │  3     company with mcompany, phone with mphone,;          │
  785.        │  4     address1 with maddress1, address2 with maddress2    │
  786.        │  5    skip                                                 │
  787.        │  6 enddo                                                   │
  788.        └────────────────────────────────────────────────────────────┘
  789.  
  790.      The numbering method can be specified through the dSCAR configuration.
  791.  
  792.      ■ CONTROLS ONLY -- 'C' key toggles on/off
  793.  
  794.      This option tells dSCAR to only include the control lines in the
  795.      output.  These control lines would be commands such as DO
  796.      CASE/OTHERWISE/ENDCASE, IF/ELSE/ENDIF, DO WHILE/ENDDO, IF/ELSE/ENDIF,
  797.      SCAN/ENDSCAN, FOR/NEXT, and PRINT/END PRINTJOB.  This option is
  798.      usually used in conjunction with the Diagramming function.
  799.  
  800.      The utility of Controls Only is that you can view the structure of
  801.      your program without having to read through the extraneous code which
  802.      has no effect on structure.
  803.  
  804.      Below are examples of source code with Controls Only off and with
  805.      Controls Only on (in both cases Diagramming is turned on):
  806.  
  807.        ┌─CONTROLS ONLY OFF──────────────────────────────────────────┐
  808.        │                                                            │
  809.        │ ╓do while .t.                                              │
  810.        │ ║    accept 'What is your name?' to myname                 │
  811.        │ ║   ┌if upper(myname) <> 'JOE'                             │
  812.        │ ║   │    ? 'Only Joe is allowed access!'                   │
  813.        │ ────────return                                            │
  814.        │ ║   ├else                                                  │
  815.        │ ║   │    clear                                             │
  816.        │ ║   │    ? 'Hello Joe'                                     │
  817.        │ ║   │    ? 'Do you wish to check your messages now?        │
  818.        │ ║   │    accept to CheckMsg                                │
  819.        │ ║   │   ╒do case                                           │
  820.        │ ║   │   ╞case CheckMsg = 'Y'                               │
  821.        │ ║   │   │    do CheckIt                                    │
  822.        │ ║   │   ╞case CheckMsg = 'N'                               │
  823.        │ ║   │   │    ? 'Thank you for logging in.'                 │
  824.        │ ────────────return                                        │
  825.        │ ║   │   ╘endcase                                           │
  826.        │ ║   └endif                                                 │
  827.        │ ╙enddo                                                     │
  828.        └────────────────────────────────────────────────────────────┘
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.                                    Page 12
  837.  
  838.  
  839.  
  840.        ┌─CONTROLS ONLY ON───────────────────────────────────────────┐
  841.        │                                                            │
  842.        │ ╓do while .t.                                              │
  843.        │ ║   ┌if upper(myname) <> 'JOE'                             │
  844.        │ ────────return                                            │
  845.        │ ║   ├else                                                  │
  846.        │ ║   │   ╒do case                                           │
  847.        │ ║   │   ╞case CheckMsg = 'Y'                               │
  848.        │ ║   │   ╞case CheckMsg = 'N'                               │
  849.        │ ────────────return                                        │
  850.        │ ║   │   ╘endcase                                           │
  851.        │ ║   └endif                                                 │
  852.        │ ╙enddo                                                     │
  853.        └────────────────────────────────────────────────────────────┘
  854.  
  855.      Notice how much easier it is to follow the flow when Controls Only is
  856.      turned on.
  857.  
  858.      ■ ERRORS ONLY -- 'E' key toggles on/off
  859.  
  860.      With Errors Only on, only errors that are found in the dBASE code are
  861.      displayed.  When Errors Only is selected, the following options are
  862.      automatically turned off:  Line Numbers, Controls Only, Suppress
  863.      Comments, and Diagramming.
  864.  
  865.      See "CODING ERRORS dSCAR REPORTS" (page 24) for a list of the errors.
  866.  
  867.      ■ SUPPRESS COMMENTS -- '*' toggles on/off
  868.  
  869.      You can filter the comments out of your code by turning this option
  870.      on.  Useful to see only the necessary code for debugging.
  871.  
  872.      ■ PROC/FUNCT: -- '=' prompts for entry of procedure or function
  873.  
  874.      dSCAR will process only the selected procedure or function if you
  875.      indicate it here.  dSCAR will scan through your dBASE program files
  876.      until it encounters the selected procedure or function.  Only that
  877.      procedure or function will be processed.
  878.  
  879.      When you select this option dSCAR will ask for the procedure or
  880.      function to process.  The maximum length of a procedure name is 10
  881.      characters.  If you wish to turn this features off (it is not a
  882.      toggle) after already entering a procedure, just delete the procedure
  883.      name you had entered using the DELete key on the keyboard.
  884.  
  885.      ■ LINES 1 TO END -- '#' prompt for a beginning and ending line
  886.  
  887.      You can optionally select to have dSCAR process only a specific range
  888.      of line numbers in a module.  For example, you may want to process
  889.      only up through line 50 in your program.  Or, if you want to process
  890.      only lines 100 to 150, you can save time by skipping the first 99
  891.  
  892.  
  893.  
  894.  
  895.  
  896.                                    Page 13
  897.  
  898.  
  899.  
  900.      lines and everything after line 150.
  901.  
  902.      When entering a beginning line number, an entry of '0' or '1' means to
  903.      start from the beginning of the program.
  904.  
  905.      To have dSCAR process all the way to the end of the program, enter '0'
  906.      when prompted for the ending line number.
  907.  
  908.      This option only works with single modules.  Turning it on will
  909.      automatically turn Modules off.
  910.  
  911.      ■ X-REFERENCE -- 'X' toggles on/off
  912.      
  913.      Turning Variables Cross-Reference on will instruct dSCAR to prepare a
  914.      cross-reference of all variables as it processes each module.
  915.  
  916.      There are two types of cross-references:  local and global.  A local
  917.      cross-reference includes only variables found in one module or
  918.      procedure, and indicates on which line numbers found.  A global cross-
  919.      reference displays the modules each variable is found in.
  920.  
  921.      If Variables Cross-Reference is toggled on, it is recommended that
  922.      Line Numbers be turned on, as variables are referenced by their line
  923.      numbers in a local cross-reference.  If Modules is selected, then a
  924.      global cross-reference will be created; otherwise, only a local cross-
  925.      reference is generated.
  926.  
  927.      The local cross-reference is displayed after each individual module or
  928.      procedure is processed.  The listing for a local cross-reference is in
  929.      a format similar to this:
  930.  
  931.        ┌─LOCAL CROSS-REFERENCE──────────────────────────────────────┐
  932.        │                                                            │
  933.        │ Variable     Line number in file                           │
  934.        │ --------     -------------------                           │
  935.        │ CheckMsg:       11    13    15                             │
  936.        │ myname:         =2     3     4                             │
  937.        └────────────────────────────────────────────────────────────┘
  938.  
  939.      'CheckMsg' and 'myname' are variables.  'CheckMsg' occurs in lines 11,
  940.      13, and 15.  'myname' is found in lines 2, 3, and 4.  Notice the equal
  941.      sign (=) next to the 2 after 'myname.'  The equal sign indicates that
  942.      on line 2 'myname' is assigned a new value.  All variable assignments
  943.      are indicated with the equal sign, as well as being highlighted if
  944.      output is to the screen.
  945.  
  946.      If Modules is toggled on also, then a global cross-reference of
  947.      variables will also be generated.  The global cross-reference quickly
  948.      shows which variables occur in which modules.  If a variable occurs in
  949.      a procedure, then the procedure name is displayed with the module name
  950.      in parenthesis beside it.  A sample global cross-reference is shown:
  951.  
  952.  
  953.  
  954.  
  955.  
  956.                                    Page 14
  957.  
  958.  
  959.  
  960.        ┌─GLOBAL CROSS-REFERENCE─────────────────────────────────────┐
  961.        │                                                            │
  962.        │ Variable  occurs in Modules                                │
  963.        │ --------            -------                                │
  964.        │ CheckMsg:           TEST.PRG                               │
  965.        │ myname:             SHOWNAME(GETNAME.PRG) GETNAME.PRG      │
  966.        │                     TEST.PRG                               │
  967.        │ NoName:             SHOWNAME(GETNAME.PRG)                  │
  968.        │ TempName:           GETNAME.PRG                            │
  969.        └────────────────────────────────────────────────────────────┘
  970.  
  971.      'CheckMsg' occurs only in the TEST.PRG module.  'myname' occurs in two
  972.      modules and one procedure.  The procedure name is SHOWNAME, and
  973.      SHOWNAME is in the module GETNAME.PRG.  'NoName' is found solely in a
  974.      procedure, and TempName occurs in a single module.
  975.  
  976.      ■ MODULES -- 'M' key toggles on/off
  977.  
  978.      Turning Modules on will instruct dSCAR to process all modules that may
  979.      call each other in a complete dBASE system.
  980.  
  981.      Any time dSCAR encounters a DO <filename>, SET FORMAT TO <filename>,
  982.      or SET PROC TO <filename> it will add the filename to a list of
  983.      modules to be processed.  Thus, if you had several modules to process,
  984.      and they are all eventually called somewhere in the system, you could
  985.      start with the top module and dSCAR will work down from there. To
  986.      illustrate this:
  987.  
  988.      You have a module called MAIN.PRG, which calls ACCOUNTS.PRG and
  989.      INVENT.PRG.
  990.  
  991.      ACCOUNTS.PRG in turn calls EDIT.PRG, and INVENT.PRG also calls
  992.      EDIT.PRG.
  993.  
  994.      If you turn Modules on and start with the file MAIN.PRG, then  all of
  995.      these would get processed:  MAIN.PRG, ACCOUNTS.PRG, INVENT.PRG, and
  996.      EDIT.PRG.
  997.  
  998.      A module will NOT be processed twice!
  999.  
  1000.      The current module being processed is written at the bottom of the
  1001.      screen.  This makes it easy to see what modules have errors in them
  1002.      with a glance at the status line.
  1003.  
  1004.      Depending on what you specified in the configuration, drive
  1005.      designators and path names will or will not be stripped from
  1006.      filenames.  If pathnames are stripped, then dSCAR will search for
  1007.      modules first in the current directory.  If a module is not found in
  1008.      the current directory, dSCAR will search the directory in which the
  1009.      top module was specified to be in.
  1010.  
  1011.      If a file cannot be found a warning message is displayed to the
  1012.  
  1013.  
  1014.  
  1015.  
  1016.                                    Page 15
  1017.  
  1018.  
  1019.  
  1020.      screen.  Sometimes dSCAR will not find a module because the module is
  1021.      really a procedure.  In this case, ignore the warning message.
  1022.  
  1023.      If you wish to process a module as part of a system but that module is
  1024.      not being called by the system, use the MODULES file.  This is a file
  1025.      containing a list of modules you want added to the processing queue.
  1026.      See the chapter heading "MODULES PROCESSING QUEUE" (page 23) to see
  1027.      how to do this.
  1028.  
  1029.      ■ WORD FIX-UP -- 'W' key toggles on/off
  1030.  
  1031.      Word Fix-up will fix your code cosmetically by changing the case of
  1032.      reserved words and variables in your code.  For example, you may opt
  1033.      to capitalize all reserved words and lowercase variables.  You specify
  1034.      the case for reserved words and variables in dSCAR configuration.  It
  1035.      may also be changed through the temporary installation.
  1036.  
  1037.      There are five different ways to change the case of reserved words and
  1038.      variables:  upper, lower, proper, significant, and no change.  Upper
  1039.      and lower are self-explanatory.
  1040.  
  1041.      In proper case, the first letter of each word is capitalized.  For
  1042.      example, 'do while' becomes 'Do While' and 'REPLACE' becomes
  1043.      'Replace'.
  1044.  
  1045.      Significant case will capitalize only the first four letters of a
  1046.      word.  'do while' becomes 'DO WHILe' and 'replace' becomes 'REPLace.'
  1047.  
  1048.      No change will leave all reserved words or all variables as they are
  1049.      found in the code.  This is especially useful if you want to change
  1050.      the case of reserved words, but leave variables as you entered them.
  1051.  
  1052.      Below is an example of code before and after processing with Word Fix-
  1053.      up on.  In this case, reserved words are capitalized and variables are
  1054.      made proper case.
  1055.  
  1056.        ┌─CODE BEFORE PROCESSING─────────────────────────────────────┐
  1057.        │                                                            │
  1058.        │ do while .T.                                               │
  1059.        │    Accept 'What is your name?' to myname                   │
  1060.        │    IF upper(MYNAME) <> 'JOE'                               │
  1061.        │       ? 'Only Joe is allowed access!'                      │
  1062.        │       return                                               │
  1063.        │    ELSE                                                    │
  1064.        │       ? 'Hello Joe'                                        │
  1065.        │       retu                                                 │
  1066.        │    endif                                                   │
  1067.        │ enddo                                                      │
  1068.        └────────────────────────────────────────────────────────────┘
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.                                    Page 16
  1077.  
  1078.  
  1079.  
  1080.        ┌─WORD FIX-UP ON─────────────────────────────────────────────┐
  1081.        │                                                            │
  1082.        │ DO WHILE .T.                                               │
  1083.        │    ACCEPT 'What is your name?' TO Myname                   │
  1084.        │    IF UPPER(Myname) <> 'JOE'                               │
  1085.        │       ? 'Only Joe is allowed access!'                      │
  1086.        │       RETURN                                               │
  1087.        │    ELSE                                                    │
  1088.        │       ? 'Hello Joe'                                        │
  1089.        │       RETU                                                 │
  1090.        │    ENDIF                                                   │
  1091.        │ ENDDO                                                      │
  1092.        └────────────────────────────────────────────────────────────┘
  1093.  
  1094.      Keep in mind that Word Fix-up will not add or delete any code.  If you
  1095.      always use only the first four letters for dBASE commands and
  1096.      functions, dSCAR will not expand the word.  For example, if you used
  1097.      'retu' in your code, dBASE would make that 'RETU' (as shown in the
  1098.      code sample above).  It will not expand it to be 'RETURN'.
  1099.  
  1100.      ■ YOUR RESERVED -- 'Y' key toggles on/off
  1101.  
  1102.      In order to support the ever-changing and expanding dBASE language and
  1103.      dBASE clones, dSCAR allows you to add your own reserved words to its
  1104.      own list.  The main purpose of this is to keep those new commands
  1105.      which dSCAR does not recognize out of the cross-reference.
  1106.  
  1107.      Your own reserved words are contained in a file called RESERVED (no
  1108.      extension).  If dSCAR finds this file in the current directory then
  1109.      Your Reserved is automatically toggled on.  The words contained in
  1110.      RESERVED are read into dSCAR's list of reserved words and will no
  1111.      longer be added to a cross-reference of variables.
  1112.  
  1113.      If you do not wish to use the reserved words in RESERVED, then turn
  1114.      Your Reserved off.  The point of this is if you happen to be using two
  1115.      different dBASE compatible languages.  For example, you might use
  1116.      Clipper at times and dBASE IV at other times.  You will need the extra
  1117.      reserved words when processing Clipper code, so you would want Your
  1118.      Reserved toggled on.  However, when processing dBASE IV code you would
  1119.      want it toggled off, as all of dBASE IV's reserved words are part of
  1120.      dSCAR's internal list.
  1121.  
  1122.      See the chapter "ADDING RESERVED WORDS" (page 25) for instructions on
  1123.      creating your own reserved words list.
  1124.  
  1125.      ■ COMMENT CONDITION -- '&' toggles on/off
  1126.  
  1127.      dSCAR can aid in commenting your source code.  If Comment Condition is
  1128.      on, dSCAR will append the condition for an IF, DO WHILE, SCAN, and FOR
  1129.      to the finishing ENDIF, ENDDO, ENDSCAN and NEXT.  For example, take
  1130.      the following statement:
  1131.  
  1132.              IF x = 10
  1133.  
  1134.  
  1135.  
  1136.                                    Page 17
  1137.  
  1138.  
  1139.  
  1140.      When dSCAR encounters the ENDIF, it will add a comment like this:
  1141.  
  1142.              ENDIF && x = 10
  1143.  
  1144.      By doing so, it makes it easy to see what an ENDIF, ENDDO, or NEXT is
  1145.      terminating.  If there is already a comment on the ENDIF, ENDDO, or
  1146.      NEXT line, then dSCAR will leave the original comment intact and not
  1147.      add its own comment.
  1148.  
  1149.      ■ SCREEN -- 'S' key turns on, 'P', 'F', or 'O' turns off
  1150.  
  1151.      Hit the 'S' key if you want all output to go to the screen.  dSCAR
  1152.      will pause after a screen page is displayed unless Non-stop Scroll is
  1153.      toggled on.  After a page is displayed, dSCAR will prompt with the
  1154.      following message:
  1155.  
  1156.              Q to quit, N for non-stop, any other key to continue.
  1157.  
  1158.      Hitting 'Q' or <ESC> will return you to the dSCAR main menu.  'N' will
  1159.      make the display non-stop so it will not pause after each page.
  1160.      However, you can force a pause at any time by hitting the <ESC> key;
  1161.      you can then turn non-stop scrolling off if you wish.  Pressing a key
  1162.      besides 'Q' or 'N' will display the next screen page.
  1163.  
  1164.      At the end of processing the entire system, dSCAR will display this
  1165.      message:
  1166.  
  1167.              [END OF ANALYSIS]   Q to quit dSCAR, any other key for menu
  1168.  
  1169.      Pressing 'Q' or <ESC> at this point will exit dSCAR completely.  Any
  1170.      other key will return you to the main menu.
  1171.  
  1172.      ■ PRINTER -- 'P' key turns on, 'S', 'F', or 'O' turns off
  1173.  
  1174.      Hit the 'P' key if you want all output to be directed to the printer.
  1175.  
  1176.      When sending output to the printer, dSCAR will initially send the
  1177.      optional codes specified to set up the printer.  At the end of
  1178.      printing it will send the codes to reset the printer.  These printer
  1179.      codes are specified in the dSCAR configuration.
  1180.  
  1181.      There are several other printer options which are specified in the
  1182.      configuration.  These include the left margin, page length and width,
  1183.      the page heading, printer port to use, and whether or not a formfeed
  1184.      is sent after each module is printed.  See the chapter heading
  1185.      "CONFIGURING dSCAR" (page 28) for more information on these options.
  1186.  
  1187.      When Errors Only is toggled on and output is to the printer, each
  1188.      module processed is separated by dashes instead of a formfeed.
  1189.  
  1190.      Hitting <ESC> will pause printing and ask if you wish to abort.
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.                                    Page 18
  1197.  
  1198.  
  1199.  
  1200.      ■ FILE -- 'F' key turns on, 'S', 'P', or 'O' turns off
  1201.  
  1202.      Hit the 'F' key to send output to disk.
  1203.  
  1204.      Sending output to the disk is most useful when you want to pretty up
  1205.      your source code to make it more readable as you work on it.  To do
  1206.      this and still have runnable code, you must turn Diagramming and Line
  1207.      Numbers off.
  1208.  
  1209.      Output to disk is sent to the same filename of each module but with a
  1210.      new extension.  For example, the source code will be written to the
  1211.      same filename as the module being processed, but the extension will be
  1212.      '.FLO'.  The local cross-reference will go to the filename of the
  1213.      referenced module but with an extension of '.XRF'.  The global cross-
  1214.      reference will be written to the same filename as the top file, but
  1215.      with an extension of '.GBL'.  All of these extensions may be changed
  1216.      through the dSCAR configuration.
  1217.  
  1218.      For example, if you process the file HELP.PRG, the output file will be
  1219.      HELP.FLO.  If a local cross-reference is generated it will go to
  1220.      HELP.XRF.  If Modules and X-Reference is turned on, then the global
  1221.      cross-reference will be HELP.GBL if HELP.PRG is the top module.
  1222.  
  1223.      ■ OUTPUT PRINT-STYLE -- 'O' key turns on, 'S' 'P', or 'F' turns off
  1224.  
  1225.      Hit the 'O' key to send output to disk but in printing format.  This
  1226.      is necessary if you want to print the documentation later from the
  1227.      file, as all formfeeds, page headings, and margins will be left
  1228.      intact.
  1229.  
  1230.      When you select output to disk print-style, dSCAR will request a
  1231.      filename to send the output to.  If you enter a specific filename then
  1232.      all output will go to a single file--this includes source code, local
  1233.      cross-references, and the global cross-reference.
  1234.  
  1235.      If '*.*' is entered as the output file, then each module and cross-
  1236.      reference will go to a separate file, just like output to file
  1237.      operates.  For example, HELP.PRG will make two files:  HELP.FLO and
  1238.      HELP.XRF.  The difference between these files and those generated by
  1239.      output to file is that these will have printer codes inserted.
  1240.  
  1241.      ■ NON-STOP SCROLL -- 'N' key toggles on/off
  1242.  
  1243.      Non-stop Scroll will restrict dSCAR from pausing after a full page is
  1244.      displayed when output is to the screen.  You can still press the <ESC>
  1245.      key at any time to pause the output.
  1246.  
  1247.      ■ ANALYZE ANOTHER -- 'A' key prompts for a new file to process
  1248.  
  1249.      To get another file to process, hit the 'A' key.  This will ask for a
  1250.      new file to process.  Hitting <ESC> will abort the entry and return to
  1251.      the original file being processed.
  1252.  
  1253.  
  1254.  
  1255.  
  1256.                                    Page 19
  1257.  
  1258.  
  1259.  
  1260.      ■ INSTALL TEMPORARY -- 'I' key selects
  1261.  
  1262.      You can change many dSCAR options on-the-fly by Installing Temporary.
  1263.      Changes made here are for one session only.  Once dSCAR is terminated
  1264.      all temporary installation settings are lost.  If you wish to make a
  1265.      permanent change, use the dSCAR configuration.
  1266.  
  1267.      When you hit the 'I' key to Install Temporary, you are thrown into the
  1268.      installation window.  Using the up and down arrow keys go to the
  1269.      option you wish to change and enter the new value.  Pressing <ESC>
  1270.      will save the temporary settings and return to the selection window.
  1271.  
  1272.      For a detailed discussion of each setting, see the configuration
  1273.      instructions under the chapter heading "CONFIGURING dSCAR" (page 28).
  1274.  
  1275.      ■ SAVE DEFAULTS -- '!' prompts for file and saves defaults
  1276.  
  1277.      When dSCAR is initiated, the menu options have default settings.  For
  1278.      example, Diagramming and Comment Condition are turned on and output is
  1279.      to the screen.  You may find that you are continually using dSCAR with
  1280.      different settings, such as Modules and Line Numbering turned on,
  1281.      Diagramming off, and output to file.  You can make these settings the
  1282.      default with the Save Defaults command.
  1283.  
  1284.      To save your defaults, toggle all menu options to the desired state.
  1285.      When all the options are how you want them to permanently be, type
  1286.      '!'.  dSCAR will then prompt for the filename of dSCAR.  This is
  1287.      usually DSCAR.EXE, but if you renamed dSCAR then you must enter the
  1288.      new name.  The new menu defaults will be saved so that they are the
  1289.      defaults the next time dSCAR is loaded.
  1290.  
  1291.      Note that Save Defaults does NOT save the Temporary Installation
  1292.      settings.
  1293.  
  1294.      ■ QUIT -- 'Q' or <ESC> key
  1295.  
  1296.      To exit dSCAR, press 'Q' or hit <ESC>.
  1297.  
  1298.      ■ BEGIN PROCESSING -- <return> begins processing
  1299.  
  1300.      Hit <return> to start processing the selected module with the desired
  1301.      options.
  1302.  
  1303.      If output is to the printer and the printer is not ready or turned on,
  1304.      dSCAR will not begin processing.
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.                                    Page 20
  1317.  
  1318.  
  1319.  
  1320.      BATCH MODE
  1321.      ──────────────────────────────────────────────────────────────────────
  1322.  
  1323.      dSCAR can be operated completely from the command line, bypassing the
  1324.      menu screen.  Thus, you can write a batch file for dSCAR to have it
  1325.      process several systems at one time while you are away from the
  1326.      computer.
  1327.  
  1328.      The command line format for batch is:
  1329.  
  1330.              DSCAR <filename> {BCDEFLMOPSWXY}{=<procedure>/}
  1331.                                        {-begin line/}{+end line/}{(outfile)}
  1332.  
  1333.      <filename> is the name of the dBASE file to process.  Everything
  1334.      between the curly braces ({}) are optional, except that there must be
  1335.      at least one parameter after <filename> to send dSCAR into batch mode.
  1336.      Spaces should not separate the parameters after <filename>.
  1337.  
  1338.      To invoke dSCAR in batch mode with the default settings, use this
  1339.      format:
  1340.  
  1341.              DSCAR <filename> B
  1342.  
  1343.      The above command line tells dSCAR to process <filename> in batch mode
  1344.      ('B' indicates batch).  When in batch mode dSCAR will not pause after
  1345.      displaying a page, nor will it return to the menu screen, but instead
  1346.      exit back to DOS.
  1347.  
  1348.      You can also set processing options from the command line.  Do this by
  1349.      including on the command line the selection key for the menu option
  1350.      you wish to toggle from its default state.  For example, if you wish
  1351.      to toggle Diagramming off (on is the default) and send output to a
  1352.      file instead of the screen, use this command line:
  1353.  
  1354.              DSCAR <filename> DF
  1355.  
  1356.      Notice that the 'B' is not needed.  'B' is only needed if you are not
  1357.      toggling any options but wish to use the defaults.  However, including
  1358.      the 'B' parameter at other times will not hurt.
  1359.  
  1360.      There are two things you must remember when operating in batch mode:
  1361.      the selection keys for the menu options and the default menu settings.
  1362.      For example, the 'D' key turns Diagramming off and on, and Diagramming
  1363.      on is the default.
  1364.  
  1365.      Several options are not supported from batch mode, for obvious
  1366.      reasons.  These include Non-stop Scroll, Analyze Another, Install
  1367.      Temporary, and Save Defaults.
  1368.  
  1369.      Specifying a procedure/function or beginning and ending line numbers
  1370.      to process requires a special format.  For a procedure or function,
  1371.      include the name of the procedure/function between an equal sign (=)
  1372.  
  1373.  
  1374.  
  1375.  
  1376.                                    Page 21
  1377.  
  1378.  
  1379.  
  1380.      and a slash (/).  For example, the following command will process the
  1381.      procedure HELP with diagramming turned off:
  1382.  
  1383.              DSCAR <filename> D=HELP/
  1384.  
  1385.      To specify the low range of line numbers to process, include the
  1386.      beginning line number between a minus sign (-) and a slash (/).  This
  1387.      command line will process <filename> beginning at line 113:
  1388.  
  1389.              DSCAR <filename> -113/
  1390.  
  1391.      The high range line number is included between a plus sign (+) and a
  1392.      slash (/), like this:
  1393.  
  1394.              DSCAR <filename> +200/
  1395.  
  1396.      Suppose you wanted to process from line 110 to line 150.  To do this
  1397.      you would enter:
  1398.  
  1399.              DSCAR <filename> +150/-110/
  1400.  
  1401.      Notice that the order of the parameters makes no difference.
  1402.  
  1403.      You can also specify an output file on the command line.  Do this by
  1404.      including the output filename between parenthesis.  For example, to
  1405.      send output print-style (option 'O') to the file PRINT.XYZ, use this
  1406.      command line:
  1407.  
  1408.              DSCAR <filename> O(PRINT.XYZ)
  1409.  
  1410.      You will have to experiment with the batch mode in order to get the
  1411.      hang of it.  Here are a few more examples, as examples illustrate best
  1412.      in this case:
  1413.  
  1414.              DSCAR <filename> DMXL     (Diagramming off, Modules on,
  1415.                                         X-ref on, Numbering on)
  1416.  
  1417.              DSCAR <filename> D+100/L  (Diagramming off, end at line 100,
  1418.                                         Numbering on)
  1419.  
  1420.              DSCAR <filename> E=WRITE/ (Errors Only on, procedure WRITE)
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.                                    Page 22
  1437.  
  1438.  
  1439.  
  1440.      MODULES PROCESSING QUEUE
  1441.      ──────────────────────────────────────────────────────────────────────
  1442.  
  1443.      Even with Modules turned on dSCAR will not always process every module
  1444.      in your system.  The usual reason for this is macros.  For example,
  1445.      you may have some code which looks like this:
  1446.  
  1447.        ┌─MODULES & MACROS───────────────────────────────────────────┐
  1448.        │                                                            │
  1449.        │ IF Option = 1                                              │
  1450.        │    Do_file = 'MENU_1'                                      │
  1451.        │ ELSE                                                       │
  1452.        │    Do_file = 'MENU_2'                                      │
  1453.        │ ENDIF                                                      │
  1454.        │ DO &Do_file                                                │
  1455.        └────────────────────────────────────────────────────────────┘
  1456.  
  1457.      dSCAR has no way of knowing that 'Do_file' is not the name of a file
  1458.      and that MENU_1 and MENU_2 are files.  To process these modules as
  1459.      part of a system you can add them to a MODULES file.  When dSCAR is
  1460.      executed with Modules turned on, it looks for the existence of MODULES
  1461.      and reads the filenames contained in it into the processing queue.
  1462.  
  1463.      MODULES is a straight ascii file.  The filenames in it are separated
  1464.      by a carriage return/linefeed pair.  Thus, for the above example,
  1465.      MODULES would looks like this:
  1466.  
  1467.        ┌─SAMPLES MODULES FILE───────────────────────────────────────┐
  1468.        │                                                            │
  1469.        │ MENU_1.PRG                                                 │
  1470.        │ MENU_2.PRG                                                 │
  1471.        └────────────────────────────────────────────────────────────┘
  1472.  
  1473.      The filenames need not be in any particular order.  Be sure to delete
  1474.      the MODULES file when you are done with it or the modules contained in
  1475.      it may be processed for systems they are not needed for.
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.  
  1492.  
  1493.  
  1494.  
  1495.  
  1496.                                    Page 23
  1497.  
  1498.  
  1499.  
  1500.      CODING ERRORS dSCAR REPORTS
  1501.      ──────────────────────────────────────────────────────────────────────
  1502.  
  1503.      The following is a list and explanation of the structural errors
  1504.      commonly found in source code which dSCAR reports.
  1505.  
  1506.      ■ Open IF from line #### -- if there is an IF statement without a
  1507.        matching ENDIF dSCAR attempts to track down which IF statement was
  1508.        left open.
  1509.      ■ Open WHILE from line #### -- DO WHILE has no terminating ENDDO
  1510.      ■ Open CASE from line #### -- DO CASE has no terminating ENDCASE
  1511.      ■ Open TEXT from line #### -- TEXT has no terminating ENDTEXT
  1512.      ■ Open FOR from line #### -- FOR has no terminating NEXT
  1513.      ■ Open SCAN from line #### -- SCAN has no terminating ENDSCAN
  1514.      ■ Open PRINT from line #### -- PRINT has no terminating END PRINTJOB
  1515.      ■ ENDIF without IF or ELSE -- an ENDIF has no matching IF or ELSE
  1516.        statement
  1517.      ■ ELSE without IF -- an ELSE statement was found with no matching IF
  1518.        statement
  1519.      ■ ENDDO without DO WHILE -- ENDDO has no matching DO WHILE
  1520.      ■ ENDCASE without DO CASE -- ENDCASE has no matching DO CASE
  1521.      ■ ENDSCAN without SCAN -- ENDSCAN has no matching SCAN
  1522.      ■ END PRINT without PRINT -- END PRINTJOB has no matching PRINT
  1523.      ■ NEXT without FOR -- NEXT has no matching FOR
  1524.      ■ ENDCASE without DO CASE -- ENDCASE has no matching DO CASE
  1525.      ■ Unexpected ENDTEXT -- ENDTEXT has no matching TEXT
  1526.      ■ Missing DO CASE statement -- a CASE or OTHERWISE statement is
  1527.        missing the DO CASE
  1528.      ■ Empty DO CASE -- DO CASE is immediately followed by ENDCASE with no
  1529.        CASE
  1530.      ■ DO CASE not followed by CASE -- a CASE should immediately follow a
  1531.        DO CASE
  1532.      ■ Follows LOOP never executed -- the only valid code to immediately
  1533.        follow a LOOP is ELSE, ENDIF, CASE, OTHERWISE, or ENDCASE
  1534.      ■ Follows EXIT never executed -- the only valid code to immediately
  1535.        follow an EXIT is ELSE, ENDIF, CASE, OTHERWISE, or ENDCASE
  1536.      ■ After RETURN never executed -- code after a RETURN is ignored unless
  1537.        the code is a procedure, an ELSE, ENDIF, CASE, OTHERWISE, or ENDCASE
  1538.      ■ Warning:At most 1 iteration -- a SCAN and DO WHILE will only
  1539.        iterate once if a LOOP, EXIT, or RETURN is nested one level beneath
  1540.        the SCAN or DO WHILE
  1541.      ■ Redundant LOOP statement -- a LOOP nested one level beneath a DO
  1542.        WHILE will cause the DO WHILE to be executed over and over again.
  1543.        Make sure a LOOP is embedded in a conditional structure such as
  1544.        IF...ENDIF.
  1545.      ■ Not within a DO WHILE -- an EXIT must be within a DO WHILE or LOOP
  1546.        structure, and a LOOP must be within a DO WHILE structure
  1547.      ■ SET PROC not followed by TO
  1548.      ■ SET FORM not followed by TO
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.                                    Page 24
  1557.  
  1558.  
  1559.  
  1560.      ADDING RESERVED WORDS
  1561.      ──────────────────────────────────────────────────────────────────────
  1562.  
  1563.      Most dBASE compilers and dBASE-compatible interpreters have additional
  1564.      commands and reserved words not supported by dBASE itself.  dSCAR has
  1565.      internal built-in support for dBASE.  However, if you are using a
  1566.      compiler such as Clipper or interpreter such as FoxBase, dSCAR
  1567.      supports their language extensions through external files.
  1568.  
  1569.      The file RESERVED (no extension) contains extra reserved words.  The
  1570.      words contained in this file will not be added to any cross-
  1571.      references.  RESERVED contains reserved words which are found within a
  1572.      line.  Examples include ALL, TO, WHILE, and STATUS.  You do not need
  1573.      to add commands (those words which appear first on a line), as dSCAR
  1574.      will always recognize a command when it sees one.  Therefore, command
  1575.      words should not be added to the RESERVED list.  Examples of commands
  1576.      include DO, SET, CREATE, and RETURN.
  1577.  
  1578.      Included in the distribution of dSCAR are two batch files:
  1579.      USE_FOX.BAT and USE_CLIP.BAT.  If you are using FoxBase then run the
  1580.      batch file USE_FOX.  This will create the necessary RESERVED file for
  1581.      use with FoxBase.  Executing the USE_CLIP batch file will do the same
  1582.      for Clipper.
  1583.  
  1584.      You can modify or create your own RESERVED file using a text editor.
  1585.      The file is straight ascii.  Each word is on a single line separated
  1586.      by a carriage return/linefeed pair.  The words do not have to be in
  1587.      any particular order.
  1588.  
  1589.      RESERVED must reside in the current directory.  If you use both
  1590.      Clipper and FoxBase or any other dBASE-compatible product, you can put
  1591.      different RESERVED lists in different directories.  Thus, when you are
  1592.      processing Clipper code, dSCAR will use the appropriate reserved words
  1593.      if you are in the Clipper directory.  dSCAR will use the FoxBase set
  1594.      of words when in the FoxBase directory.
  1595.  
  1596.      dSCAR automatically detects if the RESERVED file is present and turns
  1597.      Your Reserved on as needed.
  1598.  
  1599.  
  1600.  
  1601.  
  1602.  
  1603.  
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.                                    Page 25
  1617.  
  1618.  
  1619.  
  1620.      dSCAR's reserved word list includes all of those found in dBASE IV.
  1621.      If you are unsure whether or not dSCAR supports a reserved word which
  1622.      is found in your dBASE compiler or interpreter, check the following
  1623.      list of dSCAR's internal reserved words:
  1624.  
  1625.      &                 FIELDS             NOAPPEND           SAVE
  1626.      ADDITIVE          FILE               NOEJECT            SAY
  1627.      ALIAS             FILL               NOFOLLOW           SCREEN
  1628.      ALL               FILTER             NOMENU             SDF
  1629.      ALTERNATE         FOR                NOT                SECONDARY
  1630.      AND               FORM               NOUPDATE           SELECTION
  1631.      APPLICATION       FORMAT             OFF                STATUS
  1632.      ARRAY             FREEZE             ON                 STRUCTURE
  1633.      ASCENDING         FROM               OR                 SUMMARY
  1634.      BEFORE            FUNCTION           OTHERWISE          T
  1635.      BLANK             GET                PAD                TAG
  1636.      BOTTOM            GETS               PAGE               TO
  1637.      CASE              HEADING            PFS                TOP
  1638.      CLEAR             HISTORY            PICTURE            TRANSACTION
  1639.      COLOR             INDEXES            PLAIN              TYPE
  1640.      DATABASES         INTO               POPUPS             TYPEAHEAD
  1641.      DECIMALS          KEY                PRIMARY            UNIQUE
  1642.      DEFAULT           LABEL              PRINT              USERS
  1643.      DELIMITED         LIKE               PROCEDURE          USING
  1644.      DELIMITER         LOCK               QUERY              VIEW
  1645.      DESCENDING        MACROS             RANDOM             WAIT
  1646.      DO                MARGIN             RANGE              WHILE
  1647.      DOUBLE            MASTER             READERROR          WIDTH
  1648.      ERROR             MEMO               RECORD             WINDOWS
  1649.      ESCAPE            MEMORY             RELATION           WITH
  1650.      EXCEPT            MENUS              REPORT
  1651.      EXTENDED          MODULE             REST
  1652.      ENVIRONMENT       NEXT               SAMPLE
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.  
  1674.  
  1675.  
  1676.                                    Page 26
  1677.  
  1678.  
  1679.  
  1680.      OTHER FEATURES & TIPS
  1681.      ──────────────────────────────────────────────────────────────────────
  1682.  
  1683.      ■ Table of Contents
  1684.  
  1685.      dSCAR will create a table of contents for your completed documentation
  1686.      if Modules is toggled on and output is to the printer or print-style
  1687.      to disk.
  1688.  
  1689.      The table of contents tells on which page numbers modules and cross-
  1690.      references are found.
  1691.  
  1692.      ■ Can dSCAR indent my source code properly and still retain a runnable
  1693.        file (without diagramming and line numbers and such)?
  1694.  
  1695.      The answer is yes.  To do this for a single file, turn all options off
  1696.      and select file output.  dSCAR will generate a file with no
  1697.      diagramming but still indent your code.  Error messages are written as
  1698.      comments, thereby not interfering with any interpreter your code is
  1699.      being run through.  To do this for a whole system do the same thing
  1700.      but toggle Modules on.
  1701.  
  1702.      ■ Setting Margins on Printer
  1703.  
  1704.      There is a fairly easy way to have dSCAR leave top and bottom margins
  1705.      on your printouts.  For a top margin, include in your macro heading
  1706.      several blank lines.  For a bottom margin, set your page length to
  1707.      less than it actually is.  For example, if your page length is 66
  1708.      lines, set it to 60--dSCAR will go to the next page at line 60 and
  1709.      leave a bottom margin of six lines.
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.                                    Page 27
  1737.  
  1738.  
  1739.  
  1740.      CONFIGURING dSCAR
  1741.      ──────────────────────────────────────────────────────────────────────
  1742.  
  1743.      The configuration part of dSCAR is built into the main program.  There
  1744.      are no separate configuration files, as the main DSCAR.EXE file will
  1745.      be modified to use your new settings as defaults.  The following areas
  1746.      can be modified through configuration:
  1747.  
  1748.      ■ MISCELLANEOUS -- This includes defaults for indentation, file
  1749.        extensions, screen width, printer width and length, printer
  1750.        port, and output headings, to name a few.
  1751.  
  1752.      ■ COLOR -- The different color settings of dSCAR may be modified
  1753.        to suit your monitor and preference.  The default settings are set
  1754.        so as to run on a variety of monitors.  If you have a color monitor
  1755.        you may opt to use more variety of colors to make the menu and
  1756.        processing screens more appealing.
  1757.  
  1758.      ■ PRINTER SETUP AND RESET -- Define command codes to send to your
  1759.        printer to put it in different modes before and after printing.
  1760.  
  1761.      To run the configuration program, log into the same directory
  1762.      containing DSCAR.EXE and at the DOS prompt type:
  1763.  
  1764.              DSCAR C  <return>
  1765.  
  1766.      The 'C' parameter tells dSCAR to run the configuration.
  1767.  
  1768.      Because dSCAR is self-modifying, it needs to know the name and
  1769.      directory under which to find itself.  dSCAR will first ask for the
  1770.      .EXE file to modify, including path name.  This defaults to DSCAR.EXE
  1771.      in the current directory.  However, if dSCAR is not in the current
  1772.      directory or was re-named, you need to answer the question:
  1773.  
  1774.           Name of file to modify (include path):
  1775.  
  1776.      If the file specified is not found in the current directory or
  1777.      directory specified, then dSCAR will tell you so and let you enter it
  1778.      again.  If you wish to abort the configuration process at this point,
  1779.      hit <ESC>.  If the file to modify is found, then a configuration menu
  1780.      is presented with these five options:
  1781.  
  1782.           1 - Configure Miscellaneous settings
  1783.           2 - Install colors
  1784.           3 - Change printer set-up sequence
  1785.           4 - Change printer reset sequence
  1786.           5 - Quit & Save
  1787.           0 - Quit with No Save
  1788.  
  1789.      At this point select the configuration option you wish to modify.  The
  1790.      different configurable features of each section are outlined below.
  1791.      The cursor keys are functional while changing configuration options.
  1792.  
  1793.  
  1794.  
  1795.  
  1796.                                    Page 28
  1797.  
  1798.  
  1799.  
  1800.      MISCELLANEOUS SETTINGS
  1801.  
  1802.      ■ Upper, Lower, Proper, Significant, or No change reserved words
  1803.  
  1804.        If Word Fix-Up is selected, dSCAR can change the case of reserved
  1805.        words.  Select here the case you wish reserved words to have.
  1806.        Below are samples of each type of case:
  1807.  
  1808.        UPPER: All reserved words are capitalized.
  1809.               ie DO WHILE, ENDDO, SET TALK, RESTORE
  1810.  
  1811.        LOWER: Reserved words are put in lower case
  1812.               ie do while, enddo, set talk, restore
  1813.  
  1814.        PROPER: The first letter of each word is capitalized
  1815.               ie Do While, Enddo, Set Talk, Restore
  1816.  
  1817.        SIGNIFICANT: Only the first four letters are capitalized
  1818.               ie DO WHILe, ENDDo, SET TALK, RESTore
  1819.  
  1820.        NO CHANGE: Leave reserved words as they are found in the code
  1821.  
  1822.      ■ Upper, Lower, Proper, Significant, or No change variables
  1823.  
  1824.        This is the same as above, but specifies what action to take on
  1825.        variables. Thus, you may want to capitalize reserved words and
  1826.        lowercase variables to make your code more readable.
  1827.  
  1828.      ■ Number of spaces to use for indentation
  1829.  
  1830.        This is the indentation increment dSCAR uses when formatting
  1831.        your code to look "pretty."  Shown below are two pieces of the
  1832.        same  code,  the first with an indentation of three and the
  1833.        second with an indentation of five:
  1834.  
  1835.        ┌─INDENT OF THREE────────────────────────────────────────────┐
  1836.        │ do while count < 100                                       │
  1837.        │    if count = 50 then                                      │
  1838.        │       ? 'Halfway there!'                                   │
  1839.        │    endif                                                   │
  1840.        │    x = x + 1                                               │
  1841.        │ enddo                                                      │
  1842.        └────────────────────────────────────────────────────────────┘
  1843.  
  1844.        ┌─INDENT OF FIVE─────────────────────────────────────────────┐
  1845.        │ do while count < 100                                       │
  1846.        │      if count = 50 then                                    │
  1847.        │           ? 'Halfway there!'                               │
  1848.        │      endif                                                 │
  1849.        │      x = x + 1                                             │
  1850.        │ enddo                                                      │
  1851.        └────────────────────────────────────────────────────────────┘
  1852.  
  1853.  
  1854.  
  1855.  
  1856.                                    Page 29
  1857.  
  1858.  
  1859.  
  1860.      ■ Graphic or Text flow screen diagrams
  1861.  
  1862.        Valid options here are 'G' and 'T'.  Graphic diagrams use the
  1863.        IBM extended character set.  If your printer does not support
  1864.        these graphic characters then you may wish to turn graphics off.
  1865.        Text diagrams are better for documentation, although graphics are
  1866.        more appealing.  Here are two examples of the different flow
  1867.        diagrams:
  1868.  
  1869.        ┌─GRAPHIC FLOW DIAGRAMS──────────────────────────────────────┐
  1870.        │                                                            │
  1871.        │ ╓DO WHILE .T.                                              │
  1872.        │ ║    ACCEPT 'What is your name?' TO Myname                 │
  1873.        │ ║   ┌IF UPPER(Myname) <> 'JOE'                             │
  1874.        │ ║   │    ? 'Only Joe is allowed access!'                   │
  1875.        │ ────────RETURN                                            │
  1876.        │ ║   ├ELSE                                                  │
  1877.        │ ║   │    ? 'Hello Joe'                                     │
  1878.        │ ║   │   ╒DO CASE                                           │
  1879.        │ ║   │   ╞CASE Myname = 'JOE'                               │
  1880.        │ ║   │   │    ? 'You typed in uppercase'                    │
  1881.        │ ║   │   ╞CASE Myname = 'joe'                               │
  1882.        │ ║   │   │    ? 'You typed in lowercase'                    │
  1883.        │ ────────────RETURN                                        │
  1884.        │ ║   │   ╘ENDCASE                                           │
  1885.        │ ║   └ENDIF                                                 │
  1886.        │ ╙ENDDO                                                     │
  1887.        └────────────────────────────────────────────────────────────┘
  1888.  
  1889.        ┌─TEXT FLOW DIAGRAMS─────────────────────────────────────────┐
  1890.        │                                                            │
  1891.        │ DO WHILE .T.                                               │
  1892.        │ W    ACCEPT 'What is your name?' TO Myname                 │
  1893.        │ W    IF UPPER(Myname) <> 'JOE'                             │
  1894.        │ W   T    ? 'Only Joe is allowed access!'                   │
  1895.        │ <--------RETURN                                            │
  1896.        │ W    ELSE                                                  │
  1897.        │ W   F    ? 'Hello Joe'                                     │
  1898.        │ W   F    DO CASE                                           │
  1899.        │ W   F    CASE Myname = 'JOE'                               │
  1900.        │ W   F   1    ? 'You typed in uppercase'                    │
  1901.        │ W   F    CASE Myname = 'joe'                               │
  1902.        │ W   F   2    ? 'You typed in lowercase'                    │
  1903.        │ <------------RETURN                                        │
  1904.        │ W   F    ENDCASE                                           │
  1905.        │ W    ENDIF                                                 │
  1906.        │ ENDDO                                                      │
  1907.        └────────────────────────────────────────────────────────────┘
  1908.  
  1909.      ■ Truncate lines longer than specified width
  1910.  
  1911.        If a processed line is longer than the specified width (ie 80
  1912.  
  1913.  
  1914.  
  1915.  
  1916.                                    Page 30
  1917.  
  1918.  
  1919.  
  1920.        for the screen, usually) then dSCAR can either break it up
  1921.        using the dBASE continuation character (semicolon), or truncate
  1922.        the line.  It is sometimes useful to truncate lines when
  1923.        output is to the screen for flow diagrams, as the output is
  1924.        easier to read.  However, for printer and file outputs lines
  1925.        should not be truncated.  It is recommended you set this to
  1926.        'N', as you can set Truncate on temporarily from the dSCAR menu.
  1927.  
  1928.      ■ Use new line number for continuation lines
  1929.  
  1930.        If line numbering is turned on and dSCAR must break up a line,
  1931.        then the line numbering can take one of two formats.  If this
  1932.        option is set to 'N' then the continuation line will have the
  1933.        same line number as the first line of the entire command.
  1934.        However, if it is set to 'Y' then each continuation line will
  1935.        have its own line number.  Examples follow:
  1936.  
  1937.        ┌─SAME LINE NUMBER FOR CONTINUATION LINES────────────────────┐
  1938.        │                                                            │
  1939.        │ 1  SELECT a                                                │
  1940.        │ 2  RELEASE m0addrf,m0arecf,m0cashf,m0commf,m0custf,;       │
  1941.        │ 2   m0glacf,m0glanf,m0gllkf,m0invof,m0invtf,m0itrnf,;      │
  1942.        │ 2   m0passf,m0recrf,m0scomf,m0tranf,m0ycshf                │
  1943.        │ 3  PUBLIC m0addrf,m0arecf,m0cashf,m0commf,m0custf,m0glacf  │
  1944.        │ 4  USE &m0sysdr.sysdata                                    │
  1945.        └────────────────────────────────────────────────────────────┘
  1946.  
  1947.        ┌─NEW LINE NUMBER FOR CONTINUATION LINES─────────────────────┐
  1948.        │                                                            │
  1949.        │ 1  SELECT a                                                │
  1950.        │ 2  RELEASE m0addrf,m0arecf,m0cashf,m0commf,m0custf,;       │
  1951.        │ 3   m0glacf,m0glanf,m0gllkf,m0invof,m0invtf,m0itrnf,;      │
  1952.        │ 4   m0passf,m0recrf,m0scomf,m0tranf,m0ycshf                │
  1953.        │ 5  PUBLIC m0addrf,m0arecf,m0cashf,m0commf,m0custf,m0glacf  │
  1954.        │ 6  USE &m0sysdr.sysdata                                    │
  1955.        └────────────────────────────────────────────────────────────┘
  1956.  
  1957.        The second method is handy if you need to reference specific line
  1958.        numbers of a file from within an editor, but the first method is
  1959.        preferred for cross-references.
  1960.  
  1961.      ■ Are you using Clipper?
  1962.  
  1963.      If you are processing mainly Clipper files then answer 'Y' to this
  1964.      question.  Clipper does not support comments which span more than one
  1965.      line using the continuation character (;).  Therefore, if output is to
  1966.      a file and you are using Clipper, dSCAR will not use continuation
  1967.      characters in the code unless it has to, thereby allowing your Clipper
  1968.      code to be runnable after being processed by dSCAR.
  1969.  
  1970.      If you find that another compiler or dBASE-compatible interpreter has
  1971.      this same problem, then you can answer 'Y' to this question.
  1972.  
  1973.  
  1974.  
  1975.  
  1976.                                    Page 31
  1977.  
  1978.  
  1979.  
  1980.      ■ Default extension for dBASE program files
  1981.  
  1982.        dSCAR assumes program files to have an extension of .PRG.
  1983.        However, if you are using a different naming convention you can
  1984.        specify that extension here.
  1985.  
  1986.      ■ Default extension for dSCAR program files
  1987.  
  1988.        When dSCAR sends the output of program and format files to disk,
  1989.        it uses the same filename as the original file, but with a
  1990.        different extension.  This extension defaults to .FLO, but can be
  1991.        changed here.
  1992.  
  1993.      ■ Default extension for dSCAR cross-references files
  1994.  
  1995.        Cross-reference outputs will have the same filename as the module
  1996.        being processed, but with a new extension.  This extension defaults
  1997.        to .XRF, but can be specified differently.
  1998.  
  1999.      ■ Default extension for dSCAR printer files
  2000.  
  2001.        If output is to a file printer-style, then dSCAR writes to a file
  2002.        with the same filename and new extension.  This extension defaults
  2003.        to .PRN, but can be changed.
  2004.  
  2005.      ■ Strip drive and path from filenames
  2006.  
  2007.        Respond with 'Y' if you want to strip drive and pathnames from files
  2008.        encountered in processing.  If they are not stripped, dSCAR will
  2009.        look in the paths specified.  Regardless of what this option is set
  2010.        to, dSCAR always recognizes and uses any path prefixed to the main
  2011.        file you enter at start-up.  This option is especially important
  2012.        when the Modules option is turned on.
  2013.  
  2014.      ■ Number of lines to display per output screen
  2015.  
  2016.        This should be defaulted to stop and wait for a keypress when one
  2017.        full page has been displayed.  But, if you happen to want to display
  2018.        only ten lines before stopping, or perhaps two pages, you can change
  2019.        it with this option.
  2020.  
  2021.      ■ Number of columns across output screen
  2022.  
  2023.        This determines where to break a long line at.  If want to break
  2024.        lines at 40 characters, then specify 40.  Or if you happen to have a
  2025.        wide display then you can increase the number of columns.  The
  2026.        default is 80.
  2027.  
  2028.      ■ Number of lines per page on your printer
  2029.  
  2030.        The printer length tells dSCAR how many lines are on the paper so
  2031.        that it can issue a formfeed at the proper time to skip over the
  2032.  
  2033.  
  2034.  
  2035.  
  2036.                                    Page 32
  2037.  
  2038.  
  2039.  
  2040.        perforation.  The default should  work for paper that is the
  2041.        standard 11 inches long.  You may have to experiment with this
  2042.        setting if you are using a laser printer.
  2043.  
  2044.      ■ Column width of your printer
  2045.  
  2046.        This is the number of printable characters across each printer page.
  2047.        The default value of 80 should work with most printers.  However,
  2048.        you will have to change this if you are using a wide carriage
  2049.        printer so that dSCAR will print all the way across the page.  If
  2050.        you set your printer to condensed mode you may have to change this
  2051.        value.
  2052.  
  2053.      ■ Left margin for printer output
  2054.  
  2055.        Specify this value in number of spaces to indent.  For example,
  2056.        enter 5 to indent five spaces before printing each line, or 0 for
  2057.        no left margin.  Margins are especially useful if you plan on
  2058.        hole-punching your reports.
  2059.  
  2060.      ■ Number of characters per line for file output
  2061.  
  2062.        This is basically the same as the screen width, but instead
  2063.        indicates when to break a long line when output is to a file.
  2064.        Some people may want to display a screen width, but others may
  2065.        want to go as far as 255 characters.
  2066.  
  2067.      ■ Default printer port
  2068.  
  2069.        dSCAR supports printer ports 1, 2, and 3.  dSCAR will send printer
  2070.        output to the port specified.
  2071.  
  2072.      ■ Issue a formfeed after each module
  2073.  
  2074.        If you wish each module and every cross-reference to appear on its
  2075.        own page when output is to printer, then have dSCAR send a form feed
  2076.        after each module.  However, answer NO if you wish to save paper and
  2077.        not start each module on a separate page.
  2078.  
  2079.      ■ Report heading for printer reports
  2080.  
  2081.        On the top of each printer page, dSCAR can optionally print a
  2082.        header containing such information as module name, dSCAR version,
  2083.        current date, page number, and more.  This header is user-definable,
  2084.        and can contain straight text or macro commands.  Macro commands
  2085.        will print dynamic information such as page number, module being
  2086.        processed, date, and dSCAR version number.  Straight text can
  2087.        contain a copyright notice, your company name, or anything else
  2088.        you desire.
  2089.  
  2090.        The header is entered in a three-line format.  If you run out of
  2091.        room for the header text and macros, hit <return> to get to the next
  2092.  
  2093.  
  2094.  
  2095.  
  2096.                                    Page 32
  2097.  
  2098.  
  2099.  
  2100.        line and continue entering the header.  Each of the three lines is
  2101.        strung together and treated as one long heading line.  Note that
  2102.        each line of entry does NOT represent one line on the printer.
  2103.  
  2104.        Macro commands are one uppercase character and are preceded by the
  2105.        ampersand character (&), except for the new line macro which is a
  2106.        single back slash (\).  Macro values are printed exactly where they
  2107.        are found in the header line configuration.  Below is a list of the
  2108.        macro commands available:
  2109.  
  2110.             Macro  Meaning      Picture
  2111.             ---------------------------------
  2112.             &P     page number   9999
  2113.             &D     date          Mon DD, year
  2114.             &T     time          99:99am
  2115.             &V     version       9.99 BETA
  2116.             &S     system name
  2117.             &M     current module
  2118.             &F     path+module
  2119.             &=     procedure being displayed if specific procedure selected
  2120.             &&     print the ampersand character (&)
  2121.             \      newline  (use as many lines as you want in the heading)
  2122.  
  2123.        Remember that macro characters MUST BE IN UPPERCASE!
  2124.        Here are some example macro headings and how they would print:
  2125.  
  2126.        ----------------
  2127.        MACRO: dSCAR v&V                          &D  &T\SYSTEM: &S
  2128.  
  2129.        dSCAR v3.0                          Dec 29, 1988  10:41pm
  2130.        SYSTEM: LIBRARY
  2131.        ----------------
  2132.        MACRO: Copyright (c) 1989 by John Smith.\\&M\&F\Page &P\
  2133.  
  2134.        Copyright (c) 1989 by John Smith.
  2135.  
  2136.        ADDBOOK.PRG
  2137.        \DBASE\LIBRARY\ADDBOOK.PRG
  2138.        Page 10
  2139.        ----------------
  2140.  
  2141.        The second example shows how to use the new line character (\).
  2142.        A newline can be placed anywhere, and doubling new line characters
  2143.        will add a blank line.  By putting several new line characters at
  2144.        the end of a macro heading you can effectively space between the
  2145.        header and the body of your report.
  2146.  
  2147.  
  2148.      INSTALL COLORS
  2149.  
  2150.      The colors dSCAR uses for its menus and output display can be
  2151.      configured to your preference.  When color installation is selected,
  2152.  
  2153.  
  2154.  
  2155.  
  2156.                                    Page 33
  2157.  
  2158.  
  2159.  
  2160.      the available colors are drawn across the screen with the letters A-P
  2161.      denoting each color.
  2162.  
  2163.      There are nine different color objects.  For each object specify a
  2164.      foreground and background color by selecting the letter representing
  2165.      the desired color.  Note that only colors A-H are available for
  2166.      background colors!
  2167.  
  2168.      Below is a description of each color item:
  2169.  
  2170.      ■ Source line -- this is the color for the display of your source code
  2171.  
  2172.      ■ Line numbers -- if line numbers is turned on, the line numbers will
  2173.        be in this color
  2174.  
  2175.      ■ Error Messages -- any error messages, in processing or on the menu
  2176.        screen, will show up as this color
  2177.  
  2178.      ■ Diagramming -- if diagramming is turned on, the screen diagrams will
  2179.        be highlighted in this color
  2180.  
  2181.      ■ Footer message -- this is the message at the bottom of the
  2182.        processing screen indicating the current module being processed
  2183.  
  2184.      ■ Selected options -- selected options on the menu screen will be
  2185.        indicated by highlighting in this color
  2186.  
  2187.      ■ Un-selected options -- menu options which are turned off
  2188.        (unselected) will be displayed in this color
  2189.  
  2190.      ■ Window color -- this is the color for the window border on the menu
  2191.        screen
  2192.  
  2193.      ■ Window titles -- the titles above menu options and title headings of
  2194.        the different windows will show up in this color
  2195.  
  2196.      The best way to configure the color is to select some appealing
  2197.      colors, run dSCAR, and then try again if the colors did not turn out
  2198.      how you like them.
  2199.  
  2200.      Keep in mind that the main background color within a window and on the
  2201.      processing screen will ALWAYS be black.
  2202.  
  2203.  
  2204.      PRINTER SETUP AND RESET
  2205.  
  2206.      dSCAR can automatically send setup codes to your printer when output
  2207.      to printer is selected.  This is useful if you want your printer to go
  2208.      into condensed mode, be reset, or have the page length reset before
  2209.      any reports are printed.
  2210.  
  2211.      In addition, dSCAR can optionally send codes after it is done
  2212.  
  2213.  
  2214.  
  2215.  
  2216.                                    Page 34
  2217.  
  2218.  
  2219.  
  2220.      printing, perhaps to reset the printer to its original settings.
  2221.  
  2222.      To enter setup codes, select option 3 from the configuration menu.
  2223.      Option 4 allows you to enter reset codes.
  2224.  
  2225.      Upon entering either printer setup or reset, you are prompted to enter
  2226.      print code #1.  A print code is a single character--whether it be a
  2227.      control character or alphanumeric character--which will be sent to the
  2228.      printer.  For example, the ESCape code and the letter 'A' both
  2229.      represent single print codes.   Up to 40 print codes may be sent for
  2230.      the setup sequence, and an additional 40 for the reset sequence.
  2231.  
  2232.      To enter an alphanumeric print code, just hit the key on the keyboard.
  2233.      For example, to send the letter 'A' to the printer, hit the 'A' key.
  2234.      To send the '@' symbol, hit that key on the keyboard.
  2235.  
  2236.      Control codes are entered by typing the '#' key (pound sign).  A '#'
  2237.      tells dSCAR that the next characters are ascii codes.  For example, to
  2238.      enter ESCape as a print code, type '#' and then type in '27' (followed
  2239.      by the <return> key).  To enter the '#' key as a print code, type '#'
  2240.      and then '35', as 35 is the ascii code for the pound character.
  2241.  
  2242.      When you are all done entering print codes, press the <ESC> key
  2243.      (remember, to have the ESCape character be a print code, you must
  2244.      enter the ascii code for it).
  2245.  
  2246.      Option 5 from the configuration menu will save your new settings to
  2247.      the executable dSCAR file and then exit configuration.  If you do not
  2248.      want to save the changes made, then select option 0 to exit without
  2249.      writing the configuration.
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.  
  2272.  
  2273.  
  2274.  
  2275.  
  2276.                                    Page 35
  2277.  
  2278.  
  2279.  
  2280.      ABOUT THE AUTHOR & THE PROGRAM
  2281.      ──────────────────────────────────────────────────────────────────────
  2282.  
  2283.      The first version of dSCAR was released in 1986 as user supported
  2284.      software.  Version 1.0 was followed by 2.0 and then 2.3a.  Version 3.0
  2285.      is almost twice as fast as version 2.3 and has a multitude of
  2286.      additional features.
  2287.  
  2288.      In 1988 I was contacted by a large software publishing firm interested
  2289.      in buying dSCAR.  I turned down their offer with the idea that dSCAR
  2290.      would be more successful if it continued to be marketed by me.  In
  2291.      successful I mean:  1) I could enhance the program to my
  2292.      specifications and continue to update it at my convenience; and
  2293.      2) financially I could do better selling dSCAR as user supported
  2294.      software than to take what the publisher offered me.
  2295.  
  2296.      During the 1989 summer break I did not seek a "real" job so that I
  2297.      could release dSCAR v3.0.  I am hoping sales of dSCAR will put me
  2298.      through four years of college at Cal Poly in San Luis Obispo,
  2299.      beginning in the fall of 1989.
  2300.  
  2301.      Why was version 3.0 so slow in coming?  Time was the number one
  2302.      culprit.  In addition to going to school I run track & field (10.7sec
  2303.      for 100m, 21.9 for 200m, 48.50 for 400m).  I hope to continue my
  2304.      running at Cal Poly, but will have someone else handle the dSCAR
  2305.      orders.
  2306.  
  2307.      dSCAR was not a one-man effort.  In addition to the registrants who
  2308.      provided monetary support and comments before v3.0, I wish to thank
  2309.      the following individuals for their beta-testing, support, or
  2310.      suggestions:  Randy Wallin, Gene Head, Todd Natkin, Bruce Bott, Kent
  2311.      Riesen, Rod Ledbetter, P. Olympia, Ed Albert, Jon Love, Larry Taylor,
  2312.      and Scott Ponder.
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332.  
  2333.  
  2334.  
  2335.  
  2336.                                    Page 36
  2337.