home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / database / q_pro4b.zip / QP4DOC.DOC
Text File  |  1989-09-01  |  436KB  |  15,711 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                 Q N E    I N T E R N A T I O N A L    P R E S E N T S
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                         TM
  16.                             Q - P R O  4      (Shareware)
  17.  
  18.                                      Version 4.0
  19.  
  20.  
  21.  
  22.           Q-PRO 4 is a fourth generation language and database for IBM PC-
  23.           DOS, Generic MS-DOS, Novell Netware, and all LANs and networks
  24.           that are IBM Netbios compatible. 
  25.  
  26.           Written in assembler, the Q-PRO 4 interpreter is amazingly fast. 
  27.           In fact, screen and file speed are so fast that an ordinary 4.77
  28.           Mhz PC with floppy disks makes a dandy application machine.
  29.            
  30.           Application development is typically 5 to 10 times faster than
  31.           other databases because of Q-PRO 4's advances features.  Some of
  32.           them are:
  33.  
  34.            -   Advanced fourth generation event driven architecture.
  35.            -   "Painted" screens.
  36.            -   Fill in the blanks data entry screens.
  37.            -   Extremely fast B+ tree multikey indexed file handling.
  38.            -   Inherently structured high level complete language syntax
  39.                with: procedures, table lookup, memory and file arrays,
  40.                subroutines, assembly language interface, and data
  41.                dictionary.
  42.            -   Full record and file locking on supported LAN's and
  43.                networks.
  44.            -   No practical limits on File Size, number of files open
  45.                simultaneously, record size, or memory variables.
  46.            -   Optional distribution system and licence.
  47.            -   Optional translator to language C.
  48.  
  49.           Thousands of commercial copies of Q-PRO 4, Version 4.0, are in
  50.           use in the United States and 40 foreign countries (including a
  51.           Japanese Language version) since 1986.  It has been reviewed in
  52.           Data Based Advisor, PC Magazine and others with universal
  53.           acclaim.
  54.  
  55.           We have recovered our development and made a modest profit so we
  56.           have decided to place it into shareware so more people can try
  57.           this extraordinary language. 
  58.  
  59.                                         Release 1.0
  60.                                         Langhorne, Pennsylvania
  61.                                         September 1, 1989
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.      Copyright (C) 1983-1989 QNE International.  All rights reserved.
  70.  
  71.      No part of this manual may be reproduced, transmitted, transcribed, stored
  72.      in a retrieval system, or translated into any language (natural or
  73.      computer), in any form or by any means, except as described in the
  74.      following license, without the prior written permission of QNE
  75.      International.
  76.  
  77.      You are granted a limited license to use the software described in this
  78.      manual.  The software may be used or copied only in accordance with the
  79.      terms of that license, which is described beginning on the next page.
  80.  
  81.      Information in this manual is subject to change without notice and does not
  82.      represent a commitment on the part of QNE International
  83.  
  84.      QNE International may make improvements and/or changes in this manual
  85.      and/or in Q-PRO 4 Test Drive and/or in Q-PRO 4 at any time.
  86.  
  87.      QNE International is a registered trademark, and Q-PRO 4 is a trademark of
  88.      QNE International.
  89.  
  90.      QNE International
  91.      136 Granite Hill Court
  92.      Langhorne, PA 19047
  93.      (215) 968-5966
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.                   T H E   Q - P R O 4   P R O D U C T   F A M I L Y
  102.                   =================================================
  103.  
  104.                                      Version 4.0
  105.                                      -----------
  106.      Q-PRO 4 User's Group (QUG)
  107.      --------------------------
  108.      Join QUG for only $25.00 per year and enjoy the benefits of a bulletin
  109.      board for users with hints, techniques, and public domain Q-PRO 4 software.
  110.  
  111.      Q-PRO 4
  112.      -------
  113.      This is the highly regarded and well reviewed version of the commercially
  114.      successful Q-PRO 4, Version 4.0.  Full system, manual, and 30 days (up to 2
  115.      hours) free telephone support.
  116.  
  117.      Q-PRO 4 Plus
  118.      ------------
  119.      The same as Q-PRO 4 with a six file report generator, dBASE II/III/IV
  120.      inport utility, Lotus import/export utility, custom configuration
  121.      utilities, and 60 days (up to 3 hours) of free telephone support.
  122.  
  123.      Authors LockUp
  124.      --------------
  125.      With this set of utilities, the application developer can encrypt and lock
  126.      the program code.  Purchase of this package includes a non-transferrable,
  127.      unlimited distribution licence.
  128.  
  129.      Q2C
  130.      ---
  131.      This product translates the Q-PRO 4 source code to language C.  It is then
  132.      compiled and linked producing .EXE files.  You can embed function calls and
  133.      C programs in the source code. Includes a non-transferrable, unlimited
  134.      distribution licence.
  135.  
  136.      Q-Query
  137.      -------
  138.      This is a "post-relational" query system designed for developers and
  139.      endusers.
  140.  
  141.                                      Version 5.0
  142.                                      -----------
  143.      Q-PRO 4, Version 5.0 is the gateway to OS2 and UNIX/XENIX.  All version 4.0
  144.      code is upwards compatible to version 5.0.  From there a whole new world of
  145.      hardware and operating systems is available.
  146.  
  147.                                      Version 3.0
  148.                                      -----------
  149.      For you unreconstructed 8 bit users, there is even a version that runs very
  150.      nicely on CP/M and MP/M-80 (Turbodos too!).  Call for information.
  151.  
  152.  
  153.                              Quic Start for the Impatient
  154.                                           3
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.                   Q U I C   S T A R T   for  the  I M P A T I E N T
  163.                   =================================================
  164.  
  165.      For those of you who don't read the documentation except as a last resort,
  166.      this short guide is dedicated.  We also assume that you know exactly what
  167.      you are doing!
  168.  
  169.      Things You Must Do
  170.      ------------------
  171.      1. Unpack the software. The software is in a self unpacking format.  Simply
  172.      log on the target drive and type the name of each furnished .EXE file.
  173.  
  174.      2.  * * * *  LOAD BTSYS.EXE * * * * by typing BTSYS.  If you skip this
  175.      step, you won't be able to read or write data files.
  176.  
  177.      The Minimum
  178.      -----------
  179.      Q-PRO 4 uses a combination of procedural code and "painted" screens.  You
  180.      write the pro-gram and paint the screen with the Binary Workstation editor.
  181.  
  182.      File handling is  multikey indexed sequential, random, or sequential.  Most
  183.      data files are indexed.  Indexed and random files are defined with a File
  184.      Item Description (FID) file.
  185.  
  186.      Getting On With It
  187.      ------------------
  188.      Load BW.EXE, the program editor.  You use BW to:
  189.  
  190.      -    write the programs.  It comes up ready to edit your program code.
  191.           Functions are initiated by pressing function keys.  The menu is shown
  192.           at the bottom of the screen.  
  193.  
  194.           Pressing F10 will scroll forward the functions associated with each
  195.           function key.  Pressing F9 scrolls backwards.
  196.  
  197.        -  develop the screens.  While in BW, press F8 to go to the screen
  198.           editor. Type the labels/prompts on the screen the way you want then to
  199.           be.  Press F1 to bring up a window used to define enterable screens.
  200.           
  201.        -  define the FID files.
  202.  
  203.      Putting It Together
  204.      ===================
  205.  
  206.      Application Overview
  207.      --------------------
  208.      Generally, you develop an application one program (or screen) at a time. 
  209.      Programs can freely "chain" each other into and out of memory.  Registers,
  210.      files and disk I/O buffers remain intact between screens.
  211.  
  212.  
  213.  
  214.                              Quic Start for the Impatient
  215.                                           4
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.      Program Flow of Control
  224.      -----------------------
  225.      Q-PRO 4 is "Event driven" so flow of control is completely different than
  226.      almost every other language.  Control goes back and forth between the
  227.      operator and program.  This is always under the control of the programmer. 
  228.      For example, when the user is entering data on the screen, he has control. 
  229.      When he moves to the next enterable field, usually the programmer has
  230.      control.
  231.  
  232.      Developing Programs
  233.      ------------------
  234.      The sequence of developing a program module is usually:
  235.  
  236.        1. Design the screen and its entry fields.  The screen data entry fields,
  237.           once defined, are the same as defining memory variables, i.e. you can
  238.           interrogate their value, move data into and out of them, etc.
  239.       
  240.           One of the fields to be filled out when defining a screen data entry
  241.           is "PROCEDURE NAME".  If you enter a name here, when the user enters
  242.           the field and then goes to the next field by pressing return or an
  243.           arrow, the named procedure will be executed.
  244.  
  245.       2.  Write the program code.  The program code is organized into PROCEDURES
  246.           or PROC's.  A procedure is initiated with the keyword (not too
  247.           surprisingly) PROC followed by a space and the name of the procedure. 
  248.           PROC names (and all other names) are limited to 10 characters in
  249.           length and MUST begin with an alpha character. (NOTE: Q-PRO 4 treats
  250.           upper and lower case identically.)
  251.  
  252.           PROCS are terminated with either an END or in the case of a "CALLed"
  253.           proc RETURN.  When the proc terminates control reverts to the operator
  254.           in the enterable screen data field that the programmer puts him in. 
  255.           Usually this is the next enterable field, but the programmer has full
  256.           control of this. 
  257.             
  258.       3.  Designing the files.  Usually the primary data file is very similar to
  259.           the fields on the screen.  If this is the case, the Quic FID facility
  260.           can be utilized very effectively.
  261.  
  262.  
  263.       4.  Learning the language.  Look over the included sample programs
  264.           starting with SAMPINS.QNE.  They are profusely commented and
  265.           illustrate some common coding techniques.
  266.  
  267.           Read the Commands Section of the manual to see the breadth of commands
  268.           available.
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.                              Quic Start for the Impatient
  276.                                           5
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.                                  Quic Reference Card
  285.                                  ===================
  286.  
  287.      IBM PC Terminal Keyboard Definitions
  288.  
  289.      Cursor Left . . . . . .  Left Arrow
  290.      Cursor Right. . . . . .  Right Arrow
  291.      Cursor Up . . . . . . .  Up Arrow
  292.      Cursor Down . . . . . .  Down Arrow
  293.      Cursor Home . . . . . .  Home
  294.      Tab       . . . . . . .  Return key
  295.      Back Tab  . . . . . . .  Shift Tab
  296.      Enter Data  . . . . . .  END
  297.      Function 0  . . . . . .  ESC
  298.      Funct 1-9   . . . . . .  F1-F9
  299.      Funct 11-20 . . . . . .  SF1-SF10
  300.      Clear Screen  . . . . .  Control Home
  301.      Clear to End of Line  .  Control End
  302.      Clear to End of Screen   Control Pg Down
  303.      Insert Character. . . .  Insert Key
  304.      Delete Character. . . .  Delete Key
  305.  
  306.  
  307.      COMMAND SYNTAX
  308.      --------------
  309.      Items within braces {} are optional.  Items within angle brackets <> denote
  310.      a class of item, rather than a literal value.  Square brackets [] are
  311.      required where shown.
  312.  
  313.      Field Descriptor Values
  314.      -----------------------
  315.      Space,x   any data
  316.      X         any data, forced to upper case
  317.      a         alphabetic data(A-Z,a-z,blank)
  318.      A         alphabetic data forced to upper case
  319.      m         alphanumeric data (A-Z, a-z, 0-9, blank)
  320.      M         alphanumeric data forced to upper case (A-Z, a-z, 0-9, blank)
  321.      n,N       numeric data (0-9  +  -  .)
  322.      i,I       integer data (0-9  +  -)
  323.      d, D      digit data (0-9)
  324.  
  325.      Field Functions
  326.      ---------------
  327.      =    autoduplicate       ?    invisible field
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.                                  Quic Reference Card
  336.                                         Page 6
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.      Data Elements
  345.      --------------
  346.      Registers"     Numeric:  #N0  to   #N9
  347.                     String:   #S0  to   #S9
  348.                     Boolean:  #B0  to   #B9
  349.                     Error:    #E   Field:    #F
  350.                     Line:     #L   Keyout:   #K
  351.                     Page:     #P
  352.  
  353.      Screen Fields
  354.      -------------
  355.      $FIELD    [<expression>]      $OFFSET   [<screen data field name>]
  356.  
  357.      File Fields
  358.      -----------
  359.      &<file field name>[<file #>]  &<file field name>[<file #>,<index>]
  360.  
  361.      Literals
  362.      --------
  363.      String (". . ." or '. . .')    Numeric (1,37,5 etc.) 
  364.      Control character (@<value>)
  365.  
  366.      Variables
  367.      ---------
  368.      B - Boolean or bit (set(1) or reset(0))
  369.      I - Integer (-2,147,483,648 to 2,147,483,647)
  370.      F - Floating Point (1.7E-308 to 1.7E+308)
  371.      N - Numeric (0-9, decimal point, plus sign)
  372.      X - String (X indicates any data: alphanumeric, symbols, etc.)
  373.      <variable name> <N or X>, <length> {,<dimension>} {,<2nd dimension>}
  374.  
  375.  
  376.      Keyout Values (#K)
  377.      -------------
  378.        0 - Typed out               1 - Tabbed out
  379.        2 - Backtabbed out          3 - Cursor up
  380.        4 - Cursor down             5 - Cursor left
  381.        6 - Cursor right            7 - Enter
  382.        8 - Home                    9 - Any Function key
  383.       10 - Break
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.                                  Quic Reference Card
  396.                                         Page 7
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.                                        Commands
  405.                                        --------
  406.  
  407.      File Handling
  408.      -------------
  409.      BACKSPACE <file#>{:<error>}
  410.      CLOSE {file# or *}{:<error>}
  411.      COPY <file# or *> TO <file# or *> {:<error>}
  412.      ERASE <filename>{:<error>}
  413.      FCOPY <filename>TO<filename>{:<error>}
  414.      FILETYPE <file#>{:<error>}
  415.      FREE <file#>{:<error>}
  416.      FSEAR <file#>{NOADV}AT<condition> {:<error>}
  417.      GET <data or *> FROM <file#> FOR <length>{TRIMMED}{:<error>}
  418.      KEY <file#>USING<key#>{:<error>}
  419.      LRETRY  <retrycount>
  420.      MAKE/OPEN
  421.       sequential out
  422.           <filename>,0,<file#> {:<error>}
  423.       sequential in
  424.           <filename>,1,<file#>{:<error>} 
  425.       SDF out
  426.           <filename>,4,<file#>{:<error>}
  427.       SDF in
  428.           <filename>,5,<file#>{:<error>}
  429.      Random/Indexed 
  430.           <filename>USING<FIDname>{INDEX<indexname>},<file#>, {UNLOCKED} {R/O}  
  431.         {:<error>}
  432.      POSN <file#> TO <record or key> {RELATIVE} {USING<key#>} {DESCENDING}
  433.           {:<error>}
  434.      PUT <data or *> TO <file#>{FOR <length>}{:<error>}
  435.      RCLEAR <file#>{:<error>}
  436.      READ <file#>{NOADV}{:<error>}
  437.      RENAME <oldfilename>,<newfilename> {:<error>}
  438.      RESTART <file#>{TO<position>}{:<error>}
  439.      RLOCK <file#>{:<error>}
  440.      RUNLOCK <file#>{:error}
  441.      SECURE <file#>{:<error>}
  442.      WRITE <file#>{NOADV}{:<error>}
  443.  
  444.      Error Handling
  445.      --------------
  446.      ERROR <error message, register, or variable>
  447.      ERRTRAP {<line#>}
  448.      NCHECK <data>{:<error>}
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.                                  Quic Reference Card
  456.                                         Page 8
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.      Data Formatting
  465.      ---------------
  466.      EDIT <expression>USING<picture>INTO <data>{:<error>}
  467.      CENTER <data>       CURRENCY <string>   LCASE <data>
  468.      LJUST <data>        RJUST <data>        SIZE <data>INTO<data>{TRIMMED}
  469.      UCASE <data>        UNEDIT <data>INTO<data>{:<error>}
  470.  
  471.      Arithmetic
  472.      ----------
  473.      ACCURACY <value>         ADD <data>TO<data>{GIVING <data>}
  474.      CALC <data>=<expression> MUL <data>TIMES<data>{GIVING <data>}
  475.      ROUND <expression>BY<expression>INTO <data>
  476.      SUB <data>FROM<data>{GIVING <data>}
  477.  
  478.  
  479.      Logical
  480.      -------
  481.      RESET <Boolean register or variable>    SET <Boolean register or variable>
  482.  
  483.      Control Transfer
  484.      ----------------
  485.      BEGIN {WHILE/UNTIL/IF <condition>}
  486.      ELSE {IF<condition>}
  487.      ENDBEGIN {WHILE/UNTIL <condition>}
  488.      BROFF     BRON
  489.      CALL <procedure>    CALL <table[index]>
  490.      CHAIN <filename>{:error}
  491.      END
  492.      FOR <index>=<expression>TO<expression>BY<expression>
  493.      ENDFOR <index>
  494.      GOTO <label>        GOTO <table[index]>
  495.      RETURN
  496.  
  497.      Conditional
  498.      -----------
  499.      IF<condition>{THEN}<statement>
  500.  
  501.      Screen Control
  502.      --------------
  503.      CLEAR <field or *>            CURSOR <row>,<column>
  504.      BUFFER <expression>           FILL <character>
  505.      PRINT <data>{,<data> . . .}   HELP <screen>{,<screen>}{:<error>}
  506.      HOME           HOMECLEAR      HOFF      HON
  507.      LOCK <field>   NEXT <field>
  508.      RESUME
  509.      UNLOCK <field or *>
  510.  
  511.  
  512.  
  513.  
  514.  
  515.                                  Quic Reference Card
  516.                                         Page 9
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.      Data Movement
  525.      -------------
  526.      CONCAT <data>{[<start>,<length or *>] } {TRIMMED} +<data>{[<start>,<length
  527.             or *>]} {TRIMMED} +.  .  .  . INTO <data>{[<start or *>]} {TRIMMED}
  528.      MOVE <data> {[<start>,<length or *>]} TO <data> { [<start or *>]} {TRIMMED}
  529.  
  530.      Table Management
  531.      ----------------
  532.      TABLE <table name>
  533.      TSEAR <table> AT <key>{,<data>, <data>}{:<error>}
  534.      ASEAR <array name> {DOWN} USING <index> AT <condition> {:<error>}
  535.  
  536.      Date Handling
  537.      -------------
  538.      JDPACK <string> INTO <data>        JDUNPACK <data> INTO <string>
  539.      GETDATE <data>                     SETDATE <data>
  540.  
  541.      Operating System Interface
  542.      FORMLOAD            NOFORMLOAD
  543.      SYSTEM              LPDETACH
  544.      HOST <host system> {:<error>} 
  545.      RUN <file name> USING <parameter>{NOPAUSE} {NORETURN} {RELOAD} <filename>}
  546.          {CONTINUE} {:<error>}
  547.  
  548.      Miscellaneous
  549.      -------------
  550.      *    comment
  551.      SYSMODE BTAB <SET or RESET>
  552.              LPCHK <SET or RESET>
  553.      PRINTSCN {:<error>} 
  554.      INSTR <substring>{TRIMMED},<string>{TRIMMED},<result>
  555.  
  556.      Debugging
  557.      ---------
  558.      NOTRACE        TRACE          DEBUG
  559.       
  560.      Assembler Interface
  561.      -------------------
  562.      DEFSEG {<address>}
  563.      EXEC <input  string> {,<output  string>} {:<error>}
  564.      LOAD <filename>,<address>{:<error>}
  565.      PEEK <address>, <length>, <data>   POKE <address>, <data>
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.                                  Quic Reference Card
  576.                                        Page 10
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.                                   SPECIAL PROCEDURES
  585.                                   ==================
  586.  
  587.      PROC BREAK          PROC ENTER          PROC ERROR
  588.      PROC  KEY<N>        PROC LOAD
  589.  
  590.  
  591.                                       FUNCTIONS
  592.                                       ---------
  593.  
  594.      ASCII Value:   $ASC()         e to Power:    $ETOX()
  595.      Scrn.Field No.:$FIELD()       Integer Value: $INT()
  596.      Top of memory: $MEMEND()      Natural Log:   $LN()
  597.      Screen Offset: $OFFSET()
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.                                  Quic Reference Card
  636.                                        Page 11
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.                                   Table of Contents
  646.  
  647.  
  648.      SINGLE COPY SOFTWARE LICENSE  . . . . . . . . . . . . . . . . . . . . .   1
  649.  
  650.      LIMITED LICENSE TO COPY . . . . . . . . . . . . . . . . . . . . . . . .   3
  651.  
  652.      I N T R O D U C I N G   Q-PRO 4  T E S T   D R I V E  . . . . . . . . .   4
  653.           Purchasing Q-PRO 4 . . . . . . . . . . . . . . . . . . . . . . . .   5
  654.  
  655.      Q-PRO 4  O V E R V I E W  . . . . . . . . . . . . . . . . . . . . . . .   7
  656.  
  657.      Q - P R O 4   T U T O R I A L . . . . . . . . . . . . . . . . . . . . .  10
  658.           Installing Q-PRO 4 . . . . . . . . . . . . . . . . . . . . . . . .  11
  659.           Example Program  . . . . . . . . . . . . . . . . . . . . . . . . .  11
  660.                Load Binary WorkStation . . . . . . . . . . . . . . . . . . .  11
  661.                STEP 1 - Build the Background . . . . . . . . . . . . . . . .  12
  662.                Graphics and Highlighting . . . . . . . . . . . . . . . . . .  13
  663.                STEP 2 - Define Fields  . . . . . . . . . . . . . . . . . . .  13
  664.                Primary Edits . . . . . . . . . . . . . . . . . . . . . . . .  14
  665.                STEP 2a - Run the Screen Program  . . . . . . . . . . . . . .  16
  666.                STEP 3 - Define the Data Files  . . . . . . . . . . . . . . .  17
  667.                STEP 4 - Coding the Program   . . . . . . . . . . . . . . . .  18
  668.           Using the Editor . . . . . . . . . . . . . . . . . . . . . . . . .  19
  669.           PROC LOAD  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  20
  670.           PROC NAMEP . . . . . . . . . . . . . . . . . . . . . . . . . . . .  21
  671.           Event Driving  . . . . . . . . . . . . . . . . . . . . . . . . . .  22
  672.                The Linkage . . . . . . . . . . . . . . . . . . . . . . . . .  23
  673.                Adding the Linkage  . . . . . . . . . . . . . . . . . . . . .  23
  674.           Recording Data . . . . . . . . . . . . . . . . . . . . . . . . . .  23
  675.           Finding and Fixing Bugs  . . . . . . . . . . . . . . . . . . . . .  24
  676.           Hints, Tips & Techniques . . . . . . . . . . . . . . . . . . . . .  29
  677.           Sample Programs  . . . . . . . . . . . . . . . . . . . . . . . . .  29
  678.           Advanced Input Editing . . . . . . . . . . . . . . . . . . . . . .  31
  679.           Screen Handling  . . . . . . . . . . . . . . . . . . . . . . . . .  33
  680.                Screen Graphics . . . . . . . . . . . . . . . . . . . . . . .  33
  681.                Screen Offset . . . . . . . . . . . . . . . . . . . . . . . .  34
  682.           Structured Programming . . . . . . . . . . . . . . . . . . . . . .  36
  683.                Structured Constructs . . . . . . . . . . . . . . . . . . . .  36
  684.           Debugging  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  37
  685.           All About Registers  . . . . . . . . . . . . . . . . . . . . . . .  38
  686.           Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  40
  687.           Variables  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  43
  688.                Declaring Variables . . . . . . . . . . . . . . . . . . . . .  44
  689.                Dimensioned Variables . . . . . . . . . . . . . . . . . . . .  45
  690.           LANs and Multiuser . . . . . . . . . . . . . . . . . . . . . . . .  46
  691.                Commands  . . . . . . . . . . . . . . . . . . . . . . . . . .  46
  692.                Record Locking  . . . . . . . . . . . . . . . . . . . . . . .  46
  693.  
  694.  
  695.                                  Quic Reference Card
  696.                                        Page 12
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.                Record Unlocking  . . . . . . . . . . . . . . . . . . . . . .  47
  705.                File Locking  . . . . . . . . . . . . . . . . . . . . . . . .  47
  706.                Accession Number Management . . . . . . . . . . . . . . . . .  48
  707.           Restructuring an Indexed File  . . . . . . . . . . . . . . . . . .  49
  708.                Adding Keys . . . . . . . . . . . . . . . . . . . . . . . . .  49
  709.  
  710.      P R O G R A M M E R'S    R E F E R E N C E   M A N U A L  . . . . . . .  50
  711.                Naming Conventions  . . . . . . . . . . . . . . . . . . . . .  50
  712.                Format Files  . . . . . . . . . . . . . . . . . . . . . . . .  50
  713.                Building a Format . . . . . . . . . . . . . . . . . . . . . .  50
  714.                Build Screens . . . . . . . . . . . . . . . . . . . . . . . .  51
  715.           THE PROGRAMMING SYSTEM . . . . . . . . . . . . . . . . . . . . . .  55
  716.                Procedures  . . . . . . . . . . . . . . . . . . . . . . . . .  55
  717.                Screen Data Field Procedures  . . . . . . . . . . . . . . . .  55
  718.                Data Items  . . . . . . . . . . . . . . . . . . . . . . . . .  56
  719.           Standard Procedures  . . . . . . . . . . . . . . . . . . . . . . .  60
  720.                PROC BREAK  . . . . . . . . . . . . . . . . . . . . . . . . .  60
  721.                PROC ENTER  . . . . . . . . . . . . . . . . . . . . . . . . .  60
  722.                PROC ERROR  . . . . . . . . . . . . . . . . . . . . . . . . .  60
  723.                PROC KEY0-20  . . . . . . . . . . . . . . . . . . . . . . . .  61
  724.                PROC LOAD . . . . . . . . . . . . . . . . . . . . . . . . . .  61
  725.           Statement Types  . . . . . . . . . . . . . . . . . . . . . . . . .  61
  726.                Expressions . . . . . . . . . . . . . . . . . . . . . . . . .  63
  727.           Screen Offset  . . . . . . . . . . . . . . . . . . . . . . . . . .  63
  728.           Structured Programming . . . . . . . . . . . . . . . . . . . . . .  64
  729.           Tables and Table Handling  . . . . . . . . . . . . . . . . . . . .  65
  730.  
  731.      FILES AND FILE HANDLING . . . . . . . . . . . . . . . . . . . . . . . .  70
  732.                File Handler  . . . . . . . . . . . . . . . . . . . . . . . .  70
  733.                File System Interrupts  . . . . . . . . . . . . . . . . . . .  70
  734.                Loading BTSYS . . . . . . . . . . . . . . . . . . . . . . . .  70
  735.                File Types  . . . . . . . . . . . . . . . . . . . . . . . . .  71
  736.           Multi-key Indexed Sequential Files . . . . . . . . . . . . . . . .  71
  737.                File Keys . . . . . . . . . . . . . . . . . . . . . . . . . .  71
  738.                Reading and Writing . . . . . . . . . . . . . . . . . . . . .  71
  739.                Data File . . . . . . . . . . . . . . . . . . . . . . . . . .  72
  740.                Index File  . . . . . . . . . . . . . . . . . . . . . . . . .  72
  741.                Deleted Records . . . . . . . . . . . . . . . . . . . . . . .  73
  742.                File Maintenance  . . . . . . . . . . . . . . . . . . . . . .  73
  743.           Random Files . . . . . . . . . . . . . . . . . . . . . . . . . . .  73
  744.                Structure . . . . . . . . . . . . . . . . . . . . . . . . . .  73
  745.           Sequential (text) Files  . . . . . . . . . . . . . . . . . . . . .  73
  746.           SDF (Comma Delimited) Files  . . . . . . . . . . . . . . . . . . .  74
  747.           Indexed and Random File Handling . . . . . . . . . . . . . . . . .  74
  748.                Fundamentals  . . . . . . . . . . . . . . . . . . . . . . . .  74
  749.                Data Dictionary (FID) Files . . . . . . . . . . . . . . . . .  74
  750.                PC-DOS and MS-DOS File Considerations . . . . . . . . . . . .  75
  751.                File Restructuring  . . . . . . . . . . . . . . . . . . . . .  75
  752.           File Handling Commands . . . . . . . . . . . . . . . . . . . . . .  76
  753.  
  754.  
  755.                                  Quic Reference Card
  756.                                        Page 13
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.                MAKE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  765.                OPEN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  766.                FILETYPE  . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  767.                CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  768.                SECURE  . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
  769.                PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  770.                GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  771.                KEY . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  772.                POSN  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  77
  773.                READ  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  774.                WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  775.                FREE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  776.                COPY  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  78
  777.  
  778.      ERROR HANDLING  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  80
  779.           Local Error Traps  . . . . . . . . . . . . . . . . . . . . . . . .  80
  780.           PROC ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . .  81
  781.           ERRTRAP  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  82
  782.  
  783.      LANS and MULTIUSER SYSTEMS  . . . . . . . . . . . . . . . . . . . . . .  84
  784.                Principles  . . . . . . . . . . . . . . . . . . . . . . . . .  84
  785.           Multiuser Commands . . . . . . . . . . . . . . . . . . . . . . . .  84
  786.           MULTIUSER - ERRORS . . . . . . . . . . . . . . . . . . . . . . . .  87
  787.  
  788.      B I N A R Y   W O R S T A T I O N . . . . . . . . . . . . . . . . . . .  89
  789.           Starting Up  . . . . . . . . . . . . . . . . . . . . . . . . . . .  90
  790.           The Text Editor  . . . . . . . . . . . . . . . . . . . . . . . . .  93
  791.           Fid Generator  . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  792.                FID Files . . . . . . . . . . . . . . . . . . . . . . . . . . 104
  793.                Referencing File Data Fields  . . . . . . . . . . . . . . . . 109
  794.  
  795.      Q - P R O 4   C O M M A N D S . . . . . . . . . . . . . . . . . . . . . 111
  796.           Symbology  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
  797.                Structure of the Commands . . . . . . . . . . . . . . . . . . 111
  798.                Naming Conventions  . . . . . . . . . . . . . . . . . . . . . 112
  799.                Data Items  . . . . . . . . . . . . . . . . . . . . . . . . . 112
  800.                Expressions . . . . . . . . . . . . . . . . . . . . . . . . . 114
  801.           Function Summary . . . . . . . . . . . . . . . . . . . . . . . . . 115
  802.           Command Summary  . . . . . . . . . . . . . . . . . . . . . . . . . 116
  803.           F u n c t i o n s  . . . . . . . . . . . . . . . . . . . . . . . . 119
  804.           C O M M A N D S  . . . . . . . . . . . . . . . . . . . . . . . . . 126
  805.  
  806.      Q - P R O 4  E R R O R   M E S S A G E S  . . . . . . . . . . . . . . . 233
  807.  
  808.      QMAINT  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
  809.  
  810.      Order Form  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
  811.  
  812.  
  813.  
  814.  
  815.  
  816.                                   License Agreement
  817.                                           0
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.                             THIS SOFTWARE IS NOT FOR SALE
  826.                             -----------------------------
  827.  
  828.      Q-PRO 4 Test Drive is subject to the following license terms and
  829.      conditions.
  830.  
  831.                              SINGLE COPY SOFTWARE LICENSE
  832.                                   QNE International
  833.                           ----------------------------------
  834.                           
  835.      THIS IS A SINGLE COPY SOFTWARE LICENSE granted by Quic-n-Easi Products,
  836.      Inc, trading as QNE International, a New Jersey Corporation with its
  837.      mailing address at 136 Granite Hill Court, Langhorne, PA 19047. Q-PRO 4
  838.      Test Drive is licensed to you as the end user.  It is not sold.
  839.  
  840.      Q-PRO 4 Test Drive is copyrighted material. You may use it on  a trial
  841.      basis provided you do not violate the copyright and if you  follow these
  842.      simple rules.  Use of Q-PRO 4 Test Drive on a regular basis requires
  843.      purchase as described later.
  844.  
  845.      You may not make any changes or modifications to Q-PRO Tests  DRIVE, and
  846.      you may not decompile, disassemble, or otherwise Reverse-engineer it. You
  847.      may not rent or lease it to others.
  848.  
  849.      You may make copies of Q-PRO 4 Test Drive only under the terms  of the
  850.      following section entitled "Limited License to Copy".
  851.  
  852.      This Software is Commercial Computer Software under Federal  Government
  853.      Acquisition Regulations and agency supplements to them. The Software is
  854.      provided to the Federal Government and its agencies  only under the
  855.      Restricted Bights Provisions of the Federal Acquisition Regulations
  856.      applicable to commercial computer software developed at private expense and
  857.      not in the public domain. The Use, Duplication, or disclosure by the Gov-
  858.      ernment is subject to restrictions as set forth in subdivision (c)(l)(ii)
  859.      of the Rights  in Technical Data and Computer Software clause at
  860.      252.227-7013.
  861.  
  862.      LIMITED WARRANTY.  QNE International does not warrant that the functions 
  863.      contained in the software will meet your requirements or that the  oper-
  864.      ation of the software will be uninterrupted or error free.  The warranty
  865.      does not cover any media or documentation which has been  subjected to
  866.      damage or abuse by you. The software warranty does not  cover any copy of
  867.      the software which has been altered or changed in any way by you or others. 
  868.      QNE International is not responsible for problems caused by changes in the
  869.      operating characteristics of the computer hardware or operating system
  870.      which are made after the delivery of the software.
  871.  
  872.      ANY IMPLIED WARRANTIES INCLUDING ANY WARRANTIES OF MERCHANTABILITY  OR
  873.      FITNESS FOR A PARTICULAR PURPOSE ARE LIMITED TO THE TERM OF THE
  874.      EXPRESS WARRANTIES. Some States do not allow limitations on how long an
  875.  
  876.  
  877.                                   License Agreement
  878.                                           1
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.      implied warranty lasts, so the above limitation may not apply to you.
  887.  
  888.      QNE International SHALL NOT IN ANY CASE BE LIABLE FOR SPECIAL, INCIDENTAL,
  889.      CONSEQUENTIAL,INDIRECT OR OTHER SIMILAR DAMAGES ARISING FROM ANY BREACH OF
  890.      THESE WARRANTIES EVEN IF QNE International OR ITS AGENT HAS BEEN ADVISED OF
  891.      THE POSSIBILITY OF SUCH DAMAGES.  Some states do not allow the exclusion or
  892.      limitation of incidental or consequential  damages, so the above limitation
  893.      or exclusion may not apply to you.
  894.  
  895.      The warranties set forth above are in lieu of all other express end 
  896.      implied warranties, whether oral, written, or implied, and the remedies set
  897.      forth above are your sole and exclusive remedy.
  898.  
  899.      LIMITATION OF LIABILITY. In no case shall QNE International's liability
  900.      exceed the license fees paid for the right to use Q-PRO 4 TEST DRIVE or ten
  901.      Dollars ($10.00), whichever is greater.
  902.  
  903.      INTEGRATION. This License constitutes the entire agreement and   
  904.      understandIng between the parties and supersedes any prior agreement or
  905.      understanding whether oral or written, relating to the  subject of this
  906.      License. This Agreement may only be modified by a  written agreement signed
  907.      by QNE International.
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.                                   License Agreement
  939.                                           2
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946.  
  947.                                LIMITED LICENSE TO COPY
  948.                                =======================
  949.  
  950.      You are granted a limited license to copy Q-PRO 4 Test Drive only for the
  951.      trial use of others subject to the software license described above, and
  952.      also the following:
  953.  
  954.      Q-PRO 4 Test Drive must be copied in unmodified form, complete with the
  955.      following files:
  956.  
  957.      QNE.EXE   The Q-PRO 4 TEST DRIVE program
  958.  
  959.      BW.EXE    The Binary Workstation Editor
  960.  
  961.      BWFID.EXE The Binary Workstation FID generator
  962.  
  963.      QNE.DOC   The Q-PRO 4 Documentation on disk.
  964.  
  965.  
  966.      The full and unmodified Q-PRO 4 Test Drive documentation must be included
  967.      with the copy.
  968.  
  969.      No fee, charge or other compensation may be accepted or requested by anyone
  970.      without express written permission from QNE International.
  971.  
  972.      Q-PRO 4 Test Drive may not be distributed in conjunction with any other
  973.      product or service without a specific license to do so from QNE
  974.      International.
  975.  
  976.      Q-PRO 4 Test Drive may be distributed only in North America - DISTRIBUTION
  977.      OF Q-PRO 4 Test Drive OUTSIDE OF NORTH AMERICA IS STRICTLY FORBIDDEN.
  978.  
  979.      Operators of electronic bulletin board systems (Sysops) may post Q-PRO 4
  980.      Test Drive for downloading by their users without written permission only
  981.      as long as the above conditions are met.  A fee may be charged for access
  982.      to the BBS as long as no specific fee is charged for access to the Q-PRO 4
  983.      Test Drive files.
  984.  
  985.      Distributors of public domain and user supported software, such as disk
  986.      vending services, may distribute copies of Q-PRO 4 Test Drive subject to
  987.      the above conditions only after obtaining written permission from QNE
  988.      International.  Such permission usually is granted; please write for
  989.      details.
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.                                   License Agreement
  1000.                                           3
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.                  I N T R O D U C I N G   Q-PRO 4  T E S T   D R I V E
  1009.                  ====================================================
  1010.  
  1011.      Q-PRO 4 Test Drive is the "try before you buy" version of Q-PRO 4.  QNE
  1012.      International created it to allow you to "test drive" Q-PRO 4 before
  1013.      committing your hard earned dollars.  This has benefits for both the users
  1014.      and the authors.
  1015.  
  1016.      First of all, though, you must be aware that Q-PRO 4 and Q-PRO 4 Test Drive
  1017.      ARE NOT free software, NOR are they in the PUBLIC DOMAIN.  Both programs
  1018.      are fully copyrighted works protected to the full extent of US and
  1019.      international copyright law.
  1020.  
  1021.      Why allow a program "test drive"?  Q-PRO 4 Test Drive is based on a
  1022.      marketing technique called "shareware" or "user-supported software",  which
  1023.      is a means for the computing community to receive quality software  while
  1024.      directly supporting authors.  It is based on the idea that the  value and
  1025.      utility of software is often best assessed by the user on his or her own
  1026.      system.  Only after using a program can one really determine  whether it
  1027.      serves personal applications, needs and tastes.
  1028.  
  1029.      The benefits to users are fairly obvious: you are allowed to thoroughly
  1030.      evaluate the software before purchasing it.  How many times have you
  1031.      purchased an expensive piece of software only to find that it doesn't do
  1032.      what you need?
  1033.  
  1034.      Software authors benefit by creating a distribution channel of satisfied
  1035.      users who 
  1036.  
  1037.      recommend and pass along their product.  This"pyramid" effect can be a very
  1038.      effective marketing technique, and is vastly less expensive than
  1039.      traditional marketing techniques.  This is not to say that "test drives"
  1040.      and more traditional methods like magazine advertising are mutually
  1041.      exclusive.  They may be used together very effectively to target different
  1042.      segments of the market.
  1043.  
  1044.      What does this mean to you?  While you are granted a limited license to
  1045.      evaluate the program on a trial basis, regular use of the program requires
  1046.      purchase.  What is a "trial basis"?  Kicking the program around over a
  1047.      weekend to see how it works is certainly using it on a trial basis. 
  1048.      Installing and using the program in a production test environment for two
  1049.      weeks is trial use.  Using the software twice a week for regular work for
  1050.      three months is not and therefore requires purchase.  Using the program
  1051.      regularly for any regular task, especially if it has replaced other
  1052.      software, is not trial use.  These examples are not intended as definitive
  1053.      rules, but more as general guidelines.
  1054.  
  1055.      You are not allowed to modify the software under any conditions.  We do,
  1056.      however, encourage you to create "add-on" support utilities and program to
  1057.      enhance your and others' enjoyment of the program.
  1058.  
  1059.  
  1060.                                      Introduction
  1061.                                           4
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.      You may copy the program for the trial use of others subject to the rule
  1070.      outlined in the previous section "Limited License to Copy".  In general,
  1071.      you may only copy the program in complete and unmodified form, as we
  1072.      distribute it.
  1073.  
  1074.      You may not charge any fee for copies of the program without written
  1075.      permission from QNE International.  This applies especially to disk
  1076.      vendors.   Some services mislead customers into thinking they have
  1077.      purchased the software, rather than just the disk and duplication service. 
  1078.      If you have purchased this product from a disk vendor and feel they were
  1079.      misleading about what you have purchased, please write us and we will
  1080.      investigate the matter.
  1081.  
  1082.      You may not include Q-PRO 4 Test Drive with any other product,   whether
  1083.      hardware or software, without specific license.  For example, you   may not
  1084.      include Q-PRO 4 Test Drive on the hard drives of computers   you  sell, or
  1085.      include it with copies of software you have developed.
  1086.  
  1087.  
  1088.                                   Purchasing Q-PRO 4
  1089.                                   ==================
  1090.  
  1091.      After using Q-PRO 4 Test Drive for a while, you need to decide if you want
  1092.      to continue using it on a regular basis.  If not, please feel free to
  1093.      continue copying it for the trial use of others, or to pass your copy along
  1094.      to a friend.
  1095.  
  1096.      Please note that there are two versions of the software, Q-PRO 4 and Q-PRO
  1097.      4 Test Drive.  The TEST DRIVE version may be copied and used for evaluation
  1098.      as described above.  The purchased version of Q-PRO 4, however, may only be
  1099.      copied for backup purposes.  After receiving your purchased copy of Q-PRO 4
  1100.      you may continue to copy Q-PRO 4 Test Drive for friends; you may not copy
  1101.      Q-PRO 4.
  1102.  
  1103.      Why should you purchase Q-PRO 4?  To pay for the software which you are
  1104.      gainfully using, and to support its authors and encourage them to produce
  1105.      more high quality software.  And because regular use of Q-PRO 4 Test Drive
  1106.      without purchase is a violation of the license
  1107.      under which you use it.
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.                                      Introduction
  1122.                                           5
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.      When you purchase Q-PRO 4 for $50.00, you will receive the following:
  1131.  
  1132.       -   Perpetual license for you to use the software you have purchased. 
  1133.       -   A two disk program set including a serialized Q-PRO 4.
  1134.       -   A 300+ page professionally typeset and printed manual which includes a
  1135.           tutorial and index.
  1136.       -   30 days (up to 2 hours) telephone technical support.
  1137.  
  1138.      When you purchase Q-PRO 4 Plus for $90.00, you will receive, in addition to
  1139.      the above:
  1140.  
  1141.       -   Utilities to import/export Lotus files, to import dBASE II/III/IV data
  1142.           files, to custom configure your Q-PRO 4 keyboard any way you want, and
  1143.           to custom configure Binary WorkStation.
  1144.       -   The Q-PRO 4 non-procedural report generator.
  1145.       -   60 days (up to 3 hours) of telephone technical support.
  1146.        
  1147.      To order via credit card, call our business office at (800) 333-0448. Cash
  1148.      and check purchasers should use the order form in the back of this manual.
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164.  
  1165.  
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.                                      Introduction
  1183.                                           6
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.                                Q-PRO 4  O V E R V I E W
  1192.                               ======================== 
  1193.      Design Freedom
  1194.      --------------
  1195.      Q-PRO 4's design philosophy of Q-PRO 4 is different from almost any other
  1196.      language or "database manager" that you have ever seen.  Our approach makes
  1197.      the language work for you, not vice versa.
  1198.  
  1199.      Non Sequitur
  1200.      ------------
  1201.      All of you have used and been used by BASIC, FORTRAN, or, more likely,
  1202.      dBASE II or dBASE III (or IV - which is probably why you are reading these
  1203.      words!).  All are sequential languages.
  1204.  
  1205.      In sequential languages, the program code is running continuously.  If
  1206.      there is to be interaction with the operator through the keyboard/CRT, the
  1207.      programmer must handle this interaction in excruciating detail under
  1208.      program control.  These languages were either designed before the advent of
  1209.      CRT's or the authors forgot that in a modern environment, the user of an
  1210.      application is almost continuously communicating with the application
  1211.      through the keyboard.
  1212.  
  1213.      To overcome this design shortcoming, the programmer must write enormous
  1214.      amounts of code to communicate with the user.  More than likely, because of
  1215.      the ever-present deadlines, the 
  1216.  
  1217.      screen becomes a repetitive question and answer session--a completely
  1218.      unsatisfactory human interface.
  1219.  
  1220.      Events Drive Us
  1221.      ---------------
  1222.      How is Q-PRO 4 different?  Q-PRO 4 is an "event" driven language not a
  1223.      "sequential" language.  An event driven language itself detects keystrokes
  1224.      or the status of a screen input field as an event automatically.  This
  1225.      information is immediately available for program control.  The programmer
  1226.      then determines if and where in the program to transfer control.  Now you
  1227.      can concentrate on the application, not the management of the environment.
  1228.  
  1229.      Q-PRO 4 senses events at several levels.  The most fundamental is automatic
  1230.      sensing of a keystroke which is numeric when it should have been alpha,
  1231.      etc.  At the next level, it may sense a screen field that must be filled
  1232.      when it has not been.  At the next level, at the programmers option, Q-PRO
  1233.      4 branches to a segment of the program code.
  1234.  
  1235.      It's Magic
  1236.      ----------
  1237.      How is this magic done?  The Q-PRO 4 entry screen is a set of
  1238.      fill-in-the-blanks fields which, at the option of the programmer, may or
  1239.      may not be enterable by the operator.  Normally, the screen is set up as a
  1240.  
  1241.  
  1242.                                        Overview
  1243.                                           7
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.      true fill-in-the-blanks type which closely resembles the form the user is
  1252.      accustomed to.  The programmer completes a short form on the screen which
  1253.      defines the field.  This definition sets the attributes of the field; such
  1254.      as its name, length, alpha only, numeric only, justification, may enter,
  1255.      must enter, etc.
  1256.  
  1257.      If the operator types a numeric in an alpha only field, Q-PRO 4 detects it,
  1258.      halts entry and displays an error message.  The keyboard is disabled except
  1259.      for the ESCAPE key.  The bad character will not be displayed.  Pressing the
  1260.      ESCAPE key will turn control back to the operator.  In this manner, Q-PRO 4
  1261.      forces correct entry according to field definition without program
  1262.      intervention.
  1263.  
  1264.      The operator moves from entry field to entry field on the screen either by
  1265.      filling up the field or by pressing the RETURN key.  The RETURN key itself
  1266.      may be detected as an event.  If the field is properly entered, and a
  1267.      program segment is specified for the field, the program segment, called a
  1268.      procedure, will be executed.  
  1269.      Now the application is entirely under the control of the programmer.  The
  1270.      programmer may use any of the over 100 Q-PRO 4 commands to error check the
  1271.      field, search for and display a record from a file or any other tricky
  1272.      stuff that programmers are so fond of.
  1273.  
  1274.      Programmable Function Keys
  1275.      --------------------------
  1276.      This same capability allows Q-PRO 4 to detect 21 function keys, the enter
  1277.      key and other editing keys.  The programmer can do whatever his heart
  1278.      desires when one of these keys is pressed by the operator.  For example,
  1279.      F10 could terminate the application, F9 could display a help screen, etc.
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.                                        Overview
  1303.                                           8
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.      Another benefit of this approach is that, by use of screen field names or
  1312.      by symbolic notation, the screen fields may be examined for consistency. 
  1313.      And, calculations may be performed on the screen.
  1314.  
  1315.      Modern Commands
  1316.      ---------------
  1317.      All Q-PRO 4's commands are English-like and logically consistent in
  1318.      structure.  They always start with a verb, and are followed by an operand
  1319.      and optionally by a modifier.  Extended commands will have additional
  1320.      operands and additional modifiers.
  1321.  
  1322.      Databases Are Poor Relations
  1323.      ----------------------------
  1324.      Many so-called databases are entirely relational.  Q-PRO 4 applications may
  1325.      be set up relationally, hierarchically, or any other strange way that suits
  1326.      the programmer and the application.  We do not presume to know how your
  1327.      databases should be set up, but we do know that not all databases in an
  1328.      application are related!  For example, in a typical order entry
  1329.      application, the product database is rarely related to the sales person
  1330.      database.  
  1331.  
  1332.      They may or may not be related on a transaction.  The point is, of course,
  1333.      that you, the applications designer, are the only one who knows how the
  1334.      various databases work together.  Q-PRO 4's function is to give you the
  1335.      freedom to do it your way quickly and with the least possible systems and
  1336.      programming overhead.
  1337.  
  1338.  
  1339.  
  1340.  
  1341.  
  1342.  
  1343.  
  1344.  
  1345.  
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.  
  1354.  
  1355.  
  1356.  
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.                                        Overview
  1363.                                           9
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.                             Q - P R O 4   T U T O R I A L
  1372.                             =============================
  1373.  
  1374.      Q-PRO 4 Fundamentals
  1375.      --------------------
  1376.      Q-PRO 4 has three segments, the screens, the File Items Descriptor (or FID)
  1377.      and the program code.  The Binary WorkStation editor is used to create the
  1378.      entire application.  Actually, Binary WorkStation has three editors: one
  1379.      for program code, one for screens, and one for FIDs.
  1380.  
  1381.      Program Code
  1382.      ------------
  1383.      The program code is broken into segments called procedures or PROCs.  The
  1384.      program code editor of Binary WorkStation has the normal text editor
  1385.      capabilities you would expect of any text editor.  In addition, it has
  1386.      special features specifically for Q-PRO 4 programming.  Some of these
  1387.      features include:  a syntax checker, a macro code generator, and a file
  1388.      items descriptor (FID) generator.  Binary WorkStation is also a very good
  1389.      editor for text files.  
  1390.  
  1391.      When Binary WorkStation is first loaded the program code editor is
  1392.      executed.
  1393.  
  1394.      Screens 
  1395.      --------
  1396.      Screens are created in a what-you-see-is-what-you-get (WYSIWYG) mode with
  1397.      the screen editor portion of Binary WorkStation.
  1398.  
  1399.      You "paint" the background for the screen window.  This is the labels or
  1400.      operator prompts, colors and line graphics.  The labels are created by
  1401.      positioning the cursor where you want them and typing the text.  The lines
  1402.      are drawn by changing to the graphics mode.  Then they are drawn with the
  1403.      cursor left and right keys.  The intersections are placed with the function
  1404.      keys.  
  1405.         
  1406.      You define a data entry area or screen data field by pressing a function
  1407.      key to display the screen data field of the screen editor.  On this screen
  1408.      you specify the characteristics of the field and its primary edits such as
  1409.      width, type (alpha, numeric,etc.), may enter, must enter, may tab, must
  1410.      tab, etc.  
  1411.  
  1412.      As you will see, creating a dramatic, attractive screen for the user is a
  1413.      sheer delight.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.                                        Tutorial
  1423.                                           10
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.                                  Installing Q-PRO 4 
  1432.                                   ==================
  1433.  
  1434.      If you have not already done so, it is time to unpack and install Q-PRO 4. 
  1435.      Simply unarc the Q-PRO4.ARC file in the directory you are going to work in.
  1436.  
  1437.      Binary WorkStation has extensive help screens.  You can refer to them from
  1438.      any subdirectory where you happen to be if you use the DOS variable BWHLP. 
  1439.      Use this format in autoexec.bat: set bwhlp=<d>:<sub> (where <d> = drive and
  1440.      <sub> = subdirectory where Binary WorkStation is).
  1441.       
  1442.      Check for READ.ME
  1443.      -----------------
  1444.      The latest information about Binary WorkStation is on the Binary
  1445.      WorkStation diskette.  It is a plain ASCII file.  Please take a look at it.
  1446.  
  1447.  
  1448.  
  1449.                                    Example Program
  1450.                                    ===============
  1451.  
  1452.      About This Chapter 
  1453.      ------------------
  1454.      In this chapter, we will develop a small Q-PRO 4 application.  Although
  1455.      this application is simple, it is illustrative of the techniques used in
  1456.      many applications.  Additional material on technique is in the Hints, Tips
  1457.      & Techniques chapter and in the sample programs.
  1458.  
  1459.  
  1460.      Steps in Building a Q-PRO 4 Program
  1461.      -----------------------------------
  1462.  
  1463.           Step
  1464.       
  1465.           1.  Build the background
  1466.           2.  Define the data entry fields
  1467.           3.  Define the data files
  1468.           4.  Code the program
  1469.           5.  Run the program
  1470.  
  1471.      Usually we will take the steps in order, but there will be variations for
  1472.      clarity and flow.   
  1473.  
  1474.      Load Binary WorkStation
  1475.      ----------------------- 
  1476.      Change directory to the directory that Q-PRO 4 is on.  Load Binary
  1477.      WorkStation and tell it the program file you will be using by typing BW
  1478.      CUST.QNE (Note the space between BW and CUST.QNE) and then press RETURN. 
  1479.      The options screen will display.  Press RETURN.  You will be in the program
  1480.  
  1481.  
  1482.                                        Tutorial
  1483.                                           11
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489.  
  1490.  
  1491.      code editor portion of Binary WorkStation.  This is a blank screen that we
  1492.      will use later to write the procedural program code portion of the program.
  1493.  
  1494.      /------------------------------\
  1495.      |STEP 1 - Build the Background |
  1496.      \------------------------------/
  1497.  
  1498.      Press F8 to invoke the screen editor and display the screen.  A blank
  1499.      screen will display.  Visualize the screen as a clean page to draw your
  1500.      form on.
  1501.  
  1502.           About Backgrounds
  1503.           -----------------
  1504.           The background is our term for the constant material on the screen. 
  1505.           This material is variously referred to as "prompts", "labels",
  1506.           "operator information", . . .
  1507.  
  1508.           In Q-PRO 4, the background most often emulates the pre-printed portion
  1509.           of a printed form.  
  1510.  
  1511.      Move the cursor on the screen using your system cursor control keys and
  1512.      type the text until your screen looks like the one following.  Remember,
  1513.      with Binary WorkStation, you have insert character and line, delete
  1514.      character and line, etc.  The composition of the screen is "free-form" so
  1515.      feel free to arrange it for the best effect on your screen.  Leave some
  1516.      room in the bottom third of the screen for additions to be made later.  
  1517.  
  1518.      You should generally follow this layout:
  1519.  
  1520.      /-------------------------------------------------------------------------\
  1521.      |                                                                         |
  1522.      |                                                                         |
  1523.      |                        ENTER NEW CUSTOMERS                              |
  1524.      |                                                                         |
  1525.      |                                                                         |
  1526.      |      Name:                                                              |
  1527.      |                                                                         |
  1528.      |      Street and Number:                                                 | 
  1529.      |                                                                         |
  1530.      |      City:                                 State:    ZIP:               |
  1531.      |                                                                         | 
  1532.      |                                                                         |
  1533.      |                                                                         |
  1534.      |                                                                         |
  1535.      |                                                                         |
  1536.      |                                                                         |
  1537.      |                                                                         |
  1538.      |                        ESC - To Exit to System                          |
  1539.      |                                                                         |
  1540.  
  1541.  
  1542.                                        Tutorial
  1543.                                           12
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.      |                                                                         |
  1552.      \-------------------------------------------------------------------------/
  1553.  
  1554.  
  1555.                               Graphics and Highlighting
  1556.                               =========================
  1557.  
  1558.      You can enhance the readability and make a more dramatic presentation on
  1559.      the screen by using line graphics and highlighting.  Highlighting and
  1560.      business graphics depend on the computer or terminal you are using.  Not
  1561.      all support these features.
  1562.  
  1563.      Business Graphics
  1564.      -----------------
  1565.      To put business graphics on the window: 
  1566.  
  1567.           1.   Press FUNCT 0 (Funct 10 on the IBM-PC) to put Binary WorkStation
  1568.                in the graphics mode.
  1569.           2.   Use the cursor controls to draw horizontal and vertical lines and
  1570.                the function keys to print the corners and intersections.  See
  1571.                the Binary WorkStation section for more details.
  1572.  
  1573.      Highlighting
  1574.      ------------
  1575.      Highlighting takes one character position on the screen.  You must make
  1576.      allowance for this when you use highlighting.  To highlight:
  1577.  
  1578.           1.   Place the cursor to the left of the background field that you
  1579.                want to highlight and press F3, the highlight on key.
  1580.  
  1581.  
  1582.           2.   Move the cursor to the right of the field to be highlighted. 
  1583.                Press the highlight off key, F4.
  1584.  
  1585.      The text between the highlight on character and the highlight off character
  1586.      will be highlighted.  On some machines, such as the IBM-PC, the machine
  1587.      will not know that the highlight exists until you go back to the menu by
  1588.      pressing ESCAPE and then re-display the screen by pressing menu F8.
  1589.  
  1590.  
  1591.      /------------------------------\
  1592.      |STEP 2 - Define Fields        |
  1593.      \------------------------------/
  1594.  
  1595.  
  1596.      Q-PRO 4 Data Entry Fields
  1597.      -------------------------
  1598.      One of Q-PRO 4's strongest features is its use of data entry fields. 
  1599.      Overall, they emulate the blanks to be filled in on a preprinted form.
  1600.  
  1601.  
  1602.                                        Tutorial
  1603.                                           13
  1604.  
  1605.  
  1606.  
  1607.  
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.      To Enter or Not
  1614.      ---------------
  1615.      As you will see, defining them is simplicity itself; there is no coding and
  1616.      the fields are easily moveable.  Screen data fields may or may not be
  1617.      enterable by the operator.  Or, they may be created enterable and then made
  1618.      nonenterable!
  1619.  
  1620.      Primary Edits
  1621.      -------------
  1622.      At the time the fields are defined, primary edits are also defined: 
  1623.      alpha/numeric only, may enter, must enter, must fill, etc.  Again, there is
  1624.      no program code and the primary edits may be changed at any time.
  1625.       
  1626.      Field Definition
  1627.      ----------------
  1628.      Move the cursor to the right of the colon(:) following CUSTOMER NUMBER. 
  1629.      Press F1.  The form below will be displayed.  As you see, it is arranged in
  1630.      columns.  You define the field by describing it in each column.  Here is
  1631.      how you do it: 
  1632.  
  1633.      Column      Your Entry             Meaning
  1634.      ------      ----------   ------------------------------------------------- 
  1635.      Field name     NAME      From now on, Q-PRO 4 will use the identifier NAME
  1636.                               to refer to the contents of this screen data
  1637.                               field.  In other words, NAME is now a variable in
  1638.                               your program.  See the Naming Conventions Section
  1639.                               in the Q-PRO 4 Reference Manual for a full explan-
  1640.                               ation of naming conventions.  Press the TAB key.
  1641.  
  1642.      Len.           30        This specifies that up to thirty characters will
  1643.                               be allowed in the NAME screen data field.  As we
  1644.                               progress, you will see how the screen data field
  1645.                               definition will narrow the operator's choices.
  1646.                               Press the TAB key twice to skip to Type. 
  1647.      Row            <tab>     This is the row coordinate.  It is already filled
  1648.                               in for you.  Pressing tab skips over it.
  1649.  
  1650.      Col            <tab>     The column coordinate is filled in for you.
  1651.  
  1652.      Type           <tab>     The Type descriptor is a two character field.  The
  1653.                               first character forces the operator to put in the
  1654.                               correct type of data.  As we will allow anything
  1655.                               here just press TAB. Refer to the Quick Reference
  1656.                               Card for the meaning of all the field descriptor
  1657.                               codes.  The second character may be blank, equal
  1658.                               sign (=) for autoduplication, or question mark (?)
  1659.                               for an invisible field
  1660.  
  1661.  
  1662.                                        Tutorial
  1663.                                           14
  1664.  
  1665.  
  1666.  
  1667.  
  1668.  
  1669.  
  1670.  
  1671.  
  1672.  
  1673.      Just           L         This field specifies the justification.  The L
  1674.                               will cause data entered in the screen data field
  1675.                               to be left justified.
  1676.  
  1677.      Fill Char      <tab>     Frequently numeric fields are right justified and
  1678.                               use a zero (0) as a leading character.  You may
  1679.                               specify any leading character.  Do not use a
  1680.                               number sign (#) until you read about it in the
  1681.                               Programmer's Reference Manual.
  1682.  
  1683.  
  1684.      May Ent.       Y         Since we are going to allow entry, put a "Y" here.
  1685.  
  1686.  
  1687.      Must Ent.      Y         We want to force the user to put something here.
  1688.  
  1689.      Must Fill      N         The user does not have to completely fill the
  1690.                               field.
  1691.  
  1692.      Must Tab       N         We are not going to require the user to press tab
  1693.                               to leave the field. 
  1694.  
  1695.      Procedure
  1696.       Name          <tab>     At the moment we are not going to write a
  1697.                               procedure for this field.
  1698.  
  1699.                * * * You are now finished defining the field NAME * * * 
  1700.  
  1701.      Press ENTER to return to the background screen.  The previously typed
  1702.      screen is displayed again.  The NAME screen data entry field looks like
  1703.      this:
  1704.  
  1705.  
  1706.      NAME :   ################
  1707.  
  1708.      The number signs (###) indicate the presence of a defined screen data field
  1709.      and its length.  We will refer to these defined fields as screen data
  1710.      fields.
  1711.  
  1712.      Use the same procedure for all the other fields on the screen using the
  1713.      field specifications below.
  1714.  
  1715.      Screen  Field                            Fill  May Must Must Must Proceed
  1716.      Label   Name      Len  Row Col Type Just Char. Ent Ent  Fill  Tab   Name
  1717.      ------ |----------------------------------------------------------------
  1718.      NAME   |  NAME    30                 L          Y    N    N     N
  1719.      STREET |  STREET  30                 L          N    N    N     N
  1720.  
  1721.  
  1722.                                        Tutorial
  1723.                                           15
  1724.  
  1725.  
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.      CITY   |  CITY    20                 L          N    N    N     N
  1732.      STATE  |  STATE    2             A   L          Y    N    Y     N
  1733.      ZIP    |  ZIP      5             D   L          Y    Y    Y     Y
  1734.                                                          
  1735.  
  1736.      Note:  when a field format definition for every field has been entered,
  1737.      this segment of the program is complete.  Press F8 to return to the coding
  1738.      section.
  1739.  
  1740.      Press Control and U at the same time.  This dialog screen will display:
  1741.  
  1742.      /-------------------------------------------------------------------\
  1743.      |                                                                   |
  1744.      |  Save this file? [Y]         Save in Q-PRO 4 format? [Y]          |
  1745.      |                                                                   |
  1746.      |  File name [CUST.QNE                                  ]           |
  1747.      \-------------------------------------------------------------------/
  1748.  
  1749.      * * *  MAKE SURE THAT the first two questions are answered - Y. ****
  1750.  
  1751.      Press enter.   
  1752.  
  1753.  
  1754.      /---------------------------------\
  1755.      | STEP 2a - Run the Screen Program |
  1756.      \---------------------------------/
  1757.  
  1758.      1.   Press ENTER.  Press F8.  You will be moved to the program code editor.
  1759.  
  1760.      2.   Hold the CTRL key down and press U.  Press ENTER when the dialog
  1761.           screen displays.
  1762.      3.   Hold the CTRL key down and press Q.  When the dialog screen is
  1763.           displayed, press RETURN to run your program.  It will be loaded by the
  1764.           runtime interpreter (QNE.EXE), and execution will begin.  The data
  1765.           entry screen that you have built will be displayed ready for data
  1766.           entry.
  1767.  
  1768.      Entering Data
  1769.      -------------
  1770.      Begin typing data using the CURSOR RIGHT key or the ENTER key to go forward
  1771.      from data entry field to data entry field.  Use the SHIFT TAB key or the
  1772.      CURSOR LEFT key to go backwards from field to field.  If the data you key
  1773.      does not agree with the field specification, then an error message will be
  1774.      displayed.  To resume keying, press ESC.
  1775.  
  1776.      Changing Data
  1777.      -------------
  1778.      To change the data in a field, press the ENTER key to go forward or the
  1779.      Shift TAB key to go backward until you get to the correct field.  Either
  1780.  
  1781.  
  1782.                                        Tutorial
  1783.                                           16
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.      type over the previous data, or use the CLEAR TO END OF LINE (CONTROL END)
  1792.      key to erase the rest of the data in that field.  You may also use the
  1793.      INSERT/DELETE character keys.  Then type the correct data.
  1794.  
  1795.      Once you have entered all the data for a customer, press END.  The screen
  1796.      will clear for additional entries.
  1797.  
  1798.      When you have finished, press ESC to return to Binary WorkStation.
  1799.       
  1800.  
  1801.      ***  NOTE:  no data that has been typed on the screen will actually be 
  1802.           written on a data file because the data files and data file
  1803.           handling have not yet been programmed.
  1804.  
  1805.  
  1806.      /-----------------------------------\
  1807.      |  STEP 3 - Define the Data Files   |
  1808.      \-----------------------------------/
  1809.  
  1810.      FID Generator
  1811.      -------------
  1812.      The data in a data file is arranged into fields which have names.  The File
  1813.      Item Description Generator, is used to create the file, called a FID file,
  1814.      which contains the names of the fields in the data file.  The FID file is
  1815.      also used for creating and opening data files.  FID is a menu selection
  1816.      from Binary WorkStation.
  1817.  
  1818.      Select the FID generator by holding down the CNTL key and pressing V.  At
  1819.      the bottom of the screen, this line will display:
  1820.  
  1821.      FID Name or Number [                                   ]
  1822.  
  1823.      In the blank provided for FID Name or Number, type CUST.FID.  The FID
  1824.      definition screen will display.
  1825.  
  1826.      Current File [CUST.FID                            ]
  1827.        
  1828.        Item name    Len.  Type     Description                  Reps
  1829.      [           ] [   ]   [ ]   [                            ] [  ]
  1830.      [           ] [   ]   [ ]   [                            ] [  ]
  1831.      [           ] [   ]   [ ]   [                            ] [  ]
  1832.      [           ] [   ]   [ ]   [                            ] [  ]
  1833.           .
  1834.           .
  1835.           .
  1836.           .
  1837.      [           ] [   ]   [ ]   [                            ] [  ]
  1838.      [           ] [   ]   [ ]   [                            ] [  ]
  1839.      [           ] [   ]   [ ]   [                            ] [  ]
  1840.  
  1841.  
  1842.                                        Tutorial
  1843.                                           17
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.      [           ] [   ]   [ ]   [                            ] [  ]
  1852.  
  1853.  
  1854.      Creating the FID File
  1855.      ---------------------
  1856.      We will create a FID file using Quic FID.  This feature lets you create the
  1857.      FID to match the screen with no tedious typing.  We are assuming that the
  1858.      name of the application file you used in the previous sections was
  1859.      CUST.QNE.  
  1860.  
  1861.      Follow these steps:
  1862.      -------------------
  1863.       
  1864.      1.  Hold down the shift key and press F2.
  1865.      2   Enter the name of our format file: (CUST.QNE)
  1866.      3.  Press F4 (Update FID file) to save the FID file on disk. 
  1867.      4.  Press SHIFT F10 (Go to Binary WorkStation program code editor).
  1868.  
  1869.      Indexed or Random
  1870.      -----------------
  1871.      The FID determines what type of file will be created when it is used by
  1872.      Q-PRO 4 to create a file.  If the FID is defined with a key (or keys), the
  1873.      data file will be indexed.  If no keys, the data file will be random.
  1874.  
  1875.      Keys in Indexed Data Files
  1876.      --------------------------
  1877.      The key is another term for the sequence of the indexed data file.  In the
  1878.      customer file, the name of the customer is the key.  When you enter
  1879.      customers, no matter what sequence that you enter them, the logical order
  1880.      will be alphabetic by customer.  For a more detailed discussion, see the
  1881.      section on FIDS in the FID Generator section of the Binary WorkStation
  1882.      Reference Chapter.
  1883.  
  1884.      /-----------------------------\
  1885.      | STEP 4 - Coding the Program |
  1886.      \-----------------------------/
  1887.  
  1888.                                   Language Structure
  1889.                                   ==================
  1890.      Event Driving
  1891.      -------------
  1892.      In a previous section we pointed out that Q-PRO 4 is event driven.  An
  1893.      event may be the operator pressing TAB to leave a screen data field or
  1894.      pressing a function key.  The application designer decides if this event
  1895.      will cause transfer to the command section of the program file.  The
  1896.      command section consists of procedures.
  1897.  
  1898.  
  1899.  
  1900.  
  1901.  
  1902.                                        Tutorial
  1903.                                           18
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.      Procedures
  1912.      ----------
  1913.      The procedure, or PROC, is a series of Q-PRO 4 commands.  It may be
  1914.      specific to a screen data field or function key or more global like a
  1915.      subroutine.  When control is transferred to it, the procedure executes its
  1916.      commands and, at the application designer's option, returns control to the
  1917.      screen.  Thus, the application designer always has control.  Procedures
  1918.      have names to identify them.
  1919.       
  1920.      Linkage
  1921.      -------
  1922.      The PROCs are linked to the screen data field by the entry on the screen
  1923.      data field definition line for Proc Name (field procedure name), wherein a
  1924.      PROC name is entered.  When the operator has gotten over the primary
  1925.      hurdles, MUST ENTER, MUST FILL, etc. and presses TAB, the PROC named in
  1926.      Proc Name will be executed.  This is how Q-PRO 4 knows what procedure to
  1927.      execute for this event or the linkage from the keyboard/screen to the
  1928.      commands.
  1929.  
  1930.  
  1931.                                    Using the Editor
  1932.                                    ----------------
  1933.  
  1934.      Overview
  1935.      --------
  1936.      Binary WorkStation is a complete text editor.  Like most text editors, it
  1937.      has full facilities for entering, deleting, modifying and moving text.
  1938.  
  1939.      In general, all you need do is type in the code.  The following is a
  1940.      thumbnail description of the key facilities of Binary WorkStation:
  1941.  
  1942.      Modes
  1943.      -----
  1944.      There are two overall modes, INSERT ON and INSERT OFF.  When insert is ON,
  1945.      each keystroke will add a character or insert one where the cursor is. 
  1946.      When insert is OFF if there is a character where the cursor is, it will be
  1947.      struck over.
  1948.  
  1949.      Line Wrap
  1950.      ---------
  1951.      As opposed to word processing editors, there is no line wrap.  You can keep
  1952.      typing to the allowable width of the line, 256 characters.  Use the ENTER
  1953.      key to terminate the line.  For a more complete explanation refer to the
  1954.      Binary WorkStation section in this manual.
  1955.  
  1956.      Bottom Line Menu
  1957.      ----------------
  1958.      Binary Workstation uses a bottom line menu.  That is the bottom line of the
  1959.      screen lists the functions that will be executed when the respective
  1960.  
  1961.  
  1962.                                        Tutorial
  1963.                                           19
  1964.  
  1965.  
  1966.  
  1967.  
  1968.  
  1969.  
  1970.  
  1971.      function key is pressed.  A new set of functions is displayed when F10 is
  1972.      pressed and the previous set is displayed when F9 is pressed.  Any function
  1973.      may be executed, regardless of what is displayed, by pressing its
  1974.      associated key.  For example CNTL Q runs the program. 
  1975.  
  1976.  
  1977.  
  1978.                                       PROC LOAD
  1979.                                       ---------
  1980.  
  1981.      PROC LOAD is the procedure that is always executed first.  It is used to
  1982.      initialize conditions for the program, open files, etc.   
  1983.  
  1984.      Coding PROC LOAD
  1985.      ----------------
  1986.      In this example, PROC LOAD will open the data file.  If it cannot open the
  1987.      data file then it will assume that the data file is not there and create
  1988.      it.  In later sections we will make PROC LOAD a little smarter.  
  1989.  
  1990.      Type the lines show below which are boldfaced.
  1991.  
  1992.      PROC LOAD
  1993.                Procedure executed at the time the program loads.
  1994.  
  1995.      OPEN "CUST.DAT" USING "CUST.FID"  , 1:NO_FILE
  1996.                Open a file named CUST.DAT.  Use the data dictionary or FID,
  1997.                CUST.FID.  From now on we will refer to this file by the number
  1998.                1.  If successful, execute the next sequential command.  On
  1999.                error(i.e. could not open the file, possibly because it has not
  2000.                been created yet.) go to NO_FILE.  You may specify drives and/or
  2001.                paths in the file name,  e.g.  "/Q-PRO 4/CUST.DAT".
  2002.       
  2003.      END
  2004.                The data file was opened successfully.  The END statement gives
  2005.                control to the operator in the first enterable field. 
  2006.  
  2007.      :NO _FILE   MAKE "CUST.DAT" USING "CUST.FID",1:BAD
  2008.  
  2009.                Create CUST.DAT.  Structure it in accordance with the
  2010.                specifications in the data dictionary CUST.FID.  Assign it file
  2011.                number 1.  When created, go to the next sequential statement.  If
  2012.                it cannot be created, GOTO BAD and report the problem.
  2013.  
  2014.      END  
  2015.                On successful MAKE, turn over control to the operator.
  2016.  
  2017.      :BAD ERROR "UNABLE TO CREATE FILE"
  2018.  
  2019.                The ERROR command displays the message in quotes on line 24 of
  2020.  
  2021.  
  2022.                                        Tutorial
  2023.                                           20
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.                the screen. When the operator presses any key, control goes to
  2032.                the next sequential statement. 
  2033.  
  2034.      SYSTEM
  2035.                Although this statement will normally return you to the operating
  2036.                system, when you run the program from Binary WorkStation, your
  2037.                program will be reloaded ready for editing.
  2038.  
  2039.      END
  2040.                End of procedure.  Turn over control to the operator.
  2041.  
  2042.       
  2043.      Your proc should look like this:
  2044.  
  2045.      PROC LOAD
  2046.           FORMLOAD
  2047.           OPEN "CUST.DAT" USING "CUST.FID",1:NO
  2048.           END
  2049.      :NO MAKE "CUST.DAT" USING "CUST.FID",1:BAD
  2050.           END
  2051.      :BAD ERROR "UNABLE TO CREATE FILE"
  2052.                SYSTEM
  2053.                END
  2054.  
  2055.  
  2056.      Labels
  2057.      ------
  2058.      Labels, in Q-PRO 4, are simply places to jump to on various conditions. 
  2059.      They may be numeric or alphanumeric.  If they are alphanumeric, they follow
  2060.      the standard naming conventions discussed in the reference section. 
  2061.      Alphanumeric labels must have a colon (:) as the first character.
  2062.  
  2063.  
  2064.                                       PROC NAMEP
  2065.                                       ----------
  2066.  
  2067.      Function of the PROC
  2068.      --------------------
  2069.      When the user entirely fills the NAME field or presses TAB this PROC will
  2070.      execute.  It searches the database established in PROC LOAD and displays a
  2071.      customer record if there is a record on the file that exactly matches the
  2072.      name that is entered in the NAME FIELD.  
  2073.  
  2074.      Type only those lines which are boldfaced in the following procedure.
  2075.  
  2076.      PROC NAMEP  
  2077.                Defines the PROCedure NAMEP.
  2078.      POSN 1 TO NAME
  2079.                This statement positions the datafile to the contents of the
  2080.  
  2081.  
  2082.                                        Tutorial
  2083.                                           21
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.  
  2090.  
  2091.                screen data field, NAME.
  2092.  
  2093.      READ 1:NO_MATCH
  2094.                Read the record.  If there is an exact match between the file
  2095.                data field and the screen data field, load the file buffer with
  2096.                the record and execute the next command.  If there is not an
  2097.                exact match, go to NO_MATCH.
  2098.                For the purposes of retrieving a record from a file, an Exact
  2099.                match is understood to be a match, character by character, for
  2100.                both fields.
  2101.  
  2102.           COPY 1 TO *
  2103.                Copy all fields on the data file that have the same name as
  2104.                fields on the screen to the screen.  The 1 is the file number and
  2105.                the asterisk (*) is used to represent the screen.  This is one of
  2106.                the ways a data dictionary can work for you.  By simply selecting
  2107.                matching, or non-matching names, you can easily control what data
  2108.                is copied from what to what.  Of course, you can specify the
  2109.                movement a field at a time if you wish.
  2110.  
  2111.           NEXT
  2112.                Gives the operator control in the next enterable field, STREET.
  2113.  
  2114.                NOTE:  Other Q-PRO 4 statements that give control back to the
  2115.                operator are END, and RESUME.
  2116.  
  2117.      :NO_MATCH END
  2118.                If there is no matching record on the database terminate the
  2119.                PROC.  This gives control to the user in the next enterable
  2120.                field, STREET.  
  2121.  
  2122.      Your PROC should look like this:
  2123.  
  2124.      PROC NAMEP
  2125.                POSN 1 TO NAME
  2126.                READ 1:NO_MATCH
  2127.                COPY 1 TO *
  2128.                NEXT
  2129.      :NO_MATCH
  2130.  
  2131.      END
  2132.  
  2133.                                     Event Driving
  2134.                                     -------------
  2135.  
  2136.      The event which sets off looking for a particular name on file, i.e.
  2137.      executing PROC NAME, is the operator leaving the screen data field, NAME. 
  2138.      Normally the operator presses the TAB key.
  2139.  
  2140.  
  2141.  
  2142.                                        Tutorial
  2143.                                           22
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.      The Linkage
  2152.      -----------
  2153.      We need to establish the linkage between the event, i.e. tabbing out of
  2154.      screen data field NAME and executing PROC NAME.  The linkage is established
  2155.      as part of the field definition of the screen data field, NAME.  We will
  2156.      set this up now.
  2157.  
  2158.      Adding the Linkage
  2159.      ------------------
  2160.      From the program code editor, press SHIFT F8 to load the screens editor.
  2161.  
  2162.      The screen format that you've been working on will display.  Place the
  2163.      cursor on the #####'s after Name and press F1.  The Field Definition Screen
  2164.      will display.  
  2165.  
  2166.      Move the cursor to the right of the field NAME:.  Place it on the number
  2167.      signs (###), and press F1.  The FIELD FORMAT DEFINITION for the screen data
  2168.      field NAME will be displayed.  
  2169.  
  2170.      Tab to the right under Proc Name.  Type NAMEP.  This is the linkage to the
  2171.      interpreter.  When the operator presses TAB in the screen data field NAME,
  2172.      Q-PRO 4 sees NAMEP as the screen field procedure name and it looks for a
  2173.      procedure in the program code named NAMEP to execute some instructions.  If
  2174.      there is no procedure named NAMEP, an error will be reported.  You can't
  2175.      fool Q-PRO 4!
  2176.  
  2177.      Press ESC twice to return to the program code editor.
  2178.  
  2179.  
  2180.                                     Recording Data
  2181.                                     --------------
  2182.      PROC ENTER
  2183.      ----------
  2184.      This proc is executed when the designated ENTER key is pressed.  Most
  2185.      often, it is used when the data on screen is complete and the user wishes
  2186.      to record it.
  2187.  
  2188.      PROC ENTER
  2189.           This is the procedure invoked when the ENTER key is pressed. 
  2190.  
  2191.      COPY * TO 1
  2192.           Copy all the screen data fields to the file data fields of the same
  2193.           name. 
  2194.  
  2195.      WRITE 1 NOADV : BAD_WRITE
  2196.           Write the record, goto BAD_WRITE on error.  The NOADV keeps the file
  2197.           from advancing to the next record which saves time.   It is important
  2198.           to note here what gets written when this command is executed.  In the
  2199.           current example, the contents of the screen will be recorded on disk. 
  2200.  
  2201.  
  2202.                                        Tutorial
  2203.                                           23
  2204.  
  2205.  
  2206.  
  2207.  
  2208.  
  2209.  
  2210.  
  2211.           Because the key to the file is NAME, if you have entered a new name
  2212.           then a new record will be created.  If it is a name that is already on
  2213.           file, then that record will be updated to match the screen.
  2214.  
  2215.      END
  2216.           The screen will clear.  (This is automatic when the ENTER command
  2217.           reaches the END statement.)  Control is turned over to the operator in
  2218.           the CUSTNO field.
  2219.  
  2220.      :BAD_WRITE  ERROR "ERROR IN WRITING RECORD"
  2221.           Display the error message "ERROR IN WRITING RECORD" on line 24.  Turn
  2222.           over control to the operator until the ESC key is pressed.  When ESC
  2223.           is pressed, the next command will execute.
  2224.  
  2225.      SYSTEM
  2226.           Return to the operating system.
  2227.  
  2228.      END
  2229.           Here, the END is not really needed, but putting it in is good
  2230.           procedure.
  2231.  
  2232.      Your PROC should look like this:
  2233.  
  2234.      PROC ENTER
  2235.           COPY * TO 1 
  2236.           WRITE 1:BAD_WRITE
  2237.           END
  2238.      :BAD_WRITE     ERROR "ERROR IN WRITING RECORD"
  2239.           SYSTEM
  2240.           END 
  2241.  
  2242.  
  2243.      Running the Program
  2244.      -------------------
  2245.      Press CNTL U to update the program.  When the dialog screen displays, press
  2246.      ENTER.  Press CNTL Q.  When the dialog screen displays, press ENTER.
  2247.  
  2248.      Entering Data
  2249.      -------------
  2250.      Enter a name in the Customer field.  If the customer is already on the
  2251.      database, it will be retrieved from the file and displayed.  You can enter
  2252.      it as is or correct it and enter it.  
  2253.      ESC will return you to Binary WorkStation procedural code editor.
  2254.  
  2255.  
  2256.                                Finding and Fixing Bugs
  2257.                                -----------------------
  2258.  
  2259.      Returning to Binary Workstation
  2260.  
  2261.  
  2262.                                        Tutorial
  2263.                                           24
  2264.  
  2265.  
  2266.  
  2267.  
  2268.  
  2269.  
  2270.  
  2271.      -------------------------------
  2272.      Press ESC, which will bring you back to Binary WorkStation's program code
  2273.      editor.
  2274.  
  2275.      Correcting Screen data fields
  2276.      ----------------------------
  2277.      To change a screen data field, redisplay the field and change it by placing
  2278.      the cursor anywhere on the number signs and press F1.  The field definition
  2279.      screen will be displayed with the previous entries.
  2280.  
  2281.      You may change any of them by moving the cursor with the TAB key and making
  2282.      the change.  Press ENTER to return to the data entry screen.
  2283.  
  2284.      Syntax Checker
  2285.      --------------
  2286.      With the Binary WorkStation loaded, press CNTL W.  Your program will be
  2287.      checked for correct syntax.
  2288.  
  2289.      If any errors are found, the syntax checker will stop at the first one. 
  2290.      Use the editing keys INSERT CHARACTER, DELETE CHARACTER, INSERT LINE, and
  2291.      DELETE LINE, etc to correct the error.
  2292.  
  2293.      Press CNTL W again.  Continue to syntax check and correct until no more
  2294.      syntax errors are detected.
  2295.  
  2296.      Line Numbers
  2297.      ------------
  2298.      Binary WorkStation does not use line numbers to organize itself.  The line
  2299.      numbers are normally not even displayed.  They are used as an aid to
  2300.      debugging.  When an error is reported by the interpreter, it will refer to
  2301.      a line number.  You can display the line numbers with Binary Workstation to
  2302.      find the offending line of code.
  2303.  
  2304.      Labels
  2305.      ------
  2306.      Numeric and alphanumeric labels are merely labels to jump to.  However,
  2307.      remember that a label can be jumped to even if it is not within the
  2308.      procedure that references it.
  2309.  
  2310.  
  2311.                           Adding Programmable Function Keys
  2312.                            --------------------------------
  2313.  
  2314.      General Description
  2315.      -------------------
  2316.      Q-PRO 4 recognizes 21 programmable function keys, 0 to 20.  Each key is
  2317.      associated with a specific PROC, PROC KEY0-20.  The PROC associated with
  2318.      the key executes immediately.  For example, on the IBM PC, pressing
  2319.      function key, F1 executes the proc KEY1; PROC KEY11 is invoked with Shift
  2320.  
  2321.  
  2322.                                        Tutorial
  2323.                                           25
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.      F1.  
  2332.  
  2333.      Functionality
  2334.      -------------
  2335.      The proc can do anything you wish it to do.  Some of the more common uses
  2336.      are:  advancing and backspacing a single record in a file, deleting
  2337.      records, special searches, and chaining to other screens.
  2338.  
  2339.      Pre-defined Function Key
  2340.      ------------------------
  2341.      PROC KEY0 is pre-defined with the following code:
  2342.  
  2343.           CLOSE
  2344.           SYSTEM
  2345.           END
  2346.  
  2347.      It is invoked with the ESC key.  You need not define it if closing the
  2348.      files and going to the operating system are what you want it to do. 
  2349.      Otherwise program this key as any other.   
  2350.  
  2351.      Examples
  2352.      --------
  2353.      We suggest that you add the examples below to your program to enhance its
  2354.      functionality.
  2355.  
  2356.      First let's write a simple subroutine that will save us some time later. 
  2357.      This subroutine reads and displays a record.
  2358.  
  2359.  
  2360.  
  2361.      PROC KEY_READ
  2362.           READ 1:EF
  2363.                Advance the file pointer one record.  If there is an error,
  2364.                presumably an End of File, goto EF.
  2365.  
  2366.           COPY 1 TO *
  2367.                Copy the fields with the same names in the data file as on the
  2368.                screen to the screen.
  2369.  
  2370.           RETURN
  2371.                Return to the main program at the next instruction after the
  2372.                calling statement.
  2373.  
  2374.      :EF  ERROR "No more records" 
  2375.                RETURN
  2376.  
  2377.      Example: Display Next Record
  2378.  
  2379.      PROC KEY1
  2380.  
  2381.  
  2382.                                        Tutorial
  2383.                                           26
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.  
  2391.           CALL KEY_READ
  2392.           END
  2393.           This example takes advantage of the characteristics of an indexed
  2394.           file.  The READ command will advance the file one logical record in
  2395.           the logical sequence or key. 
  2396.  
  2397.      Example: Display Previous Record
  2398.  
  2399.      PROC KEY2
  2400.           BACKSPACE 1:EF
  2401.           BACKSPACE 1:EF
  2402.                When a record is read, the record pointer is pointing to the next
  2403.                record.  Therefore to backspace preparing to read the previous
  2404.                record, you must backspace twice.  We have used the end of file
  2405.                routine from PROC KEY1 which it won't mind.  
  2406.        
  2407.           CALL KEY_READ
  2408.           END
  2409.  
  2410.      Example:  Delete the Currently Displayed Record
  2411.  
  2412.      PROC KEY11
  2413.           POSN 1 TO NAME USING 1
  2414.                Position the file to the contents of NAME in the primary key.  We
  2415.                want to insure that in all circumstances the record to be deleted
  2416.                actually exists. 
  2417.       
  2418.           CALL KEY_READ
  2419.  
  2420.                If the record does not exist, then the READ statement in KEY_READ
  2421.                will cause the file to go to end of file.  
  2422.  
  2423.           FREE 1
  2424.                The record currently in the buffer, i.e. the one just read, will
  2425.                be marked deleted.  This logically removes the record from the
  2426.                database.
  2427.           END
  2428.  
  2429.  
  2430.                                 Partial Key Searching
  2431.                                 ---------------------
  2432.  
  2433.      Capabilities
  2434.      ------------
  2435.      One of the more powerful features of Q-PRO 4 is partial key searching. 
  2436.      This feature allows you to get the "nearest" match for a key search.
  2437.  
  2438.      Now you can look up a customer name if you only know the first letter of
  2439.      the name.  For those of us who have occasional memory lapses, this is the
  2440.  
  2441.  
  2442.                                        Tutorial
  2443.                                           27
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.      greatest.  If you can't remember without seeing the whole record whether it
  2452.      is Smith, Smithson, or Smyth.  
  2453.  
  2454.      As an example, in our customer program, with partial key searching you just
  2455.      type "Sm" and press a function key.  The record for Smith will be
  2456.      displayed.  Using the next and previous function keys lets you browse the
  2457.      data.  
  2458.  
  2459.      Example: Partial Key Searching
  2460.  
  2461.      PROC KEY3
  2462.           POSN 1 TO NAME RELATIVE 
  2463.                The RELATIVE modifier tells Q-PRO 4 to search for an exact match
  2464.                for the contents of the screen data field, NAME, or the nearest
  2465.                next higher match.  Therefore an entry of Sm will bring up the
  2466.                first of the series.
  2467.  
  2468.           CALL KEY_READ
  2469.           END 
  2470.  
  2471.      Example: Position to Beginning of File
  2472.      PROC KEY7
  2473.           POSN 1 TO  "" RELATIVE
  2474.                Positioning the file to a null (double quotes, single or double,
  2475.                with no space between them) RELATIVE  positions it to the first
  2476.                record of the file.
  2477.  
  2478.  
  2479.  
  2480.  
  2481.  
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.                                        Tutorial
  2503.                                           28
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.                                Hints, Tips & Techniques
  2512.                               =========================
  2513.  
  2514.  
  2515.      Inherent Structure
  2516.      ------------------
  2517.      Because Q-PRO 4's PROC's are inherently structured, there is not much to do
  2518.      to organize your programs.  However, you might find it helpful to group
  2519.      various type of procs such as function key procs, subroutines, etc.
  2520.      together with an appropriate section heading.  If you use an asterisk to
  2521.      preface the heading, Q-PRO 4 will think it is a comment.  An example of
  2522.      this technique:
  2523.  
  2524.      * * * * * * * *  Field Procedures * * * * * * * * * * * 
  2525.  
  2526.      PROC NAMEP
  2527.                POSN 1 TO NAME
  2528.                READ 1:NO_MATCH
  2529.                COPY 1 TO *
  2530.                NEXT
  2531.      :NO_MATCH END
  2532.  
  2533.  
  2534.      * * * * * * * * Function Key Procedures * * * * * * * * * 
  2535.  
  2536.      PROC KEY1
  2537.           CALL KEY_READ
  2538.           END
  2539.  
  2540.      PROC KEY2
  2541.           BACKSPACE 1:EF
  2542.           BACKSPACE 1:EF
  2543.           CALL KEY_READ
  2544.           END
  2545.  
  2546.      PROC KEY11
  2547.           POSN 1 TO NAME USING 1
  2548.           CALL KEY_READ
  2549.           FREE 1
  2550.           END
  2551.  
  2552.  
  2553.                                    Sample Programs
  2554.                                    ---------------
  2555.  
  2556.      Using the Sample Programs
  2557.      -------------------------
  2558.      The sample programs comprise a demonstration invoicing system including the
  2559.      programs and some sample data.  The programs are designed to demonstrate
  2560.  
  2561.  
  2562.                                        Tutorial
  2563.                                           29
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.      some overall technique of programming with Q-PRO 4.  As demonstrations,
  2572.      they are not necessarily the best code for they were developed to
  2573.      demonstrate certain functions.  We recommend that you run them and look at
  2574.      the code.
  2575.  
  2576.      You may create your own data or use the sample data provided.  SAMPINS.DAT
  2577.      and SAMPINS.FID must be on the same directory as  the program files.  All
  2578.      other data and the FID files may be on any directory as long as all reside
  2579.      in the same directory.
  2580.  
  2581.      SAMPINS.QNE    You must run this program first.  It sets up the application
  2582.                     control file.  In this program you use a one record random
  2583.                     file to specify the system parameters such as:
  2584.  
  2585.                     o Password (and its encryption) 
  2586.                     o Company name and address
  2587.                     o Operating system
  2588.                     o Host
  2589.                     o Path for data files and FID files
  2590.  
  2591.                If the HOST and the operating system are not set correctly, then
  2592.                things will not work right.
  2593.  
  2594.      SAMPMAKE.QNE   This program is chained to from SAMPINS.QNE.  Use it to
  2595.                     create new data files.  If you create data files, the sample
  2596.                     files furnished will be deleted.  It illustrates:
  2597.  
  2598.                     o Safely creating data files
  2599.                     o Operator-program dialog
  2600.                     o Use of application control file parameters           
  2601.  
  2602.      SAMPMENU.QNE   This is the main menu for the program.  It illustrates:
  2603.  
  2604.                     o How to use the application control file for determining
  2605.                     the HOST, operating system and where the data and FID files
  2606.                     are. 
  2607.                     o How to get and use a password from the user.
  2608.                     o How to determine if the password has already been given so
  2609.                     it will not be asked for again.
  2610.                     o Chaining to other programs.   
  2611.       
  2612.      SAMPCUST.QNE   This program maintains the customer database.  From it you
  2613.                     can add a new customer, change a customer or delete a
  2614.                     customer.  It illustrates:
  2615.  
  2616.                     o Determining if a file is already open before attempting to
  2617.                     open it.
  2618.                     o Scrolling forward and backward in a data file by either of
  2619.                     two keys. 
  2620.  
  2621.  
  2622.                                        Tutorial
  2623.                                           30
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.                     o Duplicating repetitive data without rekeying.
  2632.  
  2633.      SAMPROD.QNE    This program maintains the product data base.  Use it to
  2634.                     add, delete or change products.  It illustrates:
  2635.                     o Determining if a file is already open before attempting to
  2636.                     open it.
  2637.                     o Scrolling forward and backward in a data file by either of
  2638.                     two keys. 
  2639.  
  2640.      SAMPEN.QNE     This program is the first of two programs that write an
  2641.                     invoice.  It is used to put in the bill head information. 
  2642.                     It illustrates:
  2643.                     o Use of the application control file to assign invoice
  2644.                     numbers.
  2645.                     o Use of PROC BREAK.
  2646.                     o Using multiple screens to enter data to one file.
  2647.  
  2648.      SAMPEN1.QNE    This is the second program for writing an invoice.  It
  2649.                     creates the line items of the invoice.  It illustrates:
  2650.                     o Screen scrolling
  2651.                     o Printing from Q-PRO 4 (as opposed to the report generator)
  2652.                     o Multiple records for a screen
  2653.  
  2654.  
  2655.                                 Advanced Input Editing
  2656.                                 ----------------------
  2657.  
  2658.      Capabilities
  2659.      ------------
  2660.      The only limit on the ways you can edit data as it is input is your
  2661.      imagination.  Some of the more common methods are:
  2662.  
  2663.           o Range checks
  2664.           o Table lookup
  2665.           o Comparison to other fields
  2666.           o File lookup
  2667.  
  2668.      Screen Data Field Edit Example:
  2669.           Range check of the screen data field, ZIP.
  2670.  
  2671.      PROC RANGE
  2672.           IF ZIP GE 10000 AND ZIP LE 90000 END
  2673.                End the procedure if the Zip code is in the range  10000 to
  2674.                90000. (GE = greater than or equal to, LE = less than or equal
  2675.                to.)
  2676.  
  2677.           ERROR "ZIP  outside Range."
  2678.                 Put a message on line 24 for the operator.
  2679.  
  2680.  
  2681.  
  2682.                                        Tutorial
  2683.                                           31
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.           CLEAR $FIELD[#F]
  2692.                Clear the current screen data field.  The function,
  2693.                $FIELD[<expression>], refers to the screen data field whose
  2694.                offset is calculated in the <expression>.  A screen data field's
  2695.                offset is the number of fields from the first screen data field
  2696.                (whose offset is zero) counting from left to right, top to
  2697.                bottom.  One of the valid arguments in the expression is #F, the
  2698.                current screen data field offset.  
  2699.  
  2700.           RESUME
  2701.                Give control back to the operator in the current field.
  2702.  
  2703.      Screen Data Field Edit Example: 
  2704.           Table look up of the verification of the screen data field, State
  2705.  
  2706.      PROC TABLE_LOOK
  2707.           TSEAR OK_STATES AT STATE:NO_ST
  2708.                Search the table OK_STATES using the contents of the field,
  2709.                STATE.  If there is a match, goto the next command.  If there is
  2710.                no match, goto NO_ST.
  2711.           END
  2712.                Found  a  match, end proc.
  2713.  
  2714.      :NO_ST    ERROR "Don't use this state. "
  2715.                Display instructions on line 24 of the CRT.
  2716.  
  2717.           RESUME
  2718.  
  2719.           TABLE OK_STATES
  2720.                "PA"
  2721.                "CA"
  2722.                "DE"
  2723.            END
  2724.  
  2725.                This table specifies only these three states.
  2726.  
  2727.      Screen Data Field Edit Example:
  2728.           Comparisons between fields.
  2729.  
  2730.      PROC COMPARE
  2731.           IF STATE = "PA" AND ZIP LT 50000 GOTO ST_ERR
  2732.                If the contents of the screen data field, STATE, is "PA" and the
  2733.                contents of the screen data field, ZIP, is less than 50000, goto
  2734.                the label ST_ERR
  2735.  
  2736.      Screen Data Field Edit Example:
  2737.           File verification of the field, ZIP.
  2738.  
  2739.      PROC FILE_CHK
  2740.  
  2741.  
  2742.                                        Tutorial
  2743.                                           32
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.           POSN 1 TO ZIP USING 2
  2752.                Change the file key of file 1 to the second key, ZIP. (You will
  2753.                see how to change file structures to put in additional keys in a
  2754.                later section.)  Position file 1 to the contents of the screen
  2755.                data field, ZIP.
  2756.  
  2757.           READ 1:NO_ZIP
  2758.                Read file 1.  If there is an exact match, execute the next
  2759.                sequential command.  If there is no exact match, goto NO_ZIP.
  2760.  
  2761.           KEY 1 USING 1
  2762.                Set the key back to the primary key.
  2763.           END
  2764.  
  2765.      :NO_ZIP  ERROR "This ZIP CODE is not authorized"
  2766.                CLEAR $FIELD[#F]
  2767.                KEY 1 USING 1
  2768.                RESUME
  2769.  
  2770.  
  2771.  
  2772.                                    Screen Handling
  2773.                                    ---------------
  2774.  
  2775.      Screen Graphics
  2776.      ---------------
  2777.      For certain systems (as noted in the quick reference card paste-ins), block
  2778.      or business graphics are available for enhancing the screen presentation. 
  2779.      Scrolling the Binary WorkStation menu in the screen editor mode allows
  2780.      turning graphics mode on.  While in the graphics mode the function keys
  2781.      function as shown below:
  2782.  
  2783.           CURSOR LEFT, RIGHT  HORIZONTAL SEGMENT
  2784.           CURSOR UP, DOWN     VERTICAL SEGMENT
  2785.           FUNCT 9   T RIGHT
  2786.           FUNCT 8   T LEFT
  2787.           FUNCT 7   T DOWN
  2788.           FUNCT 6   T UP
  2789.           FUNCT 5   CENTER CROSS
  2790.           FUNCT 4   LOWER RIGHT CORNER
  2791.           FUNCT 3   LOWER LEFT CORNER
  2792.           FUNCT 2   UPPER RIGHT CORNER
  2793.           FUNCT 1   UPPER LEFT CORNER
  2794.           FUNCT 10  TOGGLE GRAPHICS MODE ON/OFF
  2795.  
  2796.  
  2797.      Screen Data Fields - Editing Rows and Columns
  2798.      ---------------------------------------------
  2799.      Row/Column coordinates are usually skipped after entering the FIELD NAME. 
  2800.  
  2801.  
  2802.                                        Tutorial
  2803.                                           33
  2804.  
  2805.  
  2806.  
  2807.  
  2808.  
  2809.  
  2810.  
  2811.      When you skip these fields, Binary WorkStation calculates the coordinates
  2812.      for you.
  2813.  
  2814.      The coordinates may be "forced" by entering the actual coordinates.  This
  2815.      is useful for moving a variable field to another place on the screen to
  2816.      quickly customize a display.
  2817.  
  2818.      Correcting Screen Data Fields
  2819.      -----------------------------
  2820.      To change a screen data field, redisplay the field and change it by placing
  2821.      the cursor anywhere on the number signs and press F1.  The field definition
  2822.      screen will be displayed with the previous entries.
  2823.  
  2824.      You may change any of them by moving the cursor with the TAB key and making
  2825.      the change.  Press ENTER to return to the data entry screen.
  2826.  
  2827.      Screen Offset
  2828.      -------------
  2829.      The screen offset allows the programmer to address the screen data fields
  2830.      as offsets from the first screen data field.  Thus, the programmer may
  2831.      symbolically select fields on the screen according to the program logic or
  2832.      table look-up.
  2833.  
  2834.      The offset value for each screen data field is shown on the program
  2835.      listing.  It is no more than the number of fields from the first screen
  2836.      data field counting from left to right, top to bottom.  With this logic,
  2837.      the first screen data field at the upper left has an offset of 0. The one
  2838.      next to it on the same line has an offset of 1, etc.
  2839.  
  2840.      The field is addressed by the function $FIELD.  $FIELD allows handling of
  2841.      fields on the screen by offset value without worrying about the name of the
  2842.      field.  The combination of loops, registers and tables provides
  2843.      extraordinary screen handling capability.
  2844.  
  2845.      Example: 
  2846.  
  2847.      MOVE $FIELD[6] TO $FIELD[7]
  2848.           This moves the sixth field on the screen (counting from the top left
  2849.           field on the screen and going from left to right, top to bottom,
  2850.           starting with field zero) to the seventh field.
  2851.  
  2852.      Example:  scrolling upwards on the screen.
  2853.  
  2854.      Using the following screen format:
  2855.  
  2856.      Field 0   ###########   Field 1  ###########
  2857.      Field 2   ###########   Field 3  ###########
  2858.  
  2859.      FOR #N0 = 0 TO 1
  2860.  
  2861.  
  2862.                                        Tutorial
  2863.                                           34
  2864.  
  2865.  
  2866.  
  2867.  
  2868.  
  2869.  
  2870.  
  2871.           Begins a FOR loop from 0 to 1
  2872.           MOVE $FIELD[#N0+2] TO $FIELD[#N0]
  2873.                Moves FIELD 2 (#N0 plus 2) to FIELD 0.  Then moves FIELD 3 to
  2874.                FIELD 1.
  2875.  
  2876.      ENDFOR #N0
  2877.           END
  2878.                Note that in the contents of the brackets following the $FIELD
  2879.                will be evaluated as an expression.  This expression must
  2880.                evaluate to an integer.  The following (assuming that the
  2881.                contents of the numeric register are integers) are all valid:
  2882.  
  2883.           $FIELD[(#N1 * #N2) + 10]
  2884.           $FIELD[#N1 + #N2 - 20]
  2885.           $FIELD[$OFFSET(SCNFIELD) + 5]
  2886.  
  2887.  
  2888.      #F - The Screen Field Offset Register
  2889.      -------------------------------------
  2890.      The register #F always contains the offset of the current screen data
  2891.      field.  It uses are numerous.  For example, to call a help screen for a
  2892.      particular screen field, you can use this instruction:
  2893.  
  2894.      IF #F EQ 8 HELP "FIELD"
  2895.           #F provides powerful screen handling when combined with $FIELD.  For
  2896.           example, to clear the current field and the next three fields, use
  2897.           this code:
  2898.  
  2899.      FOR #N1 = 0 TO 2
  2900.           CLEAR $FIELD[#F + #N1]
  2901.      ENDFOR #N1
  2902.  
  2903.      Screen Data Fields Using the Same Procedure
  2904.      -------------------------------------------
  2905.      Many screen data fields may use a common procedure.  As an example of the
  2906.      use of this technique, suppose you want to add a column of three fields and
  2907.      want the correct total always to be displayed on the fourth line even if
  2908.      the user backtabs and changes the number.  The obvious is to go through a
  2909.      long series of steps to subtract out the previous number, maintain the
  2910.      values in an array or something else very tedious.  
  2911.  
  2912.      The four fields are:
  2913.  
  2914.      ADD1     ##########
  2915.      ADD2     ##########
  2916.      ADD3     ##########
  2917.  
  2918.      RESULT  ##########
  2919.  
  2920.  
  2921.  
  2922.                                        Tutorial
  2923.                                           35
  2924.  
  2925.  
  2926.  
  2927.  
  2928.  
  2929.  
  2930.  
  2931.      Make RESULT non-enterable and use this PROC for the fields ADD1, ADD2, and
  2932.      ADD3:
  2933.  
  2934.      PROC ADDP
  2935.           CLEAR RESULT
  2936.           MOVE $OFFSET(ADD1) TO #N2
  2937.      *  The function $OFFSET gives the offset of the field ADD1.
  2938.  
  2939.           FOR #N1 = 0 TO 2
  2940.                ADD $FIELD[#N2 + #N1] TO RESULT
  2941.           ENDFOR #N1
  2942.  
  2943.           With this routine, it makes no difference which field or in which
  2944.           order the data is entered, the result will be correct.
  2945.  
  2946.  
  2947.                                 Structured Programming
  2948.                                 ----------------------
  2949.  
  2950.      Structured Constructs
  2951.      ---------------------
  2952.      Q-PRO 4 has an excellent set of structured constructs.  This set is
  2953.      initiated with the command, BEGIN.  BEGIN is modified by IF, WHILE, or
  2954.      UNTIL followed by a condition.  The BEGIN construct will be entered under
  2955.      these conditions:
  2956.  
  2957.      BEGIN IF <condition>
  2958.           Enter and execute all commands between the BEGIN and ENDBEGIN if the
  2959.           <condition> is true.  If the <condition> is not true, skip over the
  2960.           construct.  (See also ELSE and ELSE IF.)
  2961.  
  2962.      BEGIN WHILE<condition>
  2963.           Enter the construct and repeatedly execute the commands within it as
  2964.           long as the <condition> is true.
  2965.  
  2966.      BEGIN UNTIL<condition>
  2967.           Enter the construct and repeatedly execute the commands within it
  2968.           until the <condition> becomes true.7
  2969.  
  2970.      The BEGIN construct is terminated by ENDBEGIN.  Between the BEGIN and the
  2971.      ENDBEGIN are the commands to be executed if the BEGIN construct is entered.
  2972.  
  2973.      Examples:
  2974.  
  2975.      BEGIN IF A > B
  2976.           CALL SUB1
  2977.           CALL SUB2
  2978.      ENDBEGIN
  2979.  
  2980.  
  2981.  
  2982.                                        Tutorial
  2983.                                           36
  2984.  
  2985.  
  2986.  
  2987.  
  2988.  
  2989.  
  2990.  
  2991.      BEGIN WHILE A < 10
  2992.           CALL TEST_SUB
  2993.           ADD 1 TO A
  2994.      ENDBEGIN
  2995.                The subroutine TEST_SUB will be repeatedly called until the
  2996.                variable A reaches the value of 10
  2997.  
  2998.      MOVE 0 TO A
  2999.      BEGIN UNTIL A=10
  3000.           CALL TEST_SUB
  3001.           ADD 1 TO A
  3002.      ENDBEGIN
  3003.           The subroutine TEST_SUB will repeatedly be called until the variable A
  3004.           reaches the value of 10.
  3005.  
  3006.      The BEGIN IF construct may also include ELSE and/or ELSE IF prior to the
  3007.      ENDBEGIN.
  3008.        
  3009.      Example:
  3010.      BEGIN IF  A=B
  3011.                CALL SUBA
  3012.           ELSE IF A=C
  3013.                CALL SUBB
  3014.           ELSE
  3015.                CALL SUBC
  3016.      ENDBEGIN
  3017.           If A=B, call subroutine A, if A=C call subroutine B; if it equals
  3018.           neither, call subroutine C.
  3019.  
  3020.  
  3021.                                       Debugging
  3022.                                       ---------
  3023.  
  3024.      Q-PRO 4 has a wealth of debugging tools that range from simply reloading
  3025.      the program and BW on an error to a full runtime debugger.
  3026.  
  3027.      ERROR Command
  3028.      -------------
  3029.      An ERROR command in the program code will halt execution and display the
  3030.      specified error message on line 24 of the CRT.  When the program encounters
  3031.      the ERROR command, it will stop, display the specified error message and
  3032.      wait for operator action.  For debugging, a message with the ERROR command
  3033.      can be used to identify locations in the code, etc.  Messages can be
  3034.      literals in quotes, a register, or a variable.
  3035.           
  3036.      DEBUG Command
  3037.      -------------
  3038.      The DEBUG command loads the runtime debugger.  It has a host of
  3039.      capabilities that include looking at any field, changing memory, changing
  3040.  
  3041.  
  3042.                                        Tutorial
  3043.                                           37
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.      the value of variables, and looking at the values of file fields.  For more
  3052.      detail on the use of DEBUG, refer to the Commands section.
  3053.  
  3054.  
  3055.  
  3056.      TRACE Command
  3057.      -------------
  3058.      The TRACE command will put the program in single step mode.  When TRACE is
  3059.      encountered, the program will execute one command at a time, displaying the
  3060.      command to be executed on line 24.  Pressing the ESCAPE key will execute
  3061.      the displayed command.  This will continue until the command NOTRACE is
  3062.      encountered or RETURN is pressed.
  3063.  
  3064.      If the "D" key is pressed during TRACE, the online debugger will be loaded
  3065.      after the command is executed.
  3066.  
  3067.  
  3068.                                  All About Registers
  3069.                                  -------------------
  3070.  
  3071.      General
  3072.      -------
  3073.      Registers are temporary working areas maintained by the system which
  3074.      resemble fields except that they are not displayed on the screen.  The
  3075.      contents of all data registers remain intact when you CHAIN to another
  3076.      application file.
  3077.  
  3078.      There are three types of data registers.  Each type has ten usable
  3079.      registers.  Registers are cleared when Q-PRO 4 is first loaded.  The
  3080.      current value of the register remains when one program CHAINs to another.
  3081.  
  3082.      String Registers
  3083.      ----------------
  3084.      String registers are used as temporary storage for data. For example, they
  3085.      can be used to build an output record for the printer or intermediate
  3086.      storage for input data prior to moving it to a field or output buffer. 
  3087.      They may be used as variables in any command in lieu of a field or literal. 
  3088.      Also, string registers are used to transfer variables between program
  3089.      chains.
  3090.  
  3091.      Length         255 Characters 
  3092.      Names          #S0 to #S9.  (the lower case "s" can be used)
  3093.      Clearing       MOVE "" or '' to the register 
  3094.                     Example:  MOVE "" TO #S0
  3095.                         or    MOVE '' TO #S0
  3096.  
  3097.      Rules for the Use of String Registers
  3098.      -------------------------------------
  3099.      1.   Data can be concatenated onto an existing string in a register or it
  3100.  
  3101.  
  3102.                                        Tutorial
  3103.                                           38
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.      can be moved on top of existing data, but data cannot be moved to an
  3112.      arbitrary position within a register that has been cleared.  To move data
  3113.      into the register at random, first fill it with blanks.     
  3114.      2.   A string register may not be moved into a numeric register unless the
  3115.      string register contains valid numeric data.
  3116.  
  3117.  
  3118.           Note:     A MOVE command with the destination being a data register
  3119.                     clears the register of any data previously contained and
  3120.                     puts the new data in the register.    
  3121.  
  3122.      Numeric Registers
  3123.      -----------------
  3124.      Numeric registers are used the same as string registers, but limited to
  3125.      numeric data.
  3126.  
  3127.           Length         20 Digits 
  3128.           Name           #N0 to #N9
  3129.           Clearing       Move a zero (0) into the register
  3130.  
  3131.      Rules for the Use of Numeric Registers
  3132.      --------------------------------------
  3133.      1.   A string or string register can be moved into a numeric register only
  3134.      if the data is all numeric, [0-9  -  +  .]  (Note: decimal points move with
  3135.      numeric data.)
  3136.      2.   Numeric registers can always be moved to a string register or field.
  3137.      3.   No substring operations are allowed in numeric registers.
  3138.  
  3139.      Bit or Boolean Registers
  3140.      ------------------------
  3141.      Each Boolean register is a flag that can be interrogated by the program to
  3142.      see if it is on or off.  Program logic upon interrogating this flag will
  3143.      determine an action.  In other words they direct logical branches in a
  3144.      program.
  3145.  
  3146.           Length         Each boolean register is a single bit
  3147.           Name           #B0 to #B9
  3148.           Setting        SET #B0
  3149.           Clearing       RESET #B0
  3150.  
  3151.      Examples:
  3152.      IF #B0 SET LOCK FIELD
  3153.           If bit register is set (on) lock the field named FIELD.
  3154.  
  3155.      IF #B0 SET CALL SUB_ROUT1
  3156.           If bit register is set (on) call subroutine SUB_ROUT1.
  3157.  
  3158.      System Registers
  3159.      ----------------
  3160.  
  3161.  
  3162.                                        Tutorial
  3163.                                           39
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.       The system has several registers that it maintains.  They are:
  3172.           
  3173.      #E   This register will contain the error codes returned from file
  3174.           operations, that is, the direct codes returned by the operating system
  3175.           instead of the Q-PRO 4 high level codes.  For example, end of media
  3176.           would be returned to #E. The possible contents of this register are
  3177.           listed in the computers system manual.  This is a read only register.
  3178.      #F   The current field on the screen that the cursor is in.  Fields are
  3179.           numbered starting with zero from top to bottom, and moving from left
  3180.           to right.  Its number will be the same as the offset in the format
  3181.           file listing.  This is a read only register.
  3182.  
  3183.      #K   The key-out register.  A read only register that contains the numeric
  3184.           code describing how the operator exited the last field (causing the
  3185.           current proc to be executed).  Values for #K are:
  3186.  
  3187.                 1 - tabbed out
  3188.                 2 - backtabbed out
  3189.                 3 - cursor up
  3190.                 4 - cursor down, newline
  3191.                 5 - cursor left
  3192.                 6 - cursor right
  3193.                 7 - enter
  3194.                 8 - home
  3195.                 9 - any function key
  3196.                10 - break
  3197.  
  3198.      #L   The line counter.  Incremented each time a WRITE 0 is issued. It is
  3199.           reset to 0 when the command RESTART 0 is issued.
  3200.  
  3201.      #P   The page counter.  Incremented each time a RESTART 0 is issued.
  3202.  
  3203.  
  3204.                                         Tables
  3205.                                         ------
  3206.  
  3207.      One of the most powerful features of Q-PRO 4 is the use of tables.  These
  3208.      tables may be used simply to validate data or, in a more sophisticated way,
  3209.      they may be used to dynamically load registers for complex data handling. 
  3210.      The form of the table search verb, TSEAR, is:
  3211.  
  3212.      TSEAR <table name> AT <data item 1>{,<data item 2>, <data item 3>,. .
  3213.      .}{:error}
  3214.      Where:
  3215.  
  3216.      table name     A table in the program which was declared by the statement 
  3217.  
  3218.      AT             Where to look for a match
  3219.  
  3220.  
  3221.  
  3222.                                        Tutorial
  3223.                                           40
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.  
  3231.      data item 1    Where to put the second element of the line in the table
  3232.  
  3233.      data item 2    Where to put the third element of the line in the table
  3234.  
  3235.      {:error}       Branch to this label if there is no match
  3236.  
  3237.      Example:
  3238.  
  3239.      TSEAR  EXTABLE AT #N1,#S1,#N2,#N3:10010
  3240.  
  3241.      In this example, the table looks like this
  3242.  
  3243.      TABLE EXTABLE
  3244.  
  3245.      1, "CUSTNAME",      15,  12
  3246.      2, "STATE",         2,   10
  3247.      3, "ZIP",           5,   10
  3248.      END
  3249.          
  3250.  
  3251.      The command TSEAR will look in numeric register one (#N1) for a match with
  3252.      the first column of the table, 1, 2, or 3.  If a match is made, it will
  3253.      take the second element of the row in which a match was made and place it
  3254.      in string register one (#S1), and the third element in numeric register two
  3255.      (#N2).  The fourth element will go into numeric register three (#N3).
  3256.  
  3257.      If #N1 contains a 1, then this command loads #S1 with CUSTNAME, #N2 with
  3258.      15, and #N3 with 12.
  3259.  
  3260.      If #N1 contains neither 1, 2, or 3, the error branch will be taken.
  3261.  
  3262.      Loading a Table with External Data
  3263.      ----------------------------------
  3264.      The elements of a table are not limited to the literals that were shown
  3265.      above.  A table element can be any appropriate data item such as a file
  3266.      data field, register, etc.  Examples of such use are for payroll tax
  3267.      tables, due dates, etc. 
  3268.  
  3269.      To illustrate this use, let us look at a payroll tax table.  We will to
  3270.      load a memory array from a file array with the state names which will be
  3271.      the arguments of the table.  Then we will load the state tax tables into a
  3272.      memory array and thence to the elements of a table.
  3273.  
  3274.      In this case, there are three state tax tables to be loaded from three
  3275.      records on the file.  Each record has the following data layout:
  3276.  
  3277.      RECORD FIELD      CONTENTS   
  3278.  
  3279.           STATE          State Name
  3280.  
  3281.  
  3282.                                        Tutorial
  3283.                                           41
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.  
  3291.  
  3292.           TAX(0)         First element of tax table
  3293.           TAX(1)         Second element of tax table
  3294.           TAX(2)         Third element of tax table
  3295.           TAX(3)         Fourth element of tax table
  3296.  
  3297.      There are two memory arrays, STATE with three elements, and TAX with 12
  3298.      elements.  Below is the code to read the file, load the memory arrays and
  3299.      load the table. 
  3300.  
  3301.      PROC LOAD
  3302.      * Define arrays, open file and load arrays.
  3303.  
  3304.           VRBL STATE, X,2,3
  3305.      * STATE is now defined as a string, two characters, and three elements.
  3306.  
  3307.           VRBL TAX, N,6,4
  3308.      * TAX is now defined as numeric, 6 characters, and four elements.
  3309.  
  3310.           OPEN "TAXFILE.DAT" USING "TAXFILE.FID",1:100
  3311.      FOR #N1 EQ 0 TO 2
  3312.           READ 1:END_FILE     
  3313.           MOVE &STATE[1,#N1] TO STATE[#N1]
  3314.           FOR #N2 = 0 TO 3
  3315.                MOVE &TAX[1,#N2] TO TAX[#N2 +(#N1 * 4)]
  3316.           ENDFOR #N2
  3317.      ENDFOR #N1
  3318.           END
  3319.  
  3320.      TABLE TAX_TABLE
  3321.           STATE[0],      TAX[0], TAX[1], TAX[2], TAX[3]
  3322.           STATE[1],      TAX[4], TAX[5], TAX[6], TAX[7]
  3323.           STATE[2],      TAX[8], TAX[9], TAX[10], TAX[11]
  3324.           END
  3325.  
  3326.      To calculate the taxes for a state use TSEAR to get the proper state from
  3327.      the screen (a field named ST) and load numeric registers to calculate as
  3328.      shown below:
  3329.  
  3330.      TSEAR TAX_TABLE AT ST, #N1, #N2, #N3, #N4:NO_STATE
  3331.      END
  3332.  
  3333.      Notes on Tables
  3334.      1.  You must insure that elements match.  That is if the argument is a
  3335.      number, then you must match it with a number.  Similarly, if the result is
  3336.      a string, put it into a string data item.
  3337.  
  3338.      2.   If you are dealing with a string argument, remember that spaces are
  3339.      valid parts of a string.  To strip a string of trailing spaces use this
  3340.  
  3341.  
  3342.                                        Tutorial
  3343.                                           42
  3344.  
  3345.  
  3346.  
  3347.  
  3348.  
  3349.  
  3350.  
  3351.      code:
  3352.  
  3353.           MOVE STRING TO #S0 TRIMMED
  3354.  
  3355.      #S0 will contain the data from STRING with trailing spaces cut off.
  3356.  
  3357.  
  3358.  
  3359.                                       Variables
  3360.                                       ---------
  3361.  
  3362.      Introduction
  3363.      ------------
  3364.      One of the neat things about being in data processing is the esoteric
  3365.      vocabulary that we have to confound and confuse the uninitiated.  One of
  3366.      these terms is "variables".  It is undoubtedly one of the words that we
  3367.      love the most because of the confusion we can sow.
  3368.  
  3369.      Definition
  3370.      ----------
  3371.      Let's define the word and remove the confusion.  The word variable comes
  3372.      from the Latin various, meaning changing.   Of the many definitions
  3373.      available in the dictionary, the closest to the data processing meaning is
  3374.      that of the variable in mathematics, something which has no fixed value as
  3375.      opposed to a constant value.
  3376.  
  3377.      However, in data processing, with our talent for jargon, we use variable as
  3378.      a blanket term for a place in the computer memory where some data is stored
  3379.      that we will change periodically.  Accordingly, when we refer to a
  3380.      variable, we are really talking about the contents of some location in
  3381.      memory.  
  3382.  
  3383.      Usage
  3384.      -----
  3385.      Variables are convenient places to stash and retrieve data whose values may
  3386.      change from time to time.  Once a variable is given a name, the value it
  3387.      contains may be used by simply using its name.  The value of a variable is
  3388.      always its most recent.  In other words, whatever was most recently put
  3389.      into the variable is what is there now.  Previous values are discarded.
  3390.  
  3391.      In Q-PRO 4, variables are exactly like screen data fields except that they
  3392.      do not display.  In a more complex form they can be dimensioned.  (Refer to
  3393.      Dimensioned Variables.)
  3394.  
  3395.      For example, data that is on a file may be read in and stored in variables
  3396.      for processing.  After and/or during procesCing, the variables may`Bα
  3397.      changed to reflect the results of the processing.
  3398.  
  3399.      Other uses of variables include tables of data, or buckets to store values
  3400.  
  3401.  
  3402.                                        Tutorial
  3403.                                           43
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.      temporarily.  They me which field or in which
  3412.           order the data is entered, the result will be correct.
  3413.  
  3414.  
  3415.                                 Structured Programming
  3416.                                 ----------------------
  3417.  
  3418.      Structured Constructs
  3419.      ---------------------
  3420.      Q-PRO 4 has an excellent set of structured constructs.  This set is
  3421.      initiated with the command, BEGIN.  BEGIN is modified by IF, WHILE, or
  3422.      UNTIL followed by a condition.  The BEGIN construct will be entered under
  3423.      these conditions:
  3424.  
  3425.      BEGIN IF <condition>
  3426.           Enter and execute all commands between the BEGIN and ENDBEGIN if the
  3427.           <condition> is true.  If the <condition> is not true, skip over the
  3428.           construct.  (See also ELSE and ELSE IF.)
  3429.  
  3430.      BEGIN WHILE<condition>
  3431.           Enter the construct and repeatedly execute the commands within it as
  3432.           long as the <condition> is true.
  3433.  
  3434.      BEGIN UNTIL<condition>
  3435.           Enter the construct and repeatedly execute the commands within it
  3436.           until the <condition> becomes true.7
  3437.  
  3438.      The BEGIN construct is terminated by ENDBEGIN.  Between the BEGIN and the
  3439.      ENDBEGIN are the commands to be executed if the BEGIN construct is entered.
  3440.  
  3441.      Examples:
  3442.  
  3443.      BEGIN IF A > B
  3444.           CALL SUB1
  3445.           CALL SUB2
  3446.      ENDBEGIN
  3447.  
  3448.  
  3449.  
  3450.                                        Tutorial
  3451.                                           36
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.      BEGIN WHILE A < 10
  3460.           CALL TEST_SUB
  3461.           ADD 1 TO A
  3462.      ENDBEGIN
  3463.                The subroutine TEST_SUB will be repeatedly called until the
  3464.                variable A reaches the value of 10
  3465.  
  3466.      MOVE 0 TO A
  3467.      BEGIN UNTIL A=10
  3468.           CALL TEST_SUB
  3469.           ADD 1 TO A
  3470.      ENDBEGIN
  3471.           The subroutine TEST_SUB will repeatedly be called until the variable A
  3472.           reaches the value of 10.
  3473.  
  3474.      The BEGIN IF construct may also include ELSE and/or ELSE IF prior to the
  3475.      ENDBEGIN.
  3476.        
  3477.      Example:
  3478.      BEGIN IF  A=B
  3479.                CALL SUBA
  3480.           ELSE IF A=C
  3481.                CALL SUBB
  3482.           ELSE
  3483.                CALL SUBC
  3484.      ENDBEGIN
  3485.           If A=B, call subroutine A, if A=C call subroutine B; if it equals
  3486.           neither, call subroutine C.
  3487.  
  3488.  
  3489.                                       Debugging
  3490.                                       ---------
  3491.  
  3492.      Q-PRO 4 has a wealth of debugging tools that range from simply reloading
  3493.      the program and BW on an error to a full runtime debugger.
  3494.  
  3495.      ERROR Command
  3496.      -------------
  3497.      An ERROR command in the program code will halt execution and display the
  3498.      specified error message on line 24 of the CRT.  When the program encounters
  3499.      the ERROR command, it will stop, display the specified error message and
  3500.      wait for operator action.  For debugging, a message with the ERROR command
  3501.      can be used to identify locations in the code, etc.  Messages can be
  3502.      literals in quotes, a register, or a variable.
  3503.           
  3504.      DEBUG Command
  3505.      -------------
  3506.      The DEBUG command loads the runtime debugger.  It has a host of
  3507.      capabilities that include looking at any field, changing memory, changing
  3508.  
  3509.  
  3510.                                        Tutorial
  3511.                                           37
  3512.  
  3513.  
  3514.  
  3515.  
  3516.  
  3517.  
  3518.  
  3519.      the value of variables, and looking at the values of file fields.  For more
  3520.      detail on the use of DEBUG, refer to the Commands section.
  3521.  
  3522.  
  3523.  
  3524.      TRACE Command
  3525.      -------------
  3526.      The TRACE command will put the program in single step mode.  When TRACE is
  3527.      encountered, the program will execute one command at a time, displaying the
  3528.      command to be executed on line 24.  Pressing the ESCAPE key will execute
  3529.      the displayed command.  This will continue until the command NOTRACE is
  3530.      encountered or RETURN is pressed.
  3531.  
  3532.      If the "D" key is pressed during TRACE, the online debugger will be loaded
  3533.      after the command is executed.
  3534.  
  3535.  
  3536.                                  All About Registers
  3537.                                  -------------------
  3538.  
  3539.      General
  3540.      -------
  3541.      Registers are temporary working areas maintained by the system which
  3542.      resemble fields except that they are not displayed on the screen.  The
  3543.      contents of all data registers remain intact when you CHAIN to another
  3544.      application file.
  3545.  
  3546.      There are three types of data registers.  Each type has ten usable
  3547.      registers.  Registers are cleared when Q-PRO 4 is first loaded.  The
  3548.      current value of the register remains when one program CHAINs to another.
  3549.  
  3550.      String Registers
  3551.      ----------------
  3552.      String registers are used as temporary storage for data. For example, they
  3553.      can be used to build an output record for the printer or intermediate
  3554.      storage for input data prior to moving it to a field or output buffer. 
  3555.      They may be used as variables in any command in lieu of a field or literal. 
  3556.      Also, string registers are used to transfer variables between program
  3557.      chains.
  3558.  
  3559.      Length         255 Characters 
  3560.      Names          #S0 to #S9.  (the lower case "s" can be used)
  3561.      Clearing       MOVE "" or '' to the register 
  3562.                     Example:  MOVE "" TO #S0
  3563.                         or    MOVE '' TO #S0
  3564.  
  3565.      Rules for the Use of String Registers
  3566.      -------------------------------------
  3567.      1.   Data can be concatenated onto an existing string in a register or it
  3568.  
  3569.  
  3570.                                        Tutorial
  3571.                                           38
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.      can be moved on top of existing data, but data cannot be moved to an
  3580.      arbitrary position within a register that has been cleared.  To move data
  3581.      into the register at random, first fill it with blanks.     
  3582.      2.   A string register may not be moved into a numeric register unless the
  3583.      string register contains valid numeric data.
  3584.  
  3585.  
  3586.           Note:     A MOVE command with the destination being a data register
  3587.                     clears the register of any data previously contained and
  3588.                     puts the new data in the register.    
  3589.  
  3590.      Numeric Registers
  3591.      -----------------
  3592.      Numeric registers are used the same as string registers, but limited to
  3593.      numeric data.
  3594.  
  3595.           Length         20 Digits 
  3596.           Name           #N0 to #N9
  3597.           Clearing       Move a zero (0) into the register
  3598.  
  3599.      Rules for the Use of Numeric Registers
  3600.      --------------------------------------
  3601.      1.   A string or string register can be moved into a numeric register only
  3602.      if the data is all numeric, [0-9  -  +  .]  (Note: decimal points move with
  3603.      numeric data.)
  3604.      2.   Numeric registers can always be moved to a string register or field.
  3605.      3.   No substring operations are allowed in numeric registers.
  3606.  
  3607.      Bit or Boolean Registers
  3608.      ------------------------
  3609.      Each Boolean register is a flag that can be interrogated by the program to
  3610.      see if it is on or off.  Program logic upon interrogating this flag will
  3611.      determine an action.  In other words they direct logical branches in a
  3612.      program.
  3613.  
  3614.           Length         Each boolean register is a single bit
  3615.           Name           #B0 to #B9
  3616.           Setting        SET #B0
  3617.           Clearing       RESET #B0
  3618.  
  3619.      Examples:
  3620.      IF #B0 SET LOCK FIELD
  3621.           If bit register is set (on) lock the field named FIELD.
  3622.  
  3623.      IF #B0 SET CALL SUB_ROUT1
  3624.           If bit register is set (on) call subroutine SUB_ROUT1.
  3625.  
  3626.      System Registers
  3627.      ----------------
  3628.  
  3629.  
  3630.                                        Tutorial
  3631.                                           39
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.  
  3639.       The system has several registers that it maintains.  They are:
  3640.           
  3641.      #E   This register will contain the error codes returned from file
  3642.           operations, that is, the direct codes returned by the operating system
  3643.           instead of the Q-PRO 4 high level codes.  For example, end of media
  3644.           would be returned to #E. The possible contents of this register are
  3645.           listed in the compu                              Tutorial
  3646.                                           47
  3647.  
  3648.  
  3649.  
  3650.  
  3651.  
  3652.  
  3653.  
  3654.      Multiuser Function Keys
  3655.  
  3656.      PROC READ_LOCK
  3657.           Since everybody wants to do this, we will write a subroutine they can
  3658.           all use.
  3659.           READ 1 NOADV:EF
  3660.                Read the record but don't advance, preparatory to trying to lock
  3661.                it.
  3662.           RLOCK 1:USED
  3663.                Lock the record in the buffer.  If it is already locked, goto
  3664.                USED.
  3665.           COPY 1 TO *
  3666.           RETURN
  3667.                Go back to the calling program at the next sequential command.
  3668.      :EF  ERROR "No more records "
  3669.           END
  3670.      PROC KEY1
  3671.                CALL READ_LOCK
  3672.                END
  3673.      PROC KEY2
  3674.           BACKSPACE 1:EF
  3675.                Since we are using NOADV, we need only BACKSPACE once.
  3676.           CALL READ_LOCK  
  3677.           END
  3678.  
  3679.      PROC KEY11
  3680.                POSN 1 TO NAME USING 1
  3681.                CALL READ_LOCK
  3682.                FREE 1
  3683.                END
  3684.  
  3685.      PROC KEY3
  3686.           POSN 1 TO NAME RELATIVE
  3687.           RLOCK  1:USED
  3688.           READ 1:EF
  3689.           COPY 1 TO *
  3690.           END
  3691.  
  3692.      Accession Number Management
  3693.      ---------------------------
  3694.      One of the better methods of transaction number management stores and
  3695.      maintains all the application system access numbers in a single application
  3696.      control file.  Usually, the file is a one record random file that is
  3697.      quickly accessible and updatable.  It contains such accession numbers as
  3698.      next available customer number, next available order number, next available
  3699.      invoice number, etc.  The trick of managing the accession numbers is the
  3700.      timing of when the number is updated.  For example, the customer number is
  3701.      updated when a new customer record is written.  If it is updated at any
  3702.      other time, numbers may be used and never assigned.
  3703.  
  3704.  
  3705.                                        Tutorial
  3706.                                           48
  3707.  
  3708.  
  3709.  
  3710.  
  3711.  
  3712.  
  3713.  
  3714.  
  3715.      Another technique is maintaining them in a record in the working indexed
  3716.      file with a unique and particular key that the programmer knows is for the
  3717.      accession number file.  For example, a file with the key $$***$$ is
  3718.      unlikely to ever be reached by the user.  This is a good method for small
  3719.      applications.  It is a problem for applications with many users because of
  3720.      the large amount of file crunching always going on.
  3721.  
  3722.      The least desirable method, we look at the last record written and add one
  3723.      to its accession number.  This method is not suitable for LANs and
  3724.      multiuser applications.
  3725.  
  3726.                             Restructuring an Indexed File
  3727.                             -----------------------------
  3728.      Adding Keys
  3729.      -----------
  3730.      You cannot change the structure of a data file by simply changing the
  3731.      associated FID file.  While the FID file knows about the change, no one has
  3732.      told the data file.  It takes a small Q-PRO 4 program to do this.
  3733.  
  3734.      The process is very simple, we make a new FID file with the structure we
  3735.      want.  Then we create a new data file with the new FID and copy each old
  3736.      record, one by one to the new file.
  3737.  
  3738.      New FID File
  3739.           Copy the old FID file, OLD.FID to a new file, NEW.FID.  Load Binary
  3740.           WorkStation.  Select the FID generator mode and load NEW.FID.
  3741.       
  3742.           Press F5 to insert a field.  Enter a new field, CUSTNO, that is 10
  3743.           characters long and numeric.
  3744.  
  3745.           Press F4 to update the FID.  Press Shift F10 to return to the editor.
  3746.  
  3747.      The program
  3748.  
  3749.      PROC RESTRUC
  3750.           OPEN "OLD.DAT" USING "OLD.FID",1:100
  3751.           MAKE "NEW.DAT" USING "NEW.FID",2:200
  3752.  
  3753.      :L   READ 1:EOF
  3754.           COPY 1 TO 2
  3755.           GOTO L
  3756.  
  3757.      :EOF CLOSE
  3758.           FCOPY "NEW.DAT", "OLD.DAT"
  3759.           FCOPY "NEW.IDX", "OLD.IDX"
  3760.           ERASE "NEW.DAT"
  3761.           ERASE "NEW.IDX"
  3762.           END
  3763.  
  3764.  
  3765.                                        Tutorial
  3766.                                           49
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.  
  3774.  
  3775.                P R O G R A M M E R'S    R E F E R E N C E   M A N U A L
  3776.                ========================================================
  3777.  
  3778.  
  3779.      Naming Conventions
  3780.      -------------------
  3781.      All Q-PRO 4 names follow the conventions shown below.  These conventions
  3782.      apply to screen field names, file field names, variables, and labels.
  3783.  
  3784.       1.  The first character of any name must be an alphabetic character.  The
  3785.           balance may be either alpha or numeric.
  3786.  
  3787.       2.  The name may be up to 10 characters long.
  3788.  
  3789.       3.  Underline characters (_) may be embedded in the name for clarity and
  3790.           they are counted in the 10 character length.
  3791.  
  3792.      Examples:
  3793.  
  3794.      FIELD_NAME          CUST_FILE           NEW_CUS_NA
  3795.  
  3796.  
  3797.      Keyboard
  3798.      --------
  3799.      Q-PRO 4 uses many of the functions of the keyboard as configured to the
  3800.      particular computer and operating system.  For example, in this manual we
  3801.      frequently refer to the "ENTER" key.  This key is different on various
  3802.      computers.  For the IBM PC, it is standardly the END key.  With the
  3803.      configuration utility, SETUP, you may change these keys to meet your own
  3804.      requirements. 
  3805.  
  3806.      Format Files
  3807.      ------------
  3808.      The format, command, or program file is the primary component of a Q-PRO 4
  3809.      application program.  It is created by the programmer.  This file contains
  3810.      the invariant (background) information, field definitions, and programming
  3811.      statements necessary for a Q-PRO 4 application.  The format is created with
  3812.      Binary WorkStation (BW), and executed by the runtime interpreter (QNE).
  3813.  
  3814.      Building a Format
  3815.      -----------------
  3816.      Binary WorkStation is used for writing the programs.  It is entered by
  3817.      typing BW when at the system prompt.  From BW, the user may select an
  3818.      existing file to edit or create a new one.
  3819.  
  3820.      Press return to begin editing. The bottom line of the screen shows the
  3821.      functions available.  Pressing F10 or F9 will scroll the function
  3822.      selections. For more details on the BW editor, see the Binary WorkStation
  3823.  
  3824.  
  3825.                             Programmer's Reference Manual
  3826.                                        Page 50
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.      section.
  3835.  
  3836.      Build Screens
  3837.      -------------
  3838.      Select F8 Screen to edit of the background (unalterable) portion of the
  3839.      screen.  To create the background, place the cursor at the location on the
  3840.      screen where you want the background text and type the desired text.  All
  3841.      the cursor control keys, the INSERT/DELETE character and line keys, and the
  3842.      TAB key are active and usable for creating and editing the background.
  3843.  
  3844.      Screen Data Field Definition
  3845.      ----------------------------
  3846.      Place the cursor where you want an entry field and press F1.  The screen
  3847.      definition window will display.  When the field definition process is
  3848.      complete for a field, press RETURN.  Previously defined screen data fields
  3849.      which are denoted by strings of the pound-sign character (#) on the screen. 
  3850.      Although, we call these scream data fields, as you will see later, they may
  3851.      or may not be enterable by the operator.
  3852.  
  3853.      These are the items that are entered to define a screen data field:
  3854.  
  3855.      Field No.      This is the OFFSET of the field as determined by Q-PRO 4. 
  3856.                     It is the sequential number of the field counting from top
  3857.                     to bottom, left to right.  The offset is a most convenient
  3858.                     method of managing screen fields.
  3859.  
  3860.      Field name     The content of this field is a name of up to 10 alphanumeric
  3861.                     characters which follow the Q-PRO 4 naming conventions.  The
  3862.                     name must be unique on the current screen but may be reused
  3863.                     on other screens.  This name may be used as a variable by
  3864.                     the application program.  The name need not correspond to
  3865.                     anything, although some correspondence is useful for
  3866.                     clarity.
  3867.  
  3868.                     To delete a pre-existing field, clear this name area (using
  3869.                     the CLEAR SCREEN key), and then press ENTER.
  3870.  
  3871.      Len            defines the number of character positions to be occupied by
  3872.                     the field on the screen.  A length of 0 is invalid.  If you
  3873.                     use care, fields may be overlapped for special applications. 
  3874.                     However, be cautious, as confusion at data entry time may
  3875.                     occur.
  3876.  
  3877.      Row            The row number occupied by the screen data field.  (Zero is
  3878.                     the topmost row.)  This field is calculated automatically by
  3879.                     FB.  Normally you should skip this field by pressing TAB. 
  3880.                     However, you may relocate the field to a different row of
  3881.                     the screen by altering the value that Q-PRO has already put
  3882.                     in. 
  3883.  
  3884.  
  3885.                             Programmer's Reference Manual
  3886.                                        Page 51
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.  
  3894.  
  3895.      Col            is the starting column number of the screen data field. 
  3896.                     Like the R value, this entry is calculated by BW.  It may be
  3897.                     changed if you desire to change the column location of the
  3898.                     screen data field.  The left-most column is zero.
  3899.  
  3900.      Type           The field type descriptor is two characters.  The first
  3901.                     character describes the field attribute; such as numeric
  3902.                     only, alpha only, etc.  The second character specifies
  3903.                     auto-duplication or an invisible field.
  3904.  
  3905.                   First Character
  3906.                   ---------------
  3907.                     Blank (or x)   Any data is allowed in this field.
  3908.                     X              Any data is allowed, but alphabetic data will
  3909.                                    be forced to upper case.
  3910.                     a              Only alphabetic data is allowed.  (A-Z, a-z)
  3911.                     A              Only alphabetic data is allowed.  When
  3912.                                    entered they will be forced to upper case. 
  3913.                                    (A-Z, a-z)
  3914.                     m              Only alphanumeric data is allowed.  (A-Z,
  3915.                                    a-z, 0- 9)
  3916.                     M              Only alphanumeric data is allowed.  When
  3917.                                    entered, any alphabetic data will be forced
  3918.                                    to upper case.  (A-Z, a-z, 0- 9)
  3919.                     N              Only numeric data, its associated sign and
  3920.                                    decimal point is allowed.  (0-9  + - .)
  3921.                     I              Only numeric data and its associated sign are
  3922.                                    allowed (integers only). (0-9  +  -)
  3923.                     D              Only numbers are allowed.  No signs or
  3924.                                    decimal point are allowed.  (0-9)
  3925.  
  3926.                When data is typed into the field by the operator, each keystroke
  3927.                is validated.  It must be within the requirements specified by
  3928.                the descriptor character for the current entry field.  If it is
  3929.                not, an error message will be displayed on line 24 of the CRT and
  3930.                none of the keys (except ESCAPE) on the keyboard will respond.
  3931.  
  3932.                To clear the message, press ESCAPE which will clear the message
  3933.                and allow resumption of keying.  The previous contents of line 24
  3934.                will be restored.  Note that if a screen presentation is desired
  3935.                in which a single entry area is to contain a mixture of types
  3936.                (i.e., three digits, followed by two alphas), multiple screen
  3937.                data fields may be located alongside each other so that they
  3938.                present the appearance of being one field to the operator.
  3939.  
  3940.             Second Character
  3941.             ----------------
  3942.                Blank               No additional functions will be performed at
  3943.  
  3944.  
  3945.                             Programmer's Reference Manual
  3946.                                        Page 52
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.                                    the keystroke level.  The field will be
  3955.                                    cleared when ENTER is pressed.
  3956.                =                   "auto- duplication" field.  This means that
  3957.                                    the field is not automatically cleared when
  3958.                                    ENTER is pressed, and the contents of the
  3959.                                    field will remain after ENTER is pressed.
  3960.  
  3961.                                    When entering data, the operator may
  3962.                                    duplicate the previous value by pressing TAB. 
  3963.                                    Alternatively, new data may be typed in the
  3964.                                    field.  On the first keystroke of the newly
  3965.                                    typed data, all character positions from the
  3966.                                    current cursor position to the end of the
  3967.                                    field are cleared before the new character is
  3968.                                    placed in the field.
  3969.  
  3970.                ?                   The field will not be visible.  This is
  3971.                                    useful for passwords.
  3972.  
  3973.      Just      There are four options for justification of the screen field.  If
  3974.                nothing is specified, then the default is left.  NOTE:  All
  3975.                fields are automatically left justified when data is being
  3976.                entered.  The appropriate re-justification is performed as the
  3977.                operator exits the field.
  3978.  
  3979.                     L    Normally, screen fields are left justified.  If nothing
  3980.                          is entered this will be the case.  However, you may
  3981.                          enter an L if you desire.
  3982.                     R    Right justifies the screen field. 
  3983.                     C    Centers the data in the screen field. 
  3984.                     N    No justification of any kind.
  3985.  
  3986.      Fill Char Use this selection to force the fill of unentered space in the
  3987.                screen field.  Most often this specification is left blank. 
  3988.                However, frequently a zero is used along with right justification
  3989.                to produce a left zero filled screen field.  
  3990.  
  3991.                If a number sign (#) is specified as a fill character, blanks
  3992.                will be displayed on the screen.  However, when the field is
  3993.                programmatically referenced (e.g., written to a file), the
  3994.                leading or trailing spaces, as the case may be, are stripped from
  3995.                the field, leaving a variable length result.  This is useful when
  3996.                building files to interface with other programming systems. 
  3997.                CAUTION:  If you are using indexed or random Q-PRO 4 files, DO
  3998.                NOT use the "#".
  3999.  
  4000.                Almost any fill character is valid.  However, for numeric data to
  4001.                be used in computations, the only valid fill characters are blank
  4002.                (used for left justified numeric data), and 0 (used for right
  4003.  
  4004.  
  4005.                             Programmer's Reference Manual
  4006.                                        Page 53
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.                justified data).
  4015.  
  4016.                     The default is a blank.
  4017.  
  4018.      May Ent.  Y    Indicates that the operator may enter data in this field.
  4019.                N    Prevents the operator from entering data in this field. 
  4020.                     This is useful for message fields, total fields, or other
  4021.                     computed or derived data items.
  4022.  
  4023.                     The default value is "Y".
  4024.  
  4025.      Must Ent. Y    Indicates that if the operator reaches this field, then some
  4026.                     data must be entered.
  4027.                N    Indicates that the operator need not enter data here.
  4028.  
  4029.                     The default value is "N".
  4030.  
  4031.      Must Fill Y    Indicates that the operator must enter the field and must
  4032.                     fill the field.
  4033.                N    Indicates that the operator need not fill the field. 
  4034.  
  4035.                     The default is "N".
  4036.  
  4037.      Must Tab  Y    Indicates that the operator must press TAB or some other
  4038.                     cursor control key to exit the field.
  4039.                N    Indicates that the operator will leave the field if TAB is
  4040.                     pressed or the field is filled. 
  4041.  
  4042.                     The default is "N."
  4043.  
  4044.      Procedure
  4045.      name      This entry may contain the name of a procedure in the program
  4046.                code or it may be left blank.  If a procedure is named, the name
  4047.                must follow the Q-PRO 4 naming conventions.  The procedure will
  4048.                be executed each time the operator exits this screen data field. 
  4049.                This procedure may do extended validity checks and calculations,
  4050.                I/O to a file, or anything else you can think of.
  4051.  
  4052.  
  4053.  
  4054.  
  4055.  
  4056.  
  4057.  
  4058.  
  4059.  
  4060.  
  4061.  
  4062.  
  4063.  
  4064.  
  4065.                             Programmer's Reference Manual
  4066.                                        Page 54
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.                                 THE PROGRAMMING SYSTEM
  4075.                                 ======================
  4076.  
  4077.      Procedures
  4078.      ----------
  4079.      Q-PRO 4 programs are composed of commands organized into procedures.  Each
  4080.      procedure is executed in at least one of three ways:
  4081.  
  4082.           1.   As a procedure associated with a screen data field.
  4083.           2.   As a standard system procedure.
  4084.           3.   As a procedure called from another procedure.
  4085.  
  4086.      Screen Data Field Procedures
  4087.      ----------------------------
  4088.      The procedure name must conform to the Q-PRO 4 naming conventions
  4089.      previously described.  The sequence in which procedures occur in a Q-PRO 4
  4090.      program is not significant.  Therefore, the programmer is free to define
  4091.      some set of procedure-naming and placement standards that best suits him. 
  4092.      One suggested programming standard is to name field procedures the same as
  4093.      their associated screen data fields, followed with a "P" (i.e., a screen
  4094.      data field named CUSTNO would be linked to a procedure named CUSTNOP).
  4095.  
  4096.      A screen data field procedure is executed when the screen data field is
  4097.      exited by the operator (except for a back tab when no data has been
  4098.      entered).  Procedures normally end by giving control back to the operator
  4099.      and may redirect the cursor to any screen data field.
  4100.      Other types of procedures are discussed later in this chapter.
  4101.  
  4102.      A procedure is defined by a PROC statement, as shown below.  
  4103.  
  4104.      PROC CUSTNOP
  4105.  
  4106.      Within the procedure are (normally) executable statements, of the form
  4107.  
  4108.           {label:} statement  {:error}
  4109.  
  4110.      label     The label portion of the statement is optional.  If present, it
  4111.                follows the standard name conventions.  It optionally may be
  4112.                followed by a colon (:).  The label may be a number or an
  4113.                alphanumeric label.  If it is an alphanumeric label, it must be
  4114.                prefaced by a colon (:).  The label is used for control transfer
  4115.                (GOTO) and error trapping statements.  NO EMBEDDED SPACES ARE
  4116.                ALLOWED.
  4117.  
  4118.      statement The statement is a Q-PRO 4 command or construct.
  4119.  
  4120.      error     The error branch (a label to go to on error) is valid only on
  4121.                certain types of statements.  If given, it must be preceded by a
  4122.                colon.
  4123.  
  4124.  
  4125.                             Programmer's Reference Manual
  4126.                                        Page 55
  4127.  
  4128.  
  4129.  
  4130.  
  4131.  
  4132.  
  4133.  
  4134.      Data Items
  4135.      ----------
  4136.      A programming language is not of much use without data to manipulate.  In
  4137.      this manual, we will refer to the following six types of data items:
  4138.           1.    Data Registers
  4139.           2.    Special Registers
  4140.           3.    Screen data fields
  4141.           4.    Literals
  4142.           5.    Variables
  4143.           6.    File data fields
  4144.  
  4145.  
  4146.      1.   Data Registers
  4147.           --------------
  4148.           There are two types of data registers, string and numeric.  There are
  4149.           10 of each type of register, designated as:
  4150.  
  4151.           #N0-#N9   Numeric registers.  Numeric registers may contain an integer
  4152.                     or real number of up to 20 digits.  This value may be
  4153.                     manipulated, written to a file, examined, or overwritten in
  4154.                     any way. 
  4155.  
  4156.           #S0-#S9   String registers.  String registers may contain a string
  4157.                     (i.e., any data, alphanumeric, numeric, etc.) of up to 255
  4158.                     characters.  These registers may be manipulated, with the
  4159.                     MOVE, INSTR, CONCAT and other commands which provide
  4160.                     mechanisms for extracting substrings, performing
  4161.                     concatenation of strings, etc.  String registers are NEVER
  4162.                     padded with blanks.  They terminate with a null unless the
  4163.                     programmer inserts blanks.
  4164.  
  4165.           Data registers also may be accessed by an indexing expression, which
  4166.           must evaluate to a number between 0 and 9 (i.e., #S[#N0+2]).  (Refer
  4167.           to EXPRESSIONS in this chapter.) 
  4168.  
  4169.      2.  Special Registers
  4170.          -----------------
  4171.           #B0-#B9   The Boolean or flag registers.  They may be SET or RESET,
  4172.                     and are used to mark the occurrence of special events within
  4173.                     an application.
  4174.  
  4175.           #F        A read-only numeric register which contains the current
  4176.                     screen field number (as shown on the format file listing).
  4177.                     Since fields can be referenced indirectly through $FIELD
  4178.                     (see Functions, below), this means that generalized code can
  4179.                     be written to handle several like fields using $FIELD[#F]
  4180.                     instead of the field names themselves.
  4181.  
  4182.  
  4183.  
  4184.  
  4185.                             Programmer's Reference Manual
  4186.                                        Page 56
  4187.  
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.           #L        The line counter register.  It is incremented every time a
  4195.                     line is written to the list device with a WRITE 0 statement. 
  4196.                     When a RESTART 0 statement is executed (producing a form
  4197.                     feed on the printer), #L is cleared (or set to an optional
  4198.                     number of line feeds following the form feed).
  4199.  
  4200.           #P        The page number register is incremented every time a RESTART
  4201.                     0 statement is executed.  Refer to the Commands section for
  4202.                     more details on RESTART and WRITE.
  4203.  
  4204.                     To start a report, set both registers to 0, and the normal
  4205.                     course of output to the printer will maintain the registers
  4206.                     after that.  To sense the need for a new page, a line of
  4207.                     code similar to the following should be executed after every
  4208.                     print line: IF #L=PAGELENGTH THEN CALL HEADING
  4209.  
  4210.                     To output the page number to a report, the following
  4211.                     sequence might be used:
  4212.  
  4213.                     RESTART 0
  4214.                     PUT "PAGE " TO 0
  4215.                     PUT #P TO 0
  4216.                     WRITE 0
  4217.  
  4218.                     Of course, using the report generator is even easier.
  4219.  
  4220.           #E        The error register.  The contents of this register are the
  4221.                     error codes as returned from file operations.  These are the
  4222.                     direct codes returned by the operating system instead of the
  4223.                     Q-PRO 4 high level codes.  The possible contents of this
  4224.                     register are listed in the appropriate system manuals as
  4225.                     being returned from a specific system call.
  4226.  
  4227.           #K        The keyout register has a numeric code telling what control
  4228.                     key caused control to be given to the program.  The values
  4229.                     for this register are as follows:
  4230.  
  4231.                     0 - typed out
  4232.                     1 - tabbed out
  4233.                     2 - backtabbed out
  4234.                     3 - cursor up
  4235.                     4 - cursor down, newline
  4236.                     5 - cursor left
  4237.                     6 - cursor right
  4238.                     7 - enter
  4239.                     8 - home
  4240.                     9 - any function key
  4241.                     10 - break
  4242.  
  4243.  
  4244.  
  4245.                             Programmer's Reference Manual
  4246.                                        Page 57
  4247.  
  4248.  
  4249.  
  4250.  
  4251.  
  4252.  
  4253.  
  4254.  
  4255.      3.  Screen Data Fields
  4256.          ------------------
  4257.           Screen data fields are defined by the programmer.  They may be
  4258.           manipulated in any way.  As their value changes, that change is always
  4259.           reflected on the screen.  Fields may be accessed directly by their
  4260.           names or indirectly through the $FIELD function.
  4261.  
  4262.                FOR #N0=0 TO 3
  4263.                     MOVE $FIELD[#N0+1] TO $FIELD[#N0]
  4264.                ENDFOR #N0
  4265.                CLEAR $FIELD[#N0]
  4266.  
  4267.      4. Literals
  4268.         --------
  4269.           Literals (constant values) may be numeric or string or control
  4270.           character.  Literals may be used in any computation or manipulation
  4271.           (including direct output to files), except that they may not be stored
  4272.           into.
  4273.  
  4274.           String Literals     String literals must be delimited with either
  4275.                               single (') or double (") quotes which must be
  4276.                               paired.  Strings may not be delimited by mixed
  4277.                               single and double quotes (i.e., 'THIS IS
  4278.                               ILLEGAL"), although a string delimited by one type
  4279.                               of quote may contain the other type (e.g., 'And I
  4280.                               quote, "Four score and seven"').
  4281.  
  4282.                               String literal examples:
  4283.                               "THIS IS A STRING LITERAL"
  4284.                               'This is a string literal with single quotes'
  4285.  
  4286.           Numeric Literals    Numeric literals are numbers.  They may include
  4287.                               the decimal point (.) and be preceded by a minus
  4288.                               (-) sign.  They may not include any non-numeric
  4289.                               characters such as a comma (,) or a dollar sign
  4290.                               ($).  Numeric literals are not delimited with
  4291.                               quotes.
  4292.  
  4293.  
  4294.                               Numeric literal examples:
  4295.                               19746
  4296.                               289567
  4297.  
  4298.  
  4299.      Control Character Literals    A control character is a decimal literal or
  4300.                                    any numeric data item preceded by an at (@)
  4301.                                    sign.  The binary equivalent of the decimal
  4302.                                    value will be treated as a string literal of
  4303.  
  4304.  
  4305.                             Programmer's Reference Manual
  4306.                                        Page 58
  4307.  
  4308.  
  4309.  
  4310.  
  4311.  
  4312.  
  4313.  
  4314.                                    1 character.  This feature is most frequently
  4315.                                    used for controlling printers with special
  4316.                                    features such as expanded print, vertical
  4317.                                    tabbing, etc., or in sending special control
  4318.                                    commands to the screen.  
  4319.  
  4320.                                    Control character literal examples:
  4321.  
  4322.                                    @44
  4323.                                    @#N0
  4324.  
  4325.                                    To put an OKIDATA into bold print mode, you
  4326.                                    could use this sequence:
  4327.  
  4328.                                    PUT  @29 TO 0
  4329.  
  4330.      5. Variables
  4331.         ---------
  4332.           Variables are data items, maintained in memory, which can be used in
  4333.           computations or to build strings.  They may be accessed in the same
  4334.           manner as screen data fields.  In general they behave in the same
  4335.           manner as screen data fields (i.e., may take on a value, may be
  4336.           extracted from a file, may be incremented or decremented, etc.).
  4337.  
  4338.           Variables are defined by the programmer in VRBL statements, which are
  4339.           normally executed at format load time in PROC LOAD.  They may take on
  4340.           single values (in which case, they are referenced directly by name),
  4341.           or multiple values (in which case, we call them ARRAYS, and reference
  4342.           them by an indexing expression which names the specific element of the
  4343.           array we desire to access).  Variables may be used anywhere or in any
  4344.           expression in place of fields, literals, or registers.  The maximum
  4345.           array size is 65,000 elements (memory permitting).
  4346.  
  4347.      6. File Data Fields
  4348.         ----------------
  4349.           Fields in data records may be accessed in two ways--either by their
  4350.           relative positions within the record, or by their names.  The second
  4351.           way is more to be desired, and is accomplished by associating a FID
  4352.           (field item descriptor) file with a data file at MAKE or OPEN time. 
  4353.           These FID files are nothing more than a list of fields and their
  4354.           locations within a record.  Using this approach, the programmer never
  4355.           has to worry where a field is within a record, even if a record format
  4356.           has changed since it was last used.
  4357.  
  4358.           FID files are built with the FID option of Binary Workstation
  4359.           described in the chapter on BW.  When a data file has been opened
  4360.           using a FID file, then fields within the record may be accessed using
  4361.           the following general syntax:
  4362.  
  4363.  
  4364.  
  4365.                             Programmer's Reference Manual
  4366.                                        Page 59
  4367.  
  4368.  
  4369.  
  4370.  
  4371.  
  4372.  
  4373.  
  4374.            &name[file number{,array element number}]
  4375.  
  4376.           The ampersand (&) in front of the field name tells Q-PRO 4 that this
  4377.           is a file field name.  The  name tells the system where on the record
  4378.           the data is located.  The number tells the system which file is to be
  4379.           used (since different files may have the same field names).  The
  4380.           optional index selects one element from a field array when
  4381.           appropriate.
  4382.  
  4383.           Example:
  4384.  
  4385.           &CUSTNAME[1]   This denotes the field CUSTNAME from file 1.
  4386.  
  4387.  
  4388.                                  Standard Procedures
  4389.                                  -------------------
  4390.  
  4391.      Any procedure may be linked to a screen field by naming that procedure in
  4392.      the field definition phase of the format building process.  There are
  4393.      certain procedures which, although left up to the programmer to define,
  4394.      have special significance to the Q-PRO 4 system.  Not defining these
  4395.      procedures, however, does not necessarily result in an error.  Standard
  4396.      procedures are not usually linked to screen data fields.
  4397.  
  4398.      PROC BREAK
  4399.      ----------
  4400.           Executed when:
  4401.  
  4402.       1.  A BREAK key has been defined (standardly control C) through SETUP,
  4403.           and;
  4404.  
  4405.       2.  Breaks are enabled (default is BRON) with the command BRON, and;   
  4406.  
  4407.       3.  The system is NOT currently accepting input from the operator (e.g. is
  4408.           printing a report, searching a file, etc.), and;
  4409.  
  4410.       4.  The defined BREAK key is pressed.
  4411.  
  4412.           A RETURN from PROC BREAK goes to the statement after the calling
  4413.           statement.  When Q-PRO 4 loads, it initializes as BRON.
  4414.  
  4415.      PROC ENTER
  4416.      ----------
  4417.      Executed when the operator presses the DESIGNATED ENTER (standardly the
  4418.      return key on the IBM PC) key, signifying "data entry complete."  This pro-
  4419.      cedure might be used to update a file record, chain to another format, etc. 
  4420.      It also clears all operator enterable screen data fields.
  4421.  
  4422.      PROC ERROR
  4423.  
  4424.  
  4425.                             Programmer's Reference Manual
  4426.                                        Page 60
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.  
  4434.      ----------
  4435.      Used as the first level of error trapping provided to the programmer.  For
  4436.      a full discussion of errors and error handling, refer to Chapter 4.
  4437.  
  4438.      PROC KEY0-20
  4439.      ------------
  4440.      Used to link application code to function key sequences.  That is, pressing
  4441.      function key 0 (ESC on the IBM PC) causes PROC KEY0 to be executed
  4442.      immediately if in field entry mode and not executing (printing, search,
  4443.      etc.); pressing function key 1 causes procedure KEY1 to be executed
  4444.      immediately, etc.  If a procedure is not declared for a function key
  4445.      (except key 0), and that key is pressed, an error message is displayed on
  4446.      the screen.  The error may be recovered from by pressing the ESCAPE key.
  4447.  
  4448.      If procedure KEY0 is not defined and ESC is pressed, Q-PRO 4 will execute a
  4449.      SYSTEM command, which closes any open files and returns to the system. 
  4450.      This is the only function key with a "default value."
  4451.  
  4452.      PROC LOAD
  4453.      ---------
  4454.      Automatically executed the first time a format is loaded into memory.  It
  4455.      is typically used to open data files, set initial register contents, etc.
  4456.  
  4457.  
  4458.                                    Statement Types
  4459.                                    ---------------
  4460.  
  4461.      There is a wide variety of statement types in Q-PRO 4. Some, such as those
  4462.      that deal with file handling and error trapping, are dealt with in their
  4463.      own respective chapters.  All are fully defined in the System Commands
  4464.      chapter.  The following is a list of the various statement types, and the
  4465.      statements which fall into each category:
  4466.  
  4467.      File Handling
  4468.      -------------
  4469.      ERASE, OPEN, MAKE, CLOSE, PUT, GET, READ, WRITE, COPY, FREE, RESTART, POSN,
  4470.      SECURE, BACKSPACE, FILETYPE, RENAME, FSEAR, FCBADDR, KEY, FCOPY, RCLEAR
  4471.  
  4472.      Error Handling
  4473.      --------------
  4474.      ERRTRAP, ERROR, NCHECK
  4475.  
  4476.      Arithmetic
  4477.      ----------
  4478.      ADD, SUB, MUL, DIV, ROUND, CALC,  ^, MATHLIB, NOMATHLIB
  4479.  
  4480.      Logical
  4481.      -------
  4482.      SET, RESET
  4483.  
  4484.  
  4485.                             Programmer's Reference Manual
  4486.                                        Page 61
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.      Control Transfer
  4498.      ----------------
  4499.      GOTO, CALL, RETURN, CHAIN, END, FOR, ENDFOR, BRON, BROFF  
  4500.  
  4501.      Conditional
  4502.      -----------
  4503.      IF, ON, BEGIN, ENDBEGIN, WHILE, UNTIL, ELSE
  4504.  
  4505.      Screen Control
  4506.      --------------
  4507.      CLEAR, HOME, HOMECLEAR, NEXT, RESUME, LOCK, UNLOCK, BELL, BUFFER, CURSOR,
  4508.      PRINT, HON, HOFF, FILL 
  4509.  
  4510.      Data Formatting
  4511.      ---------------
  4512.      EDIT, UNEDIT, RJUST, LJUST, CENTER, CURRENCY, UCASE, INSTR
  4513.  
  4514.      Data Movement
  4515.      -------------
  4516.      MOVE, CONCAT, ASEAR
  4517.  
  4518.      Table Management
  4519.      ----------------
  4520.      TSEAR
  4521.  
  4522.      Operating System Interface
  4523.      --------------------------
  4524.      RUN, SYSTEM, FORMLOAD, NOFORMLOAD  
  4525.  
  4526.      Debugging
  4527.      ---------
  4528.      TRACE, NOTRACE, DEBUG, FORMLOAD, NOFORMLOAD
  4529.  
  4530.      Machine Language Interface
  4531.      --------------------------
  4532.      MEMEND, LOAD, EXEC, PEEK, POKE, DEFSEG, $MEMEND()
  4533.  
  4534.      Multiuser Management
  4535.      --------------------
  4536.      RLOCK, RUNLOCK, HOST, LPDETACH, LRETRY
  4537.  
  4538.      Miscellaneous
  4539.      * (COMMENT), PRINTSCN, SIZE, HELP, JDPACK, JDUNPACK, SETDATE, GETDATE
  4540.  
  4541.      Functions
  4542.      ---------
  4543.  
  4544.  
  4545.                             Programmer's Reference Manual
  4546.                                        Page 62
  4547.  
  4548.  
  4549.  
  4550.  
  4551.  
  4552.  
  4553.  
  4554.      $ASC(), $ETOX(), $FIELD(), $INT(), $LN(), $MEMEND(), $OFFSET()
  4555.  
  4556.  
  4557.      Expressions
  4558.      -----------
  4559.      Expressions are used by Q-PRO 4 as part of commands as calculations instead
  4560.      of literal numbers.  For example, a particular element in an array which is
  4561.      desired at a given time is 5 or ARRAY[5]; at another time, it may be 6,
  4562.      etc.  This element may be calculated in an expression such that it is
  4563.      dynamically set instead of explicitly set by ARRAY[expression].  The
  4564.      expression is any set of numeric data items such as:
  4565.  
  4566.           ARRAY[#N1+(#N2 * #N3)]
  4567.           ARRAY[ARRAY[#N3]]
  4568.  
  4569.                                     Screen Offset
  4570.                                     -------------
  4571.  
  4572.      The SCREEN OFFSET allows the programmer to address the fields on the screen
  4573.      as offsets from the first variable field.  The first screen data field on
  4574.      the screen, starting from top to bottom, right to left, is numbered zero
  4575.      (0).  The rest follow sequentially.  Thus, the programmer may dynamically
  4576.      select fields on the screen according to the program logic or a table
  4577.      look-up.  Either a literal or an expression may be used to address the
  4578.      field with the function $FIELD [numeric register, literal, or arithmetic
  4579.      expression]. 
  4580.  
  4581.      Example:
  4582.  
  4583.           MOVE $FIELD[5] TO $FIELD[6]
  4584.  
  4585.           Moves the sixth field on the screen, (counting from the top left field
  4586.           on the screen and going from left to right, top to bottom, starting
  4587.           with field zero) to the seventh field.
  4588.  
  4589.           The use of $FIELD allows handling of fields on the screen by position
  4590.           on the screen without worrying about the name of the field.  Thus, the
  4591.           combination of loops, registers and tables gives extraordinary screen
  4592.           handling capability.  #F can be used in this command.
  4593.  
  4594.      Example:  scrolling fields through the screen., using the screen format
  4595.      below:
  4596.  
  4597.           Field 0   ###############   Field 1  ##############
  4598.  
  4599.           Field 2   ###############   Field 3  ##############
  4600.           
  4601.  
  4602.      The program code:
  4603.  
  4604.  
  4605.                             Programmer's Reference Manual
  4606.                                        Page 63
  4607.  
  4608.  
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.           FOR #N0 = 0 TO 2
  4616.           * Begins a FOR loop from 0 to 2.
  4617.                MOVE $FIELD[#N0+1] TO $FIELD[#N0]
  4618.           * Moves FIELD 1 (#N0 plus 1) to FIELD 0. 
  4619.           * Then moves FIELD 2 to FIELD 1.  Then moves FIELD 3 to FIELD 2.
  4620.           ENDFOR #N0 
  4621.           END
  4622.           
  4623.           Note that in the contents of the brackets following the $FIELD will be
  4624.           evaluated as an expression.  This expression must evaluate to an
  4625.           integer.  The following are all valid:
  4626.  
  4627.           $FIELD[(#N1 * #N2) + 10]
  4628.           $FIELD[#N1 + #N2 - 20]
  4629.           $FIELD[SCNFIELD + 5]
  4630.           $FIELD[#F]
  4631.  
  4632.                                 Structured Programming
  4633.                                 ----------------------
  4634.       
  4635.      BEGIN and ENDBEGIN
  4636.      ------------------
  4637.      BEGIN denotes the beginning of the structured construct.  BEGINs may be
  4638.      nested and may have any of the following modifiers.
  4639.  
  4640.      BEGIN
  4641.      BEGIN WHILE . . . 
  4642.      BEGIN UNTIL . . . 
  4643.      BEGIN IF . . .
  4644.  
  4645.      ENDBEGIN denotes the end of the structured construct.  It can have any of
  4646.      the following modifiers
  4647.  
  4648.      ENDBEGIN
  4649.      ENDBEGIN WHILE . . .
  4650.      ENDBEGIN UNTIL . . .
  4651.  
  4652.           Examples:
  4653.                BEGIN WHILE A GT 0
  4654.                     SUB &VALUE(100) FROM A
  4655.                     READ 100
  4656.                ENDBEGIN
  4657.  
  4658.                BEGIN UNTIL A EQ 10
  4659.                     ADD 1 TO A
  4660.                ENDBEGIN
  4661.  
  4662.                BEGIN IF A NEQ 0
  4663.  
  4664.  
  4665.                             Programmer's Reference Manual
  4666.                                        Page 64
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.                     ADD 1 TO A
  4675.                ENDBEGIN
  4676.  
  4677.                BEGIN
  4678.                     SUB 1 FROM A
  4679.                ENDBEGIN WHILE A LT 100
  4680.  
  4681.      ELSE and ELSE IF
  4682.      ----------------
  4683.      An ELSE or ELSE IF is always associated with a BEGIN IF.  A BEGIN may have
  4684.      any number of IF statements associated with it.  
  4685.  
  4686.      Example:
  4687.           BEGIN IF #N1 GT 100
  4688.                     SUB 1 FROM #N2   
  4689.                ELSE IF #N1 LT 100
  4690.                      ADD 1 TO #N2
  4691.           ENDBEGIN
  4692.  
  4693.  
  4694.                               Tables and Table Handling
  4695.                               -------------------------
  4696.  
  4697.      One unique concept of Q-PRO 4 is that of the table as an addressable
  4698.      entity.
  4699.      A table is a data structure which can be applied to defining default
  4700.      values, verifying keyed-in values, replacing abbreviations with full text,
  4701.      setting up field lengths within records, and many other uses.  It appears
  4702.      as a one or two dimensional matrix, as the following sample table
  4703.      declarations illustrate:
  4704.  
  4705.      TABLE FIRST
  4706.           "ABCD"
  4707.           "DEF"
  4708.            END
  4709.  
  4710.      TABLE SECOND
  4711.           1, "PA"
  4712.           2, "NJ"
  4713.           3, "NY"
  4714.           END
  4715.       
  4716.      A table is conceptually regarded as having some number of rows (the first
  4717.      dimension) and some number of items within each row (the second dimension). 
  4718.      A row may have as few as one item, or as many as will fit on a line. Items
  4719.      MUST be separated by a comma (,).
  4720.  
  4721.      The first element in a table row is called the "key" or "argument" for that
  4722.      row, and is usually a numeric or string literal.  This key is used with the
  4723.  
  4724.  
  4725.                             Programmer's Reference Manual
  4726.                                        Page 65
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.  
  4733.  
  4734.      TSEAR statement to locate a particular row within a table. 
  4735.  
  4736.  
  4737.  
  4738.  
  4739.      Table Lookup and Data Verification
  4740.      ----------------------------------
  4741.      Let us suppose that a format screen has a screen data field named STATE,
  4742.      into which the operator will key the usual two-character state
  4743.      identification, but in which we desire to programmatically place the full
  4744.      name of the state, after verifying that the state is one of a valid list of
  4745.      states.  Further suppose that the following table had been declared:
  4746.  
  4747.           TABLE TSTATES
  4748.  
  4749.           "PA",     "PENNSYLVANIA"
  4750.           "DE",     "DELAWARE"
  4751.           "FL",     "FLORIDA"
  4752.           "GA",     "GEORGIA"
  4753.           "NJ",     "NEW JERSEY"
  4754.           "CA",     "CALIFORNIA"
  4755.           END
  4756.  
  4757.      Having this table, we can then verify the entry of a valid state in the
  4758.      field called STATE with the following TSEAR statement:
  4759.  
  4760.           TSEAR TSTATES AT STATE  :100
  4761.  
  4762.      This says the following:
  4763.  
  4764.        o  Within the table called TSTATES, find a row whose key is equal to the
  4765.           current value of the field STATE.
  4766.        o  If a match is found, then go to the next statement.   If no match is
  4767.           found, go label 100. 
  4768.  
  4769.      This use of the TSEAR statement gives us the ability to verify that the
  4770.      state keyed in was one of a valid list of states.
  4771.  
  4772.  
  4773.      Table Lookup, Verification and Replacement
  4774.      ------------------------------------------
  4775.      Going a step further with the example and table above, we can do both the
  4776.      validation and abbreviation replacement with TSEAR as follows:
  4777.  
  4778.       TSEAR TSTATES AT STATE,NSTATE  :100
  4779.  
  4780.      The same search for a match between STATE and a row key within TSTATES will
  4781.      occur.  However, when a match is found, the field NSTATE will take on the
  4782.      value of the next data item in the matched row after the key (here, the
  4783.  
  4784.  
  4785.                             Programmer's Reference Manual
  4786.                                        Page 66
  4787.  
  4788.  
  4789.  
  4790.  
  4791.  
  4792.  
  4793.  
  4794.      full name of the state).  If a whole set of information was tied to a
  4795.      particular state, for example, the beginning and ending ZIP codes, we could
  4796.      put all that data into the table and let TSEAR pull it out when the state
  4797.      is verified.
  4798.  
  4799.  
  4800.      Table Verification and Chaining
  4801.      -------------------------------
  4802.      Another use for tables is the verification of menu selections and
  4803.      subsequent CHAINing to the proper program segment.  For example, suppose we
  4804.      have an application menu as shown below:
  4805.  
  4806.  
  4807.                PAYROLL SYSTEM MENU
  4808.  
  4809.                1- ENTER EMPLOYEE DATA
  4810.  
  4811.                2- ENTER TIME CARDS
  4812.  
  4813.                3- PRINT CHECKS
  4814.  
  4815.                4- PRINT REGISTER
  4816.  
  4817.                5- CHANGE TAX DATA
  4818.  
  4819.                6- EXIT SYSTEM
  4820.  
  4821.                ENTER SELECTION [#]
  4822.  
  4823.      where # denotes a field defined with the name INPUT.  In one statement
  4824.      (using tables), a selection could be automatically verified, and the
  4825.      appropriate program selected for chaining.  The instructions to do this
  4826.      are:
  4827.  
  4828.      PROC ENTER
  4829.      * LOOK UP SELECTION AND GET  THE PROGRAM NAME IF FOUND
  4830.  
  4831.      TSEAR SELECTABLE AT INPUT,#S0  :100
  4832.      * IF PROGRAM NAME IS NULL, THEN WE ARE DONE
  4833.      IF #S0 EQ "" THEN SYSTEM
  4834.  
  4835.      * ELSE LOAD NEW APPLICATION PROGRAM
  4836.      CHAIN #S0
  4837.      100  * THE GIVEN SELECTION IS INVALID
  4838.           ERROR "INVALID CHOICE, PLEASE REENTER"
  4839.           END
  4840.  
  4841.      * THIS IS THE SELECTION TABLE
  4842.  
  4843.  
  4844.  
  4845.                             Programmer's Reference Manual
  4846.                                        Page 67
  4847.  
  4848.  
  4849.  
  4850.  
  4851.  
  4852.  
  4853.  
  4854.           TABLE SELECTABLE
  4855.           1,   "ENTEREMP"
  4856.           2,   "ENTERTC"
  4857.           3,   "PRINTCH"
  4858.           4,   "PRINTREG"
  4859.           5,   "CHANGETAX"
  4860.                END
  4861.  
  4862.      Note that if more selections are added, only the screen and the table need
  4863.      change.  This concept can readily be expanded to include the description
  4864.      line, as well as the file name within the table, so that only the table
  4865.      need be changed as the range of selections expands.
  4866.  
  4867.      Tables as Label Arrays
  4868.      ----------------------
  4869.      An alternative use for tables is as a procedure or label array.  In this
  4870.      use, a table name and index may be used instead of a procedure in a CALL
  4871.      statement, or instead of a label in a GOTO statement.
  4872.  
  4873.      Tables used in this manner are normally not used with the TSEAR command,
  4874.      since lines within the table consist not of keys optionally followed by
  4875.      data, but of single items which are either procedure names (for indexed
  4876.      calls) or labels (for indexed GOTOs).
  4877.  
  4878.      One use of the indexed CALL or GOTO feature might be responding to a menu
  4879.      selection (possibly even using the example above), as follows:
  4880.  
  4881.      PROC ENTER
  4882.      * FIRST VALIDATE THE INPUT
  4883.           IF INPUT = 1 AND INPUT =4 GOTO GOTBL[INPUT1]
  4884.           ERROR "INVALID SELECTION"
  4885.           END
  4886.  
  4887.      * TABLE CONTAINING LIST OF LABELS
  4888.      TABLE GOTBL
  4889.           100
  4890.           200
  4891.           300
  4892.           END
  4893.  
  4894.      Tables as Procedure Arrays
  4895.      --------------------------
  4896.      Another use might be in processing a data file record, whose first field is
  4897.      a record type, as follows:
  4898.  
  4899.      PROC DOREC
  4900.      * RECORD TYPE IS IN &RECTYPE[1]
  4901.           READ 2:EOF
  4902.      * CALL PROCESSOR FOR THIS TYPE
  4903.  
  4904.  
  4905.                             Programmer's Reference Manual
  4906.                                        Page 68
  4907.  
  4908.  
  4909.  
  4910.  
  4911.  
  4912.  
  4913.  
  4914.           CALL PROCTBL[&RECTYPE[1]]
  4915.           RETURN
  4916.           END
  4917.  
  4918.  
  4919.  
  4920.  
  4921.      * TABLE OF ROUTINES FOR DIFFERENT RECORD TYPES
  4922.                TABLE PROCTBL
  4923.                ADDREC
  4924.                DELREC
  4925.                CHANGEREC
  4926.                END
  4927.      Index values for CALL and GOTO tables start with 0 for the first item, 1
  4928.      for the second, etc.
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939.  
  4940.  
  4941.  
  4942.  
  4943.  
  4944.  
  4945.  
  4946.  
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956.  
  4957.  
  4958.  
  4959.  
  4960.  
  4961.  
  4962.  
  4963.  
  4964.  
  4965.                             Programmer's Reference Manual
  4966.                                        Page 69
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.                                FILES AND FILE HANDLING
  4976.                                =======================
  4977.  
  4978.  
  4979.      File Handler
  4980.      ------------
  4981.      Q-PRO 4, Version 4.0, uses a sophisticated, state-of-the-art B+ tree,
  4982.      multikey file handler.  This file handler is the file BTSYS.EXE, which is
  4983.      terminate and stay resident.  You must load BTSYS or no file handling will
  4984.      occur.  It must be loaded before anything else in the Q-PRO 4 and Q-N-E
  4985.      system.
  4986.  
  4987.      File System Interrupts
  4988.      ----------------------
  4989.      BTSYS uses interrupts 80h, 81h, and 82h.  Other terminate and stay resident
  4990.      programs also grab whatever they want.  As there may be conflict, BTSYS's
  4991.      interrupts are configurable by establishing a DOS system variable, QNEFSI. 
  4992.      For example, to change the interrupts to 8Ah, 8Bh, and 8Ch. before BTSYS is
  4993.      loaded, from AUTOEXEC.BAT or from the command line SET QNESFI = 8A.    
  4994.  
  4995.      Loading BTSYS
  4996.      -------------
  4997.      From the system prompt, type:  BTSYS <cr>
  4998.  
  4999.           or
  5000.  
  5001.           BTSYS QNE  <program name> <cr>
  5002.  
  5003.           (This unloads BTSYS when the program is finished.)
  5004.  
  5005.      From a .BAT file:
  5006.  
  5007.                BTSYS
  5008.  
  5009.                or
  5010.  
  5011.                BTSYS QNE <program name>
  5012.  
  5013.           (This unloads BTSYS when the program is finished.)
  5014.  
  5015.      Unloading BTSYS
  5016.      ---------------
  5017.      From the command line, type:  BTSYS /U <cr>
  5018.  
  5019.  
  5020.  
  5021.  
  5022.  
  5023.  
  5024.  
  5025.                                Files and File Handling
  5026.                                        Page 70
  5027.  
  5028.  
  5029.  
  5030.  
  5031.  
  5032.  
  5033.  
  5034.      File Limitations
  5035.      ----------------
  5036.      Q-PRO 4 has few limitations on files.  These are shown below:
  5037.  
  5038.      Characteristic                          Limit
  5039.        
  5040.       Maximum Field Size                255 characters
  5041.       Maximum Record Size               65K (memory allowing)
  5042.       Maximum File Size                 2 Gbytes
  5043.       Maximum Files Open at One Time    255 (memory allowing)
  5044.       
  5045.  
  5046.      File Types
  5047.      ----------
  5048.      Q-PRO 4 supports four types of files:
  5049.  
  5050.           o random
  5051.           o multi-key index sequential
  5052.           o sequential
  5053.           o sequential with comma delimited fields (SDF files)
  5054.  
  5055.      Common data file handling statements are used for each type of file.  As a
  5056.      programming convenience, access to the system print device is performed
  5057.      with file-like statements. 
  5058.  
  5059.  
  5060.                           Multi-key Indexed Sequential Files
  5061.                           ----------------------------------
  5062.  
  5063.      File Keys
  5064.      ---------
  5065.      Each file may have up to 9 keys or sort sequences. All keys are updated
  5066.      when the record is written.  The primary key may not be duplicated. 
  5067.      Rewriting a record with the same primary key will have the effect of
  5068.      updating the current record; it will NOT create a new record.  You may
  5069.      change keys at any time but you must remember that the file position will
  5070.      not be changed.
  5071.  
  5072.      Records in indexed files are accessed by an alphanumeric key, not by a
  5073.      record number.  The key consists of up to 128 alphanumeric characters.  It
  5074.      may be multi-field and the fields need not be adjacent.      
  5075.  
  5076.      Reading and Writing
  5077.      -------------------
  5078.      Indexed files may be read any key order or in physical order.  When writing
  5079.      a record, the controlling key is the PRIMARY.  In other words, even if you
  5080.      are using a secondary key, the file handler will create the record
  5081.      positioning information correctly.
  5082.  
  5083.  
  5084.  
  5085.                                Files and File Handling
  5086.                                        Page 71
  5087.  
  5088.  
  5089.  
  5090.  
  5091.  
  5092.  
  5093.  
  5094.      When reading an indexed file, it is important to remember that the keys are
  5095.      LEFT JUSTIFIED ASCII CHARACTERS.  In this sense, numbers are considered
  5096.      characters not numbers.  When positioning to a record, the file handler
  5097.      compares the record key and the search key from left to right looking for a
  5098.      match.
  5099.         
  5100.      Physical Order
  5101.      --------------
  5102.      In addition to the 9 keys, the file may be read, positioned, and backspaced
  5103.      in physical order (the order in which it was created) by setting it in key
  5104.      0.  A numeric expression must be used for the record number in the position
  5105.      command.  The BACKSPACE command will back up the file one physical record. 
  5106.  
  5107.      All other commands that affect indexed files will work normally, that is to
  5108.      say, if a record is written, it will be written as an indexed record.
  5109.      If a deleted record is read, then trappable error number 34, Deleted record
  5110.      read.  The record will be loaded into the record buffer. (You can take
  5111.      advantage of this characteristic to recover deleted records.)  
  5112.  
  5113.      Data File
  5114.      ---------
  5115.      An indexed file set consists of two files, the data file which is an ASCII
  5116.      file, and an index file.  Within the file each record is allocated an 8
  5117.      byte internal control field.  If any character, except blank (decimal 32)
  5118.      is in the first 8 bytes, the record is inactive.  Each record is terminated
  5119.      with a carriage return/line feed.  The minimum record length is 10 bytes.
  5120.  
  5121.      Index File
  5122.      ----------
  5123.      There is one index file no matter how many indices are active.  The index
  5124.      file retains all data, even if it is flagged as inactive.  Therefore, the
  5125.      index file may get quite large.  Running the utility QMAINT with the PACK
  5126.      option will compress the index file.    
  5127.      As data records are added to the indexed file, keys are added and the nodes
  5128.      of the index file will split, leaving voids that will be used as the file
  5129.      is updated.
  5130.  
  5131.      The size of the index file is a function of the number of keys, number of
  5132.      records in the data file, and the size of the keys.  The size of the key
  5133.      should be kept as small as possible since the actual key is the secondary
  5134.      key with the primary key appended. 
  5135.  
  5136.      Although a B+ tree index never needs to be balanced, occasionally it should
  5137.      be packed to reclaim disk space.  The state of the index, packed or not,
  5138.      does not materially affect the speed of adding, deleting, or retrieving
  5139.      records.
  5140.  
  5141.      In a single user mode, key nodes are buffered.  Setting BUFFERS = 40 in
  5142.      PC-DOS or MS-DOS is highly recommended.
  5143.  
  5144.  
  5145.                                Files and File Handling
  5146.                                        Page 72
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.  
  5154.  
  5155.  
  5156.      Deleted Records
  5157.      ---------------
  5158.      Inactive or deleted records are removed automatically by the file handler
  5159.      if there is frequent corresponding record addition.  The user may remove
  5160.      them with a simple Q-PRO 4 routine to copy the old file with the deleted
  5161.      records to a new file.
  5162.  
  5163.      File Maintenance
  5164.      ----------------
  5165.      The program, QMAINT, has facilities for:
  5166.  
  5167.           o    VERIFYing, or validating, the index file against the data file.
  5168.           o    PACKing, or compressing the index file.
  5169.           o    RECOVERing a damaged index file.  The data file is pure ASCII and
  5170.                can be repaired with any ASCII file handling techniques.  The
  5171.                RECOVER option creates a new index file from the data file.  The
  5172.                implications are, among others:
  5173.  
  5174.                1.   You can delete the index file altogether and still rebuild
  5175.                it.
  5176.  
  5177.                2.   You need only store the data files for backup.
  5178.  
  5179.       
  5180.                                      Random Files
  5181.                                      ------------
  5182.  
  5183.      Structure
  5184.      ---------
  5185.      Random files are identical in structure to indexed files, except there is
  5186.      no index file.  Records may be read or written in order or directly
  5187.      accessed by record number within the file (0 is the record number of the
  5188.      first record). The file's record size may be any length.
  5189.  
  5190.      Maintenance
  5191.      -----------
  5192.      The user is responsible for determining all aspects of a random file's
  5193.      maintenance.  Records are not deleted; the user must keep track of records
  5194.      that he no longer wants to use.
  5195.  
  5196.                                Sequential (text) Files
  5197.                                -----------------------
  5198.  
  5199.  
  5200.      Sequential files are in standard ASCII format, and are compatible with most
  5201.      standard text files (for example, those produced by editors or word
  5202.      processors).  Records in these files may be of varying length.  Records are
  5203.  
  5204.  
  5205.                                Files and File Handling
  5206.                                        Page 73
  5207.  
  5208.  
  5209.  
  5210.  
  5211.  
  5212.  
  5213.  
  5214.      separated with a carriage return/line feed sequence.  Sequential files may
  5215.      be opened only for output, or only for input, and are accessed in
  5216.      sequential record order only.
  5217.  
  5218.                              SDF (Comma Delimited) Files
  5219.                              ---------------------------
  5220.  
  5221.      SDF files are identical to sequential files; except that in an SDF file
  5222.      record, all data fields are delimited by quotes and separated by commas. 
  5223.      Q-PRO 4 will always delimit fields by quotes, but can process records
  5224.      written by other systems which may not put quotes around numeric fields.
  5225.  
  5226.  
  5227.                            Indexed and Random File Handling
  5228.                            --------------------------------
  5229.      Fundamentals
  5230.      ------------
  5231.      All file operations are based on the concept of a file buffer in memory. 
  5232.      The buffer is established with the MAKE or OPEN statement, and removed with
  5233.      the CLOSE statement.  Data coming into or out from a Q-PRO 4 program first
  5234.      passes through a file buffer.
  5235.  
  5236.      A file buffer may be thought of as a string of data.  This string may be
  5237.      accessed in a symbolic, high-level manner (using file field names), or in a
  5238.      specific, low-level manner (using the relative location of data fields
  5239.      within the string).
  5240.  
  5241.      In the course of opening or creating a file, the programmer assigns it a
  5242.      number from 1 to 255.  Thereafter, the file is referenced by its assigned
  5243.      number.
  5244.  
  5245.      Data Dictionary (FID) Files
  5246.      ---------------------------
  5247.      The most convenient method to access fields in a data file record buffer is
  5248.      by name.  To do so, the programmer must first build a FID (file item
  5249.      descriptor, or data dictionary) file using the FID file generator.  The FID
  5250.      file is, in essence, a list of field names and their locations within the
  5251.      record.  To store data in the record, or to extract the data, the
  5252.      programmer need only reference the file data field by name, just like a
  5253.      screen data field, variable, or register.  Not only is this simple to
  5254.      program, but also the program becomes almost completely independent of the
  5255.      record format.  This means that when the record format changes, only the
  5256.      file changes (not the program)!
  5257.  
  5258.      A "data dictionary" facility means that there is a means of documenting
  5259.      file contents and layout.  This is the FID generator which is discussed in
  5260.      detail in its own section.  This high level means of accessing file data is
  5261.      only available for random and indexed files.
  5262.  
  5263.  
  5264.  
  5265.                                Files and File Handling
  5266.                                        Page 74
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.      A single data dictionary file may be used for multiple data files. 
  5275.      CAUTION:  Each data file requires its own index file.   Note: A data file
  5276.      must have at 10 characters of data.
  5277.  
  5278.      PC-DOS and MS-DOS File Considerations
  5279.      -------------------------------------
  5280.      For reasons known only to MicroSoft and the mighty blue giant, IBM, their
  5281.      operating systems, MS-DOS and PC-DOS, allow only up to 20 open files
  5282.      (handles) to be used by any one process.  This 20 file limitation is set
  5283.      only if FILES is set to 20 in CONFIG.SYS.  The operating system hogs five
  5284.      handles for itself leaving 15 for the process.  We take one for QNE.EXE
  5285.      which leaves 14 for data files and their associated index files.  Each data
  5286.      file takes one handle and each index takes one handle.
  5287.  
  5288.      Obviously, for useful applications, more than seven indexed data files are
  5289.      a necessity.  So we have found a way to get around the system limits.  As
  5290.      the file system uses files it will eventually run out of file handles.  It
  5291.      will then close the least recently used file that is not locked or has no
  5292.      records locked, and then it will open or reopen the target file.  For
  5293.      example, when you use an eighth data file, the file handler will close one
  5294.      of the other seven data files and open the eighth data file.  If you have
  5295.      many open files in an application, you pay the consequences of the
  5296.      shortsightedness of the masters of software with a lengthened time to open
  5297.      the files when loading the program.  Additionally, there may be a
  5298.      noticeable delay when accessing a file because another file may have to be
  5299.      physically closed and the file being accessed re-opened.  This file
  5300.      handling is transparent to the application designer as the files stay open
  5301.      logically.
  5302.  
  5303.      In the future if the maintainers of DOS, in their wisdom should awaken to
  5304.      the real world, the file system will automatically adjust and open more
  5305.      files before it has go into the virtual file handle mode.
  5306.  
  5307.      File Restructuring
  5308.      ------------------
  5309.      Q-PRO 4 indexed and random files can be restructured, that is new fields
  5310.      added or deleted and/or keys added, changed or removed by writing a simple
  5311.      Q-PRO 4 program.  The principle is to read the old file with its data
  5312.      dictionary and write a new one using the new data dictionary.  The new file
  5313.      will be in the new structure.  The code fragment below illustrates the
  5314.      technique.
  5315.  
  5316.           PROC RESTRUCT
  5317.      * Open the old data file and create a new one to copy to.
  5318.           OPEN "OLD_DAT.DAT" USING "OLD_DAT.FID",1:10
  5319.           MAKE "NEW_DAT.DAT" USING "NEW_DAT.FID",2:20
  5320.  
  5321.      * Read old file and copy/write it to the new until end of file.
  5322.           :L   READ 1:EN
  5323.  
  5324.  
  5325.                                Files and File Handling
  5326.                                        Page 75
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.                COPY 1 TO 2
  5335.                WRITE 2:30
  5336.                GOTO L
  5337.           :EN  END
  5338.  
  5339.                                 File Handling Commands
  5340.                                 ----------------------
  5341.  
  5342.      The following paragraphs discuss in detail the Q-PRO 4 statements dealing
  5343.      with file handling.  Each function is further broken down by file type,
  5344.      with an explanation of the implications of each statement for each file
  5345.      type.
  5346.      The full syntax is described in the Q-PRO 4 Commands Chapter.
  5347.  
  5348.      MAKE
  5349.      ----  
  5350.      This statement creates a file (after first deleting it if it already
  5351.      exists) and leaves the file open for later processing.  The syntax of the
  5352.      MAKE statement has four variations, depending on the file type involved.
  5353.  
  5354.      OPEN
  5355.      ----
  5356.      The function of this statement is similar to that of MAKE, except that it
  5357.      refers to a file already in existence on disk.  Therefore, an attempt to
  5358.      open a non-existent file will result in an error.  DO NOT use OPEN to
  5359.      determine if a file is already open, use the FILETYPE command.
  5360.  
  5361.      FILETYPE
  5362.      --------
  5363.      This command has two functions:
  5364.  
  5365.           1.   It returns information about currently open files.
  5366.           2.   It determines if a file is open or closed.
  5367.  
  5368.      CLOSE
  5369.      -----
  5370.      This statement tells Q-PRO 4 that a data file is no longer required for
  5371.      processing.  Although all files will be closed automatically when Q-PRO 4
  5372.      returns to the operating system, good programming practices suggest that
  5373.      files should always be explicitly closed when no longer needed.
  5374.  
  5375.      SECURE
  5376.      ------
  5377.      This command has the same effect on an indexed file as CLOSE, in that it
  5378.      forces the immediate update of internal file information required by Q-PRO
  5379.      4.  However, the file is still left open after the SECURE operation for
  5380.      further processing.  This information is potentially changed after every
  5381.      WRITE or FREE operation.
  5382.  
  5383.  
  5384.  
  5385.                                Files and File Handling
  5386.                                        Page 76
  5387.  
  5388.  
  5389.  
  5390.  
  5391.  
  5392.  
  5393.  
  5394.           Warning:  Turning off the computer without CLOSEing or SECUREing the
  5395.           data files will always corrupt them.  Worse, the operating system will
  5396.           not update the directory and data will be lost.
  5397.  
  5398.  
  5399.  
  5400.      PUT
  5401.      ---
  5402.      PUT is most often used to print directly from Q-PRO 4 and writing
  5403.      sequential and SDF files.  It is not normally used when dealing with files
  5404.      using the FID file option, although it can be.
  5405.  
  5406.      The PUT statement places a data item into a file or printer buffer for
  5407.      later output with the WRITE statement.  (PUT to a sequential file does
  5408.      immediate output.)
  5409.  
  5410.      GET
  5411.      ---
  5412.      GET is not usually used with indexed and random files using FIDs, although
  5413.      it can be.
  5414.  
  5415.      The GET statement retrieves data from a file buffer and stores it into a
  5416.      register or field.  GET is essentially the opposite operation from PUT in
  5417.      this respect.  Be careful when GETting from random or indexed files to
  5418.      avoid overflowing the record buffer.
  5419.  
  5420.      KEY
  5421.      ---
  5422.      The KEY command changes the file key reference of a multikeyed indexed
  5423.      file.  When the file is created or opened, the default file key is one (1). 
  5424.      When the key is changed, all file movements:  POSN, READ, BACKSPACE, etc.
  5425.      will be understood to be in the current key sequence and at the current
  5426.      file position.
  5427.  
  5428.      POSN
  5429.      ----
  5430.      This statement positions the data file to a specific record for reading or
  5431.      writing (random/indexed files only).
  5432.  
  5433.      POSN RELATIVE
  5434.      -------------
  5435.      For indexed files, if the desired key does not exist and the keyword
  5436.      RELATIVE is not given, a READ command to the file will give an end-of-file
  5437.      error.  If the keyword RELATIVE is given, then the file is left positioned
  5438.      at the nearest key higher in value than the key originally specified (if
  5439.      such a key exists).
  5440.  
  5441.      POSN USING
  5442.      ----------
  5443.  
  5444.  
  5445.                                Files and File Handling
  5446.                                        Page 77
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.  
  5454.      A variation of the POSN command allows positioning and changing the data
  5455.      file key at the same time.  Obviously, this variant is only used with
  5456.      indexed files.
  5457.  
  5458.  
  5459.  
  5460.      READ
  5461.      ----
  5462.      The READ command loads a data buffer with the currently positioned record
  5463.      (random or indexed files), or advances to the start of the next record
  5464.      (sequential).
  5465.  
  5466.      WRITE
  5467.      -----
  5468.      The WRITE command outputs a data record to a file (random/indexed), or
  5469.      outputs a carriage return/line feed sequence to a file (sequential).
  5470.  
  5471.      RESTART
  5472.      -------
  5473.      This command resets the file buffer pointer to any position within the data
  5474.      buffer (does not apply to sequential files).  This is especially of use in
  5475.      an environment where records are read, displayed, and updated using GETS
  5476.      and PUTS, whether fields occur in sequential order within the record or
  5477.      not.
  5478.  
  5479.      FREE
  5480.      ----
  5481.      The FREE statement marks a record in an indexed file as deleted.  To delete
  5482.      a record, it must be first loaded into the file's data buffer using a READ. 
  5483.      To insure the presence of the correct record, the usual procedure to delete
  5484.      an indexed file record is the command sequence:  POSN, READ, FREE.
  5485.  
  5486.      BACKSPACE
  5487.      ---------
  5488.      This statement moves the file backwards one record from the current
  5489.      position.  It is only used for random or indexed sequential files.  An
  5490.      end-of-file error is generated if there are no records in the file, or if
  5491.      the file is already positioned at the first record. 
  5492.  
  5493.      COPY
  5494.      ----
  5495.      COPY is used only with data files that have FIDs.  It is used for rapid
  5496.      transfer of data from a file to the screen, from the screen to a file, or
  5497.      from a file to another file.
  5498.  
  5499.      FCOPY
  5500.      -----
  5501.      FCOPY copies a file to a file.  No wild cards are allowed.
  5502.  
  5503.  
  5504.  
  5505.                                Files and File Handling
  5506.                                        Page 78
  5507.  
  5508.  
  5509.  
  5510.  
  5511.  
  5512.  
  5513.  
  5514.      FSEAR
  5515.      -----
  5516.      FSEAR searches a data file on a record-by-record basis for the satisfaction
  5517.      of any logical condition.
  5518.  
  5519.  
  5520.  
  5521.  
  5522.  
  5523.  
  5524.  
  5525.  
  5526.  
  5527.  
  5528.  
  5529.  
  5530.  
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.  
  5563.  
  5564.  
  5565.                                Files and File Handling
  5566.                                        Page 79
  5567.  
  5568.  
  5569.  
  5570.  
  5571.  
  5572.  
  5573.  
  5574.                                     ERROR HANDLING
  5575.                                     ==============
  5576.  
  5577.  
  5578.                                        General
  5579.                                        -------
  5580.  
  5581.      There are two basic types of errors that may occur within a Q-PRO 4
  5582.      program:
  5583.  
  5584.       o   Those that are handled automatically within the system.  Examples of
  5585.           automatic errors are:  syntax error (always fatal), or an invalid
  5586.           character typed in a field (recoverable by the operator).  Since these
  5587.           errors are always handled in the same manner by the system (and are
  5588.           inaccessible to the format program), the reader is referred to the
  5589.           Error Section for a list of these errors.
  5590.  
  5591.       o   Those that optionally may be handled by the user program.  Errors
  5592.           which can be handled by the program are termed "trappable" errors. 
  5593.           Error trapping is hierarchical in nature.  There is a hierarchy of
  5594.           error trapping is shown below.
  5595.       
  5596.           1.   Local Error Traps.  A local error trap is designated by the colon
  5597.                (:) and a line number or label at the end of the command.  If a
  5598.                local error trap is designated, it overrides any other error
  5599.                traps.
  5600.  
  5601.           2.   ERRTRAP.  If there is no local error trap ERRTRAP will execute
  5602.                (if present).  Note that ERRTRAP has precedence and overrides
  5603.                PROC ERROR.
  5604.  
  5605.           3.   PROC ERROR.  If there is no local error trap, or ERRTRAP control
  5606.                of the program will go to PROC ERROR.
  5607.  
  5608.      If no error trapping is specified, a trappable error will be handled as a
  5609.      fatal error.
  5610.  
  5611.                                   Local Error Traps
  5612.                                   -----------------
  5613.  
  5614.      Nature of a Local Trap
  5615.      ----------------------
  5616.      Certain statements (generally file-oriented statements and TSEAR) may
  5617.      designate line numbers or labels to act as error traps for that statement
  5618.      only.  These "local traps" override the presence of an ERRTRAP or PROC
  5619.      ERROR (described below).  Functionally the local error trap is analogous to
  5620.      "ON ERROR GOTO XXX" .
  5621.  
  5622.  
  5623.  
  5624.  
  5625.  
  5626.                                     Error Handling
  5627.                                           80
  5628.  
  5629.  
  5630.  
  5631.  
  5632.  
  5633.  
  5634.  
  5635.  
  5636.  
  5637.      Registers
  5638.      ---------
  5639.      In contrast to the more global types of error trapping (PROC ERROR and
  5640.      ERRTRAP), however, the contents of #N0 and #S0 are unchanged in an error
  5641.      condition.  In most circumstances this results in no loss of flexibility,
  5642.      since the type of error trapped is usually predictable, depending on the
  5643.      statement executed.  In the following example, a local error trap is
  5644.      associated with a read statement to detect an end-of-file condition.
  5645.  
  5646.      PROC READREC
  5647.      * Input the next record
  5648.           READ 5 :1001
  5649.      * Load the data field
  5650.           CALL LOADREC
  5651.           END
  5652.      *We go here at file end
  5653.  
  5654.      1001 CLOSE 5
  5655.           ERROR "END OF DATA ENCOUNTERED"
  5656.           CHAIN "MENU"
  5657.           END
  5658.  
  5659.  
  5660.                                       PROC ERROR
  5661.                                       ----------
  5662.  
  5663.      When PROC ERROR Is Invoked
  5664.      --------------------------
  5665.      The standard procedure ERROR receives control when a trappable error occurs
  5666.      and there is no local error trap or ERRTRAP.
  5667.      At the time of the error, the error number (as listed in Appendix A) will
  5668.      be placed in numeric register 0 (#N0), the system level error will be
  5669.      placed in the system error register (#E) and the error message will be
  5670.      placed in string register 0 (#S0).
  5671.  
  5672.      In general the system error register (#E) is more valuable for the low
  5673.      level information needed for debugging.  
  5674.  
  5675.      Example of Use
  5676.      --------------
  5677.      The following is an example of an ERROR procedure.  In this example, the
  5678.      procedure checks for a "file unavailable" error (presumably caused by
  5679.      trying to open a non-existent file) and, if so, displays an error message
  5680.      and returns to the operating system.  Otherwise, the system generated error
  5681.      message is displayed and the statement that caused the error is re-executed
  5682.      if PROC ERROR is terminated with RETURN or END.  A GOTO in PROC ERROR will
  5683.      cause stack overflow problems and, presumably, a call to us for help.
  5684.  
  5685.  
  5686.  
  5687.                                     Error Handling
  5688.                                           81
  5689.  
  5690.  
  5691.  
  5692.  
  5693.  
  5694.  
  5695.  
  5696.      Example of PROC ERROR
  5697.       
  5698.      PROC ERROR
  5699.      * No file error?
  5700.           IF #N0 EQ 13 THEN GOTO 1
  5701.      * Some other error - just display it
  5702.           ERROR #S0
  5703.           END
  5704.  
  5705.      * Display NO FILE error
  5706.      1  ERROR "CAN'T FIND DATA FILE"
  5707.           SYSTEM
  5708.           END
  5709.  
  5710.                                        ERRTRAP
  5711.                                        -------
  5712.  
  5713.      The ERRTRAP facility is used in the same manner as a local error trap,
  5714.      except that it may be used to redirect error trapping to different segments
  5715.      of code.  Each field procedure, for example, could have its own error trap
  5716.      routine.  Note:  error traps set by ERRTRAP override the existence of PROC
  5717.      ERROR.
  5718.      ERRTRAP uses the same registers as PROC ERROR.
  5719.  
  5720.      The following is an example of a procedure with its own error trap.
  5721.  
  5722.  
  5723.      PROC FOPEN
  5724.      * Set error trap
  5725.           ERRTRAP 10
  5726.           OPEN "DATAFILE",1,1
  5727.           MOVE "FILE OPEN" TO STATUS
  5728.      * Done, clear the error trap
  5729.           ERRTRAP
  5730.           NEXT CUSTNO
  5731.      * Error, look for no file error
  5732.      10   IF #N0 EQ 13 THEN GOTO 11
  5733.      * Some other error - display it
  5734.           ERROR #S0
  5735.           END
  5736.  
  5737.      * File not there, create it
  5738.      * Clear the error trap first
  5739.      11   ERRTRAP
  5740.           MAKE "DATAFILE",1,1
  5741.           MOVE "FILE CREATED" TO STATUS
  5742.           END
  5743.  
  5744.      Note that the ERRTRAP line number previously designated as an ERRTRAP is
  5745.      disabled by another ERRTRAP statement that has no line number.
  5746.  
  5747.  
  5748.                                     Error Handling
  5749.                                           82
  5750.  
  5751.  
  5752.  
  5753.  
  5754.  
  5755.  
  5756.  
  5757.  
  5758.  
  5759.  
  5760.      System Error Register - #E
  5761.      --------------------------
  5762.      In all three of the above techniques for handling errors, the error number
  5763.      register (#E) may be examined.  This register contains the specific error
  5764.      code returned by the operating system in response to a file operation
  5765.      request (as opposed to #N0, which returns a Q-PRO 4 level error code).
  5766.  
  5767.  
  5768.  
  5769.  
  5770.  
  5771.  
  5772.  
  5773.  
  5774.  
  5775.  
  5776.  
  5777.  
  5778.  
  5779.  
  5780.  
  5781.  
  5782.  
  5783.  
  5784.  
  5785.  
  5786.  
  5787.  
  5788.  
  5789.  
  5790.  
  5791.  
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797.  
  5798.  
  5799.  
  5800.  
  5801.  
  5802.  
  5803.  
  5804.  
  5805.  
  5806.  
  5807.  
  5808.  
  5809.                                     Error Handling
  5810.                                           83
  5811.  
  5812.  
  5813.  
  5814.  
  5815.  
  5816.  
  5817.  
  5818.  
  5819.                               LANS and MULTIUSER SYSTEMS
  5820.                               --------------------------
  5821.  
  5822.                                        General
  5823.                                        -------
  5824.  
  5825.      The multiuser or local area network (LAN) poses many complex problems for
  5826.      the application developer.  For the most part, the documentation furnished
  5827.      with the operating system is either sparse or confusing, or both.  Q-PRO 4
  5828.      must work within the constraints of the operating system no matter how
  5829.      illogical its design may be.  This chapter attempts to explain the
  5830.      functioning of the Q-PRO 4 commands and how the operating system handles
  5831.      them.
  5832.  
  5833.      The Q-PRO 4 shareware version is a LAN, Multiuser version.  The multiuser
  5834.      runtime will always run on a matching single user operating system.  For
  5835.      example PC-DOS programs will run with a PC-LAN runtime.
  5836.  
  5837.      Principles
  5838.      ----------
  5839.      The system works on a principle of "mutual exclusion" at the statement
  5840.      level.  This means that, under program control, a record may be locked so
  5841.      that one user will not be changing a record when another user is searching
  5842.      for a record.  Similarly, the programmer has control over the way files are
  5843.      opened, LOCKED, UNLOCKED, and/or READ ONLY.
  5844.  
  5845.      This is achieved by system calls and is transportable from operating system
  5846.      to operating system.  This locking process is always under the programmer's
  5847.      control and is transparent to users.  Q- PRO 4 will try one time to get a
  5848.      data record lock and a setable number of times (set with LRETRY) to get a
  5849.      header record lock before reporting an error (failure to get a lock) if the
  5850.      record is already locked to the programmer.  It is up to the programmer to
  5851.      decide what to do when a lock is attempted and the record is already
  5852.      locked.  It is a must, however, that programs attempt to lock a record
  5853.      before doing a read for update or a record deletion.
  5854.  
  5855.  
  5856.                                   Multiuser Commands
  5857.                                   ------------------
  5858.  
  5859.      The following Q-PRO 4 commands are specifically for multiuser operating
  5860.      system control.  See the commands section for syntax and examples.
  5861.  
  5862.      HOST
  5863.      ----
  5864.      The HOST is set with the HOST statement in the program code, typically in
  5865.      PROC LOAD.  HOST sets the type of multiuser system the application is
  5866.      running under.  NO files may be open when this command is executed.  If
  5867.  
  5868.  
  5869.                                         LAN's
  5870.                                        Page 84
  5871.  
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.      MULTIUSER data files are to be shared, the host value must be set to a
  5879.      multiuser value (that is, not SINGLE) or ALL the files may be corrupted if
  5880.      updated.  Once set, the selected HOST remains until running under another
  5881.      HOST is selected or the application returns to the multiuser operating
  5882.      system.
  5883.  
  5884.      RLOCK
  5885.      -----
  5886.      RLOCK is ignored if the system is not in multiuser mode.  If the system is
  5887.      in multiuser mode, it will lock the record on which the file is currently
  5888.      positioned (regardless of what record, if any, is currently in the data
  5889.      buffer).  If the application has previously locked a record in the same
  5890.      file, the lock is released before attempting a new lock, even if the
  5891.      attempt at the new lock is unsuccessful. 
  5892.  
  5893.      An error will occur if the record is locked by another application, an
  5894.      adjacent record in the same sector is locked, or if the file is busy.  The
  5895.      error returned is a file exclusion failure, error code 25.  The programmer
  5896.      may choose to have the application try the lock again or try to lock some
  5897.      other record.  Any other error should be treated as a fatal error.
  5898.      Note that the protocol of locking a position in a file before trying to do
  5899.      something with the record at that position is entirely at the option of the
  5900.      application programmer.  Nothing in multiuser operating systems, at the
  5901.      current level of technology, prevents an application from reading a record
  5902.      locked by someone else, if so desired.
  5903.  
  5904.      RLOCK locks the record position being pointed to in the file buffer.  It
  5905.      unlocks a previous lock if there is one.
  5906.  
  5907.      RUNLOCK
  5908.      -------
  5909.      RUNLOCK unlocks a record that has been locked by the RLOCK command.  
  5910.  
  5911.      LRETRY
  5912.      ------
  5913.      The LRETRY command sets the number of times a lock is attempted.  This
  5914.      value may be increased to help avoid timeouts on waiting for the header. 
  5915.      Be careful when you use this command for you must give the system enough
  5916.      time to react.
  5917.  
  5918.      OPEN and MAKE
  5919.      -------------
  5920.      OPEN and MAKE have two optional keywords after the file number, UNLOCKED
  5921.      and R/O (read/only). By default, a file is opened as read/write and locked. 
  5922.      These keywords can be in any order and need not appear together.  If a file
  5923.      is not opened in the unlocked mode, then only one application can open the
  5924.      file.  (Note: some systems do not support files in locked mode.)  Any other
  5925.      application attempting to use the same file will get the error, 'file
  5926.      unavailable' (error code 6).
  5927.  
  5928.  
  5929.                                         LAN's
  5930.                                        Page 85
  5931.  
  5932.  
  5933.  
  5934.  
  5935.  
  5936.  
  5937.  
  5938.  
  5939.      In almost all applications, but especially applications where unavailable
  5940.      files may occur, to be safe, MAKE all the files during application
  5941.      installation before any other application starts.  With this technique, if
  5942.      error code 6 is returned, the programmer will know it was because the file
  5943.      was locked (not because the file was not there).  This error also may occur
  5944.      if a MAKE is attempted on a file that is locked by another user.  If files
  5945.      are being opened in unlocked mode (shared), a file exclusion lock may occur
  5946.      if the file is already opened by another user and is busy (see notes on
  5947.      file busy).
  5948.  
  5949.      READ
  5950.      ----
  5951.      The READ command can return two additional errors in multiuser mode:
  5952.  
  5953.        1. The first is a file exclusion failure, error code 25 (file was busy). 
  5954.           This does not necessarily mean that the record trying to be read is
  5955.           locked.  Instead, it means that the file was busy processing a request
  5956.           for another application.  The read may be tried again.
  5957.  
  5958.        2. The second additional error is a file sync failure, error code 26.  A
  5959.           sync error may occur under the following two circumstances (or
  5960.           variants thereof):
  5961.  
  5962.             o  the application positions to a record, but before the record is
  5963.                locked and read another application deletes the record.
  5964.             o  The application does a read without NOADV, intending to go to the
  5965.                next record.  If that record is then deleted by some other
  5966.                application before it is read, a sync error can also occur. 
  5967.  
  5968.      WRITE
  5969.      -----
  5970.      The only additional error in multiuser mode is a file exclusion failure. 
  5971.      This can happen if the record being written is locked by some other
  5972.      application.  When a record is inserted into the index file, the record
  5973.      linkages of connecting records must be updated.  If any of these are locked
  5974.      by someone else, the WRITE will fail.  This is important to remember
  5975.      because it can cause what is called a "deadly embrace."  Deadly embrace
  5976.      occurs when both applications have a record locked that will cause the
  5977.      other to fail the write.  Unless one application unlocks the record, they
  5978.      will both continue to fail the write.
  5979.  
  5980.      FREE
  5981.      ----
  5982.      The FREE command is similar to the WRITE command in that a record can not
  5983.      be deleted if one of the records affected is locked.  This will cause a
  5984.      file exclusion failure, as in WRITE.  The error "key not found" (error code
  5985.      32) is returned if the record to be freed was deleted by some other
  5986.      application after the READ but before the FREE.
  5987.  
  5988.  
  5989.                                         LAN's
  5990.                                        Page 86
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.  
  5998.  
  5999.  
  6000.      BACKSPACE
  6001.      ---------
  6002.      BACKSPACE will return a file busy error (exclusion failure) or a file sync
  6003.      error, for the same reasons as in read.
  6004.  
  6005.      FSEAR, POSN, and SECURE
  6006.      -----------------------
  6007.      The commands FSEAR, POSN and SECURE also may return a file exclusion
  6008.      failure (error code 25).  During any ISAM file I/O, the header record of
  6009.      the indexed file is locked so that only one application is moving through
  6010.      or updating the index file tree structure.  If an insert takes a very long
  6011.      time because there are many duplicates or the file is grossly out of
  6012.      balance, the other applications will time out waiting for the header and
  6013.      get the file exclusion failure.  This time out is set by LRETRY.
  6014.  
  6015.      LPDETACH
  6016.      --------
  6017.      LPDETACH closes the spool file.
  6018.  
  6019.  
  6020.                                   MULTIUSER - ERRORS
  6021.                                   ------------------
  6022.  
  6023.      #E - The ERROR REGISTER
  6024.      -----------------------
  6025.      #E is a read-only register called the error register.  The contents of this
  6026.      register are the error codes as returned from file operations.  That is,
  6027.      the direct codes returned by the operating system instead of the Q-PRO 4
  6028.      high level error codes.  The possible contents of this register are listed
  6029.      in the operating system manuals.
  6030.  
  6031.  
  6032.      MULTIUSER ERROR CODES
  6033.      ---------------------
  6034.  
  6035.      FILE EXCLUSION LOCK FAILED
  6036.      Trappable as error 25.  System tried LRETRY times to lock record 0 of an
  6037.      indexed file (required for most file operations) and could not get the
  6038.      lock.
  6039.  
  6040.      FILE SYNCH. FAILURE
  6041.      Trappable as error 26.  Files are said to be out of synch when one process
  6042.      reads a record with apparently valid index links, which is then discovered
  6043.      to have been deleted by some other process.
  6044.  
  6045.      BAD HOST STATEMENT
  6046.      Trappable as error 27. A host statement was executed which either did not
  6047.  
  6048.  
  6049.                                         LAN's
  6050.                                        Page 87
  6051.  
  6052.  
  6053.  
  6054.  
  6055.  
  6056.  
  6057.  
  6058.      have a recognizable name, or at a time when all files were not closed.
  6059.  
  6060.      FILE READ-ONLY
  6061.      Trappable as error 28. Pretty obvious what this one means.
  6062.      For multiuser user, be sure you configure your operating system to allow
  6063.      three locks per file, file and record.  (You need only 2 files, if you will
  6064.      not do record-locking in your application).
  6065.  
  6066.  
  6067.  
  6068.  
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.  
  6078.  
  6079.  
  6080.  
  6081.  
  6082.  
  6083.  
  6084.  
  6085.  
  6086.  
  6087.  
  6088.  
  6089.  
  6090.  
  6091.  
  6092.  
  6093.  
  6094.  
  6095.  
  6096.  
  6097.  
  6098.  
  6099.  
  6100.  
  6101.  
  6102.  
  6103.  
  6104.  
  6105.  
  6106.  
  6107.  
  6108.  
  6109.                                         LAN's
  6110.                                        Page 88
  6111.  
  6112.  
  6113.  
  6114.  
  6115.  
  6116.  
  6117.  
  6118.                           B I N A R Y   W O R S T A T I O N
  6119.                           =================================
  6120.  
  6121.                                      Introduction
  6122.                                      ============
  6123.  
  6124.  
  6125.      Complete Development System
  6126.      ---------------------------
  6127.      Binary Workstation (BW) is a complete development management system.  BW is
  6128.      intuitive in use and extremely flexible.  There is no master menu and you
  6129.      probably will never miss it!  Indeed, after a cursory look at the
  6130.      documentation and a few minutes using BW, you will probably consign the
  6131.      documentation to gather dust wherever you toss unused documentation.
  6132.  
  6133.      Multiple Files
  6134.      --------------
  6135.      Binary WorkStation can store several of your source files in memory at the
  6136.      same time.  You can switch from module to module with a press of a key. 
  6137.      You can edit each individually and even copy parts from on to another.
  6138.  
  6139.      Syntax Checker
  6140.      --------------
  6141.      At the press of a key, your entire program will be checked for syntax
  6142.      errors saving you hours of debugging.
  6143.  
  6144.      Operating System Shell
  6145.      ----------------------
  6146.      While you are in BW you can run any other program and then return to the
  6147.      same line of code.
  6148.  
  6149.  
  6150.                                    Multiple Editors
  6151.                                    ----------------
  6152.  
  6153.      Text Editor
  6154.      ----------
  6155.      Binary Workstation is a fully featured text editor for editing Q-PRO 4
  6156.      programs or ASCII files.  You can import/export Q-PRO 4 program files or
  6157.      ASCII files also.
  6158.  
  6159.      FID Editor
  6160.      ----------
  6161.      The File Item Descriptor (FID) editor is used to create and edit the file
  6162.      descriptions.
  6163.  
  6164.      Screen Editor
  6165.      -------------
  6166.      Used to "paint" screens, you paint the background color, specify the window
  6167.  
  6168.  
  6169.                               Binary WorkStation Editor
  6170.                                        Page 89
  6171.  
  6172.  
  6173.  
  6174.  
  6175.  
  6176.  
  6177.  
  6178.      size and location, specify the active field color, specify the screen data
  6179.      entry field colors, and define the screen data entry fields.
  6180.  
  6181.      Miscellaneous Features
  6182.      ----------------------
  6183.      Other outstanding features of BW are: Alt key macros, History log file, On
  6184.      Screen Clock and Backup file option.
  6185.  
  6186.  
  6187.                                      Starting Up
  6188.                                      -----------
  6189.  
  6190.      Setting Up DOS for BW 
  6191.      ---------------------
  6192.      Binary WorkStation has an options file.  In fact, it can have an options
  6193.      file for every subdirectory you use it in.  Or it can have one options file
  6194.      that is in a directory specified by the DOS variable, <BI>BW.  We recommend
  6195.      that, at first, you use the DOS variable.
  6196.  
  6197.      Binary WorkStation has extensive help screens.  You can refer to them from
  6198.      any subdirectory where you happen to be if you use the DOS variable BWHELP.
  6199.  
  6200.      Also, so you can use it anywhere, the subdirectory with Binary WorkStation
  6201.      in it should be on the path.
  6202.  
  6203.      Setting the options
  6204.      -------------------
  6205.      From the command line, type: BW<ret> 
  6206.  
  6207.      The options screen will be displayed.  If an option file exists in the
  6208.      current directory or on the path, the previously selected options are
  6209.      displayed.
  6210.  
  6211.      Use the TAB key to move from field to field.  Pressing ENTER will save the
  6212.      options and bring up the editing screen.
  6213.  
  6214.      Current File [        ]       Enter the path and name of the file to be
  6215.                                    edited.  When you leave this screen, the
  6216.                                    named file will be displayed.
  6217.  
  6218.      Vertical Scroll Lines [16]    Number of lines to scroll when Page Up/Page
  6219.                                    Down are executed.
  6220.  
  6221.      Backup File [N]               A backup file of the file you are editing
  6222.                                    will be maintained if you enter a "Y"  
  6223.  
  6224.      Clock [Y]                     If Y is selected, the time will be displayed
  6225.                                    in the lower right corner of the screen.
  6226.  
  6227.  
  6228.  
  6229.                               Binary WorkStation Editor
  6230.                                        Page 90
  6231.  
  6232.  
  6233.  
  6234.  
  6235.  
  6236.  
  6237.  
  6238.      Q-PRO 4 File [Y]              If "Y" the editor will assume Q-PRO file
  6239.                                    format.  If "N" it will assume a standard
  6240.                                    ASCII file.  You need not set this flag, BW
  6241.                                    can figure out which one it has when the file
  6242.                                    to be edited is loaded.
  6243.  
  6244.      Directory Pattern [      ]    This pattern will govern the files to be
  6245.                                    displayed when the FILES option is selected
  6246.                                    when in the editor.
  6247.  
  6248.      FID Path [      ]             If you are going to use the FID editor
  6249.                                    feature, you enter the path for the defined
  6250.                                    FIDs.
  6251.  
  6252.      FID Names                     Up to 20 may be specified.
  6253.  
  6254.      History Log File [N]          If "Y", a log file, HISTLOG.BW will be kept
  6255.                                    of all functions, save, etc. with function
  6256.                                    and date/time.<
  6257.  
  6258.      Text Lines (min 500) [     ]  Sets the maximum number of lines of text
  6259.                                    allowed in a file.  Us it to make more room
  6260.                                    for multiple files.
  6261.  
  6262.  
  6263.      Printer: Char. Per Line [80]  Sets the number of characters per line. 
  6264.                                    Default is 80.
  6265.  
  6266.      Lines Per Page [55]           Sets the number of lines to print on hard
  6267.                                    copy.  Default is 55.
  6268.  
  6269.      DOS variables
  6270.      -------------
  6271.      If you set the DOS variable BW with the DOS SET command in AUTOEXEC.BAT
  6272.      this way:
  6273.  
  6274.           SET BW=<editor directory>
  6275.  
  6276.           only one option file will be used for all directories.
  6277.  
  6278.           If you set the DOS variable BWHELP with the DOS SET command in
  6279.           AUTOEXEC.BAT this way:
  6280.  
  6281.           SET BWHELP=\<editor directory>
  6282.       
  6283.           then the help screens will be displayed from any directory you are
  6284.           working in
  6285.  
  6286.      Uses for the Option File
  6287.  
  6288.  
  6289.                               Binary WorkStation Editor
  6290.                                        Page 91
  6291.  
  6292.  
  6293.  
  6294.  
  6295.  
  6296.  
  6297.  
  6298.      ------------------------
  6299.      If you are developing multiple applications, it is suggested that BW be in
  6300.      its own directory on the DOS path.  Then each application may have its own
  6301.      subdirectory and options set.
  6302.  
  6303.  
  6304.  
  6305.  
  6306.  
  6307.  
  6308.  
  6309.  
  6310.  
  6311.  
  6312.  
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.  
  6331.  
  6332.  
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.  
  6342.  
  6343.  
  6344.  
  6345.  
  6346.  
  6347.  
  6348.  
  6349.                               Binary WorkStation Editor
  6350.                                        Page 92
  6351.  
  6352.  
  6353.  
  6354.  
  6355.  
  6356.  
  6357.  
  6358.                                    The Text Editor
  6359.                                    ===============
  6360.  
  6361.      Running from the Command Line
  6362.      -----------------------------
  6363.      From the command line type:  BW <file name><ret>
  6364.  
  6365.      If an options file exists on the logged directory or on the path, the
  6366.      options screen will be displayed momentarily.  Then you will be moved to
  6367.      the program code editor.
  6368.  
  6369.      Overview
  6370.      --------
  6371.      The text editor has two editing modes, INSERT character and TYPEOVER
  6372.      character.  The status is displayed on the upper right and the Insert key
  6373.      toggles the mode.
  6374.  
  6375.      ESC Key
  6376.      -------
  6377.      The ESC key acts as a "cancel" key.  For example, if you have brought up a
  6378.      dialog screen, pressing ESC will bring you back.  
  6379.  
  6380.      All other functions are executed either by pressing function keys or a
  6381.      control characters.  The current function that will be activated by the
  6382.      function key is displayed at the bottom of the screen as a menu line.  A
  6383.      typical editor screen is shown below:
  6384.  
  6385.      Status Line    The top line is the status line.  From left to right the
  6386.                     fields are:
  6387.  
  6388.      library.qne    The name of the file currently being edited.
  6389.  
  6390.      Line=          The line number that the cursor is currently on.
  6391.  
  6392.      Col=           The current column of the cursor.
  6393.  
  6394.      Total Lines=   Total lines in the program.  This reserves space for your
  6395.                     program files.  Clearly, the smaller the programs, the less
  6396.                     total lines you should specify and the more programs you can
  6397.                     have in memory simultaneously. 
  6398.  
  6399.      Insert=        This is a general mode setting switch.  It will be ON in the
  6400.                     INSERT character mode or OFF in the DELETE character mode. 
  6401.                     Toggle the mode by pressing the Insert key.  Several
  6402.                     functions work differently depending on whether INSERT mode
  6403.                     is ON or OFF.
  6404.  
  6405.  
  6406.  
  6407.  
  6408.  
  6409.                               Binary WorkStation Editor
  6410.                                        Page 93
  6411.  
  6412.  
  6413.  
  6414.  
  6415.  
  6416.  
  6417.  
  6418.      Function       Insert ON                      Insert OFF
  6419.      --------       ----------                    -----------
  6420.  
  6421.      TAB            Moves the text at the cursor
  6422.                     position 4 spaces to the right.
  6423.  
  6424.      Return         Inserts a carriage return     Moves the cursor to the 
  6425.           line feed at the cursor       beginning of the next line. 
  6426.                     position.
  6427.  
  6428.      Any key        Inserts the character at      Overwrites the character
  6429.                     the cursor position           at the current character
  6430.                                                   position.
  6431.  
  6432.      10:16am   The system time
  6433.  
  6434.      Menu Line
  6435.      ---------
  6436.      Bottom Line - The bottom line is the menu line.  Because the menu line can
  6437.      display only eight functions, the menu line itself is changed by pressing
  6438.      F10 to scroll the menu forward, F9 to scroll the menu backward.
  6439.  
  6440.      From the main BW screen, dialogue screens and specification screens are
  6441.      summoned for various functions such as text search and FID display and
  6442.      generation.
  6443.  
  6444.      There are four main menu lines:
  6445.  
  6446.      Line   F1      F2     F3       F4     F5       F6     F7      F8
  6447.       
  6448.      0    Top     Bottom  Pg Up   Pg Dn   Insert  Delete  Fields  Screen
  6449.      1    Load    Update  Unload  Save/x  Swap    Exit    FIDs    Exec
  6450.      2    Search  Sr/Rep  Again   ASCII   Print   Eject   Syntax  Regs
  6451.      3    FIDgen  Files   Merge   Optns   Insert  Delete  Word    Help!
  6452.      4    SetMrk  MovBlk  CopyBlk DelBlk  Line#s  Un-Del  Goto    Help!
  6453.  
  6454.      This is what will happen with each selection:
  6455.  
  6456.      The accelerator key is shown in <> 
  6457.  
  6458.      Top       Move the cursor to the beginning of the file.  <HOME key>
  6459.  
  6460.      Bottom    Move the cursor to the bottom of the file.  <END key>
  6461.  
  6462.      Pg Up     Move the page up by the number of lines specified in Vertical
  6463.                Scroll in the Editor Options screen.  <PgUp key>
  6464.  
  6465.      Pg Dn     Move the page down by the number of lines specified in Vertical
  6466.                Scroll in the Editor Options screen.  <PgDn key>
  6467.  
  6468.  
  6469.                               Binary WorkStation Editor
  6470.                                        Page 94
  6471.  
  6472.  
  6473.  
  6474.  
  6475.  
  6476.  
  6477.  
  6478.  
  6479.      Insert    Insert a line at the current cursor position.  <Control C>  
  6480.  
  6481.      Delete    Delete a line at the current cursor position.  <Control D>
  6482.  
  6483.      Fields    Displays the screen data field specifications.  <Control F>
  6484.  
  6485.      Screen    Brings up the window definition screen ready for editing.  See
  6486.                the Screen Editor chapter for more detail.  <Shift-F8>
  6487.  
  6488.      Load      Load a file into the editor.  You may Load up to eight files into
  6489.                memory as long as you have the memory.  BW has an overhead of
  6490.                approximately 20K per file loaded.  The dialogue screen below
  6491.                will be displayed. <Control L>
  6492.        
  6493.                The files currently loaded in RAM will be displayed.
  6494.  
  6495.                Load File:file1.qne
  6496.                The most recently loaded file's name will be displayed.  To load
  6497.                another file, type the name and press enter. 
  6498.       
  6499.      Update    Updates the currently loaded file to disk.  The dialogue screen
  6500.                show below is displayed:  <Control U>
  6501.  
  6502.      Save this file [Y]
  6503.                     BW assumes that you want to save a file so it defaults to Y.
  6504.  
  6505.                     Save in Q-PRO 4 format? [Y]
  6506.  
  6507.                Enter Y if you want to save this file in Q-PRO 4 format, i.e.,
  6508.                with screens.  If you want to save it in ASCII format, press N.
  6509.  
  6510.                File name [              ] 
  6511.                Type the name of the file that you want to save.
  6512.  
  6513.      Unload    A dialog screen displays a list of all files Loaded.
  6514.  
  6515.                Entering a Y in the box will keep the file loaded.  Entering an N
  6516.                will unload the file.  You may keep or discard as many files as
  6517.                you want.
  6518.  
  6519.                Unloading a file does not save it.  If you have edited a file and
  6520.                want to keep the results, update it before unloading it. 
  6521.  
  6522.                     The cursor will be in the Unload? column.  Enter a Y in the
  6523.                     appropriate box to remove the file from memory. 
  6524.  
  6525.      Save/X    Saves all the files that are currently loaded in memory and exits
  6526.                BW.  The same dialogue screen as in SAVE will be displayed for
  6527.  
  6528.  
  6529.                               Binary WorkStation Editor
  6530.                                        Page 95
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.                each file. <Shift-F4>
  6539.  
  6540.      Swap      Swap unloads the current program file from the screen and loads
  6541.                the next one in sequence.  BW keeps track of where you are in
  6542.                each file and returns you to that line when the program is
  6543.                swapped in.  <Control O>
  6544.  
  6545.      Exit      Leave BW.  <Control X>
  6546.  
  6547.      FIDs      Displays a dialogue screen to select the fid to be displayed. 
  6548.                Only FIDs that have been defined in Editor Options will be
  6549.                displayed.  For more information, see the FID Generator section. 
  6550.                <Control P>
  6551.  
  6552.      Execute   Brings up a dialogue screen to select a program to run.  It
  6553.                defaults to the program currently loaded.
  6554.  
  6555.                     You may execute any executable program, e.g. DIR,FORMAT,
  6556.                     etc.  If you are executing QNE, BW will automatically put a
  6557.                     $ in front of the file name to turn off the QNE banner. 
  6558.                     After execution it will ask you to hit any key to return to
  6559.                     BW and display the text file that was in memory.  The
  6560.                     dialogue box shown below will be displayed:  <Control Q>
  6561.  
  6562.                     The most recently executed command line will be displayed. 
  6563.                     Enter a new one to run a different program.  You may edit
  6564.                     the line with insert/delete keys.  The dollar sign ($) tells
  6565.                     the Q-PRO 4 interpreter to suppress its banner.
  6566.  
  6567.                Notes on Execute:
  6568.                -----------------
  6569.                This option will execute the program on disk.  Therefore, if you
  6570.                are executing the program just edited and in memory, you must
  6571.                update the program currently loaded to insure that what you have
  6572.                edited is executed.  You will get a warning.
  6573.       
  6574.                For proper return from the executed Q-PRO 4 program, do not use
  6575.                FORMLOAD.
  6576.  
  6577.      Search    Displays a dialogue screen for setting the search criteria.
  6578.                <Control S>
  6579.  
  6580.                The fields are used as follows
  6581.  
  6582.                Search for [        ]    The exact string to be searched for.  BW
  6583.                                         will search for this string throughout
  6584.                                         the entire file.
  6585.  
  6586.                Ignore case [Y]          This instructs BW whether the search is
  6587.  
  6588.  
  6589.                               Binary WorkStation Editor
  6590.                                        Page 96
  6591.  
  6592.  
  6593.  
  6594.  
  6595.  
  6596.  
  6597.  
  6598.                                         case sensitive or not.  The default is
  6599.                                         Y.
  6600.  
  6601.                Quote Character [~]      Use this character for when you are
  6602.                                         looking for a quote "".  Although the
  6603.                                         default is tilde, you may use any
  6604.                                         character.
  6605.        
  6606.      Sr/Rep    Displays a dialogue screen  for setting the search and replace
  6607.                criteria.  <Control T>
  6608.  
  6609.                Search for [        ]    The exact string to be searched for.  BW
  6610.                                         will search for this string throughout
  6611.                                         the entire file.
  6612.  
  6613.                Replace with [      ]    Replace the any string that matches the
  6614.                                         search criteria with the string in shown
  6615.                                         here.
  6616.  
  6617.                Ask before replace? [Y]  Stop and ask before replacing the string
  6618.                                         with the new value.
  6619.       
  6620.                Ignore case [Y]          This instructs BW whether the search is
  6621.                                         case sensitive or not.  The default is
  6622.                                         Y.
  6623.  
  6624.                Quote Character [~]      Use this character for when you are
  6625.                                         looking for a quote "".  Although the
  6626.                                         default is tilde, you may use any
  6627.                                         character.
  6628.  
  6629.      Again     Perform the search again.  <Control A>
  6630.  
  6631.      ASCII     Display a chart of the ASCII values of decimal characters.
  6632.  
  6633.      Print     Print the program file.  <Shift-F5>
  6634.  
  6635.      Eject     Send a form feed to the list device.
  6636.  
  6637.      Syntax    Invokes the fearsome syntax checker.  It goes through your code
  6638.                from the current cursor position to the end looking for syntax
  6639.                errors.  Upon finding one, it will stop on that line, give an
  6640.                error message, and highlight that line.  <Control W>
  6641.  
  6642.      Regs      Displays all registers that are used.  <Control R>
  6643.  
  6644.      FIDGen    Invokes the FID generator.  See the FID Generator section for
  6645.                more details. <Control V>
  6646.  
  6647.  
  6648.  
  6649.                               Binary WorkStation Editor
  6650.                                        Page 97
  6651.  
  6652.  
  6653.  
  6654.  
  6655.  
  6656.  
  6657.  
  6658.      Files     Displays a directory of files that meet the directory pattern set
  6659.                in the Editor Option Screen.  
  6660.  
  6661.      Merge     Merge an external file with the characteristics in a dialogue
  6662.                screen at the current cursor location. <Shift-F9>
  6663.  
  6664.                Fill in these fields as discussed below:
  6665.  
  6666.                Merge File:    The name, including drive and directory, of the
  6667.                               file.
  6668.  
  6669.                Include Program Text? [ ]     Enter Y or N.  If Y, the text of
  6670.                                              the ASCII file or the program text
  6671.                                              from a Q-PRO 4 file will be
  6672.                                              inserted.
  6673.  
  6674.                Include Screen? [ ] Enter Y or N.  If Y, the screen of the Q-PRO
  6675.                                    4 file will be inserted.
  6676.         
  6677.      Optns     Display the Editor Options Screen
  6678.  
  6679.      Word      Move the cursor from one word to another.  
  6680.  
  6681.      Help!     Display help screen.
  6682.  
  6683.      Set Mrk   Define blocks for block operations.  Set the beginning of the
  6684.                block by placing the cursor at the location to be marked and
  6685.                press the Set Mark key.  Mark the end similarly.  <Alt-F1>
  6686.  
  6687.                Blocks are assumed to be complete lines.  No partial lines are
  6688.                allowed.
  6689.  
  6690.                To mark a single line, place the cursor at the beginning of the
  6691.                line and press the key twice.
  6692.  
  6693.      Move Blk  Move the marked block to the current cursor location.  Move Block
  6694.                will not move a block from one loaded program to another after a
  6695.                SWAP.  <Alt-F2>
  6696.  
  6697.      Cpy Blk   Replicate the marked block at the current cursor location.
  6698.  
  6699.                You can copy a block as many times as you wish.  You may also
  6700.                copy the block from one file to another after a SWAP.  <Alt-F3>
  6701.  
  6702.      Del Blk   Delete the marked block.  You may delete blocks from one file to
  6703.                another.  <Alt-F4>
  6704.  
  6705.      Line #s   This function toggles the display of paragraph numbers on the
  6706.                left border of the screen. <Shift-F7>
  6707.  
  6708.  
  6709.                               Binary WorkStation Editor
  6710.                                        Page 98
  6711.  
  6712.  
  6713.  
  6714.  
  6715.  
  6716.  
  6717.  
  6718.  
  6719.      Un-Del    This function puts the most recently deleted line at the current
  6720.                cursor position.  When using the delete line function, up to 100
  6721.                lines are stored that may be undeleted.  <Shift-F6>
  6722.  
  6723.      Goto      Jumps the cursor to a line number in a Q-PRO 4 program file or an
  6724.                ACSII file.  <Control G>
  6725.  
  6726.      Help!     Display help screen.  
  6727.  
  6728.  
  6729.                                  Other Key Functions
  6730.                                  -------------------
  6731.  
  6732.      Standard keys
  6733.      -------------
  6734.      These keys perform the usual functions: 
  6735.      INS       DEL       UP        DOWN      LEFT      RIGHT 
  6736.      PgUp      PgDn      HOME      END       BACKSPACE ENTER 
  6737.      TAB       BACKTAB
  6738.  
  6739.  
  6740.      Accelerator Keys
  6741.      ----------------
  6742.      The accelerator keys execute the functions directly.  The accelerators are
  6743.      executed by pressing the Ctrl key and the letter at the same time.  They
  6744.      are:
  6745.       
  6746.      Control Key      Function 
  6747.      A         Search Again
  6748.      B         Go to the beginning of the Line
  6749.      E         Go to the end of the Line
  6750.      F         Fields 
  6751.      G         Goto a line number
  6752.      L         Load another file in RAM
  6753.      N         Unload a file in RAM
  6754.      O         Swap the displayed file for another
  6755.      P         Display FID
  6756.      Q         Execute
  6757.      R         Display registers in use
  6758.      S         Search
  6759.      T         Search/Replace
  6760.      U         Update the file in RAM onto disk
  6761.      V         Invoke the FID Generator
  6762.  
  6763.      W         Invoke syntax checker
  6764.      X         Exit from BW
  6765.  
  6766.      Shifted Key                Function
  6767.  
  6768.  
  6769.                               Binary WorkStation Editor
  6770.                                        Page 99
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.  
  6777.  
  6778.  
  6779.      F3        Flip bottom line of display
  6780.      F4        Update/Exit
  6781.      F5        Print
  6782.      F6        Undelete
  6783.      F7        Display Line Numbers
  6784.      F8        Go to screen editor
  6785.      F9        Merge another file
  6786.  
  6787.      ALT Key                 Function
  6788.  
  6789.      F1        Set Mark
  6790.      F2        Move marked block
  6791.      F3        Copy marked block
  6792.      F4        Delete marked block
  6793.  
  6794.      Other Keys
  6795.      ----------
  6796.      Other standard keys have expanded functions.  They are:
  6797.  
  6798.      Home           Move to the beginning of file.
  6799.      End            Move to the end of file.
  6800.      Backspace      This is a destructive backspace.  If you delete an entire
  6801.                     line, the next line will be moved up.
  6802.      Del            Deletes the character at the current character location.  If
  6803.                     the cursor is at the end of a line, text from the next line
  6804.                     will be appended to the current line. 
  6805.  
  6806.  
  6807.  
  6808.  
  6809.                                     Screen Editor
  6810.                                     =============
  6811.  
  6812.      Screen Definition
  6813.      -----------------
  6814.      The definitions of the screens are kept in the program file. The screen 
  6815.      mode has its own menu line that works slightly differently than the program
  6816.      edit menu line.  It scrolls forward only by pressing F10.  The next menu
  6817.      line to be displayed is always displayed.
  6818.  
  6819.      The Insert and Delete keys remain functional as insert character and delete
  6820.      character.
  6821.  
  6822.      Building a Screen
  6823.      -----------------
  6824.      All Q-PRO 4 screens are built in the "What-you-see-is-what-you-get"
  6825.      (WYSIWYG) mode.
  6826.  
  6827.  
  6828.  
  6829.                               Binary WorkStation Editor
  6830.                                        Page 100
  6831.  
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.  
  6838.      Screen Constants
  6839.      ----------------
  6840.      For constants (or labels or fixed fields or background, whatever you use
  6841.      for terminology) on the screen, just move the cursor where you want the
  6842.      constants and type them. 
  6843.  
  6844.      Screen Data Entry Fields
  6845.      ------------------------
  6846.      For data entry fields, invoke the EDIT FLD option on the menu as discussed
  6847.      below.
  6848.  
  6849.      The menu lines are:
  6850.  
  6851.  
  6852.  
  6853.  
  6854.  
  6855.  
  6856.  
  6857.  
  6858.  
  6859.  
  6860.  
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.  
  6869.  
  6870.  
  6871.  
  6872.  
  6873.  
  6874.  
  6875.  
  6876.  
  6877.  
  6878.  
  6879.  
  6880.  
  6881.  
  6882.  
  6883.  
  6884.  
  6885.  
  6886.  
  6887.  
  6888.  
  6889.                               Binary WorkStation Editor
  6890.                                        Page 101
  6891.  
  6892.  
  6893.  
  6894.  
  6895.  
  6896.  
  6897.  
  6898.  
  6899.        F1        F2        F3      F4       F5       F6     F7      F8
  6900.      Edit Fld  Next Fld  HLT On  HLT Off  Insert  Delete   Field    Edit
  6901.      Screen    FIDS      Reps    Import   Insert  Delete!  Help     Edit
  6902.      Graphics
  6903.       
  6904.      Edit Fld       Displays the field definition window:
  6905.  
  6906.                     See the Programmer's Reference section for a detailed
  6907.                     discussion of field characteristics.  Only the field that
  6908.                     the cursor is currently on is editable.  Enter re-displays
  6909.                     the screen.
  6910.  
  6911.           Field Name     The name of the screen data field.
  6912.  
  6913.           Len            The length of the screen data field, 1 to 255
  6914.                          characters.
  6915.  
  6916.           Row            The row where the screen data field is located.  This
  6917.                          row is put in automatically by Binary WorkStation but
  6918.                          you may change it to move the screen data field.
  6919.  
  6920.           Col            The column where the screen data field is located. 
  6921.                          This row is put in automatically by Binary WorkStation
  6922.                          but you may change it to move the screen data field.
  6923.  
  6924.           Type           This is a two character field.  The first character is
  6925.                          the attribute and the second is blank=no edit,
  6926.                          ?=invisible field, or = for autoduplicate.
  6927.  
  6928.           Just           This is the field justification.  You can use L for
  6929.                          left justified, R for right justified, C for center or
  6930.                          N for none.
  6931.  
  6932.           Fill Char      This specifies the character to be used to left fill
  6933.                          the screen data field.  It is typically a zero (0) for
  6934.                          left zero fill.
  6935.  
  6936.           May Ent        A "Y" here allows the user to enter data in the field. 
  6937.                          You could have a field for program remarks only.  Here
  6938.                          the field would be N which would not let the user enter
  6939.                          data.
  6940.  
  6941.           Must Ent       If "Y", the user must enter at least one character in
  6942.                          the field.
  6943.  
  6944.           Must Fill      If "Y", the user must not only enter data in the field,
  6945.                          but must full it completely.
  6946.  
  6947.  
  6948.  
  6949.                               Binary WorkStation Editor
  6950.                                        Page 102
  6951.  
  6952.  
  6953.  
  6954.  
  6955.  
  6956.  
  6957.  
  6958.           Must Tab       If Y, the user must press the TAB key to exit the
  6959.                          field.  If it is N, the user may press TAB to exit the
  6960.                          field or be moved to the next field automatically when
  6961.                          the field is filed.
  6962.  
  6963.           Proc Name      The name of the procedure to execute when the user
  6964.                          exits the field.
  6965.  
  6966.      Hlt On         Turns on the highlighting at the point where the cursor is
  6967.                     located.  On the IBM PC, the default highlighting is reduced
  6968.                     intensity.  Highlighting requires a character position on
  6969.                     the screen.  With the full distribution version of Q-PRO 4,
  6970.                     you can modify the highlighting to your own satisfaction.
  6971.  
  6972.      Hlt Off        Returns the highlighting to standard.   
  6973.  
  6974.      Edit           Leave the screen editor.
  6975.  
  6976.      FIDs           On this screen will be displayed any FID file that you
  6977.                     designated on the option screen.  You may select one of the
  6978.                     pre-designated FIDs by entering its number.
  6979.  
  6980.      Reps           Display a dialogue screen.  Enter a number of reps while
  6981.                     positioned on a previously defined field will reproduce the
  6982.                     defined field the number of reps time, vertically.  BW will
  6983.                     generate names for the fields.
  6984.  
  6985.      Import         This will format the current file into a Q-PRO 4 Help Screen
  6986.                     or Q-PRO 4 Background Screen format.  It takes the first 24
  6987.                     lines in the program file and moves them to the screen.
  6988.  
  6989.      HELP!          Displays a help window.
  6990.  
  6991.      Graphics Mode  Turn Graphics mode on.  Graphics are drawn on the screen
  6992.                     with the cursor keys and the function keys.
  6993.  
  6994.      Next Fld       Moves cursor to next defined screen data field.
  6995.  
  6996.      HLT On         Turns highlights on at the current cursor location.
  6997.                     Highlight for PC-DOS is REDUCED INTENSITY.  You MUST leave a
  6998.                     position for the highlight.  
  6999.  
  7000.      HLT Off        Turns highlights off at the current cursor position.
  7001.  
  7002.      Insert         Insert a line at the current cursor position.
  7003.  
  7004.      Delete         Delete a line at the current cursor position.
  7005.  
  7006.      Fields         Display the specification for all defined screen data
  7007.  
  7008.  
  7009.                               Binary WorkStation Editor
  7010.                                        Page 103
  7011.  
  7012.  
  7013.  
  7014.  
  7015.  
  7016.  
  7017.  
  7018.                     fields.
  7019.  
  7020.                                     Fid Generator
  7021.                                     =============
  7022.  
  7023.  
  7024.                                     The FID System
  7025.                                     --------------
  7026.  
  7027.      The Binary Workstation File Item Descriptor Generator (FID) is used to
  7028.      build and maintain descriptions of file records (called FID files).  It
  7029.      provides a program-independent means of maintaining data file formats. 
  7030.      With FID, changes to file formats may be made without regard to any
  7031.      programs which reference these files, since all references to file fields
  7032.      is done on a symbolic (field name) basis.
  7033.  
  7034.      Other features of the FID system are:
  7035.  
  7036.             o  unlimited number of fields in a record.
  7037.             o  optional overlapping of file data field (called realignment). 
  7038.                This allows varying record formats within a data file.
  7039.             o  replicated fields within a record.  This allows fields to be
  7040.                referenced within Q-PRO 4 as if they were arrays.
  7041.             o  automatic documentation of record formats.
  7042.  
  7043.  
  7044.                                       FID Files
  7045.                                       ---------
  7046.  
  7047.      Restrictions
  7048.      ------------
  7049.      The information about record layouts is contained in a file separate from
  7050.      the data file, called a "FID" file.  A FID file may have any name, and
  7051.      reside on any drive or directory.
  7052.  
  7053.      Commands to associate data files with FID files at open or creation time
  7054.      are described in the Programmer's Reference Manual.
  7055.  
  7056.      FID Dialog Screen
  7057.      -----------------
  7058.      First the FID dialogue screen is displayed.  If any .FIDs are on the FID
  7059.      path, as defined in the options screen, they will be shown on this screen.
  7060.  
  7061.      If the FID file you want to edit is shown on the list on the top of the
  7062.      screen, enter its number and press enter.  Otherwise, type the FID file
  7063.      name and press enter.  This screen will display: 
  7064.  
  7065.      Main FID Screen
  7066.  
  7067.  
  7068.  
  7069.                               Binary WorkStation Editor
  7070.                                        Page 104
  7071.  
  7072.  
  7073.  
  7074.  
  7075.  
  7076.  
  7077.  
  7078.      Editing
  7079.      You can move the cursor freely within the screen displayed to change
  7080.      currently displayed data or enter new data.  
  7081.  
  7082.      Item Name      In this column you specify the name of the FID field.  This
  7083.                     name must follow the standard naming conventions.
  7084.  
  7085.      Len.           This is the length of the FID field.  It can be 1 to 255
  7086.                     characters in length.
  7087.  
  7088.      Type           The FID field type is either alphanumeric (X) or numeric
  7089.                     (N).
  7090.       
  7091.      Description    You may enter here any description that helps document the
  7092.                     field.
  7093.  
  7094.      Reps           The number of times this field is repeated in the file. 
  7095.                     Using this feature allows you to have file arrays.  You may
  7096.                     dimension the array from 1 to 64K.
  7097.  
  7098.                     An element in the array is called out in your program in
  7099.                     this format:
  7100.  
  7101.                          $FID_name[file #, element]
  7102.  
  7103.                               file #    The file number that uses this FID.
  7104.                               element   An integer literal or an expression that
  7105.                                         evaluates to an integer.  Note:  The
  7106.                                         element numbers start at 0.
  7107.       
  7108.                          Examples:
  7109.  
  7110.                               $FED_TAX[1,0]       The first element in file 1,
  7111.                                                   field FED_TAX.
  7112.  
  7113.  
  7114.                               $FED_TAX[1, (#n0-1)]     The #n0-1th element in
  7115.                                                        file 1, field FED_TAX
  7116.        
  7117.  
  7118.      F1 - Page Up        Scroll the FID down a page (if it is long enough).
  7119.  
  7120.      F2 - Page Down      Scroll the FID up a page.
  7121.  
  7122.      F3 - Load FID file  Moves the cursor to the top line awaiting a FID file
  7123.                          name.  After you type the name and press enter, the FID
  7124.                          file (assuming it exists) will be loaded.
  7125.  
  7126.      F4 - Update FID file     This selection allows a file description to be
  7127.  
  7128.  
  7129.                               Binary WorkStation Editor
  7130.                                        Page 105
  7131.  
  7132.  
  7133.  
  7134.  
  7135.  
  7136.  
  7137.  
  7138.                               stored as a FID file on disk.  If the FID file
  7139.                               previously existed (if there is already a file by
  7140.                               the same name on the disk), then that file will be
  7141.                               renamed to name.BFD.  This is so that any
  7142.                               previously existing data file might be regenerated
  7143.                               using the old .BFD FID file as the original
  7144.                               description, and the new FID file as the desired
  7145.                               description.
  7146.  
  7147.                               If a .BFD file is already found to exist, then FID
  7148.                               assumes that this is an old version yet to be used
  7149.                               for regeneration and no new .BFD file is
  7150.                               generated.  Any file with the same name as the
  7151.                               current FID file is deleted.
  7152.       
  7153.      F5 - Insert Field   Pressing this key opens up a line for inserting a new
  7154.                          FID field definition.
  7155.  
  7156.      F6 - Delete Field   Pressing this key deletes the FID field definition at
  7157.                          the current cursor location.
  7158.  
  7159.      F7 - Define Keys    This selection will brings up a window, shown below, at
  7160.                          the bottom of the screen to define the file key.
  7161.  
  7162.                          This screen defines what fields make up each key. 
  7163.                          Fields need not be adjacent.  Keys  must be specified
  7164.                          in sequence, i.e., 1, 2, 3, etc.  If NO keys are
  7165.                          specified, the file will be RANDOM. 
  7166.  
  7167.                          When the screen is first displayed, key number 1 will
  7168.                          be displayed.  Put in the keys by FID file name using
  7169.                          the TAB to go from field to field. 
  7170.  
  7171.                          In each space enter the name of the FID file field that
  7172.                          comprises the key.  Note: A file with no keys is a
  7173.                          random file.  See the programmer's reference manual for
  7174.                          more information on random files.
  7175.  
  7176.  
  7177.                                              Notes on keys
  7178.                                              -------------
  7179.                          Definitions
  7180.                          -----------
  7181.  
  7182.                          A key is an ASCII string consisting of one or more
  7183.                          fields that need not be adjacent.  A file may have up
  7184.                          to 9 keys.  Key 1 is, by convention, the <BI>primary
  7185.                          key.  All other keys are referred to as <BI>secondary
  7186.                          keys.
  7187.  
  7188.  
  7189.                               Binary WorkStation Editor
  7190.                                        Page 106
  7191.  
  7192.  
  7193.  
  7194.  
  7195.  
  7196.  
  7197.  
  7198.  
  7199.                          Primary Keys are UNIQUE.  There are NO duplicates.  In
  7200.                          other words, there is one and only one record with this
  7201.                          key.
  7202.  
  7203.                          Secondary Keys may be duplicated.  You may have many
  7204.                          records with the same secondary key.     
  7205.  
  7206.                          Use -- A file can be positioned to a specific record if
  7207.                          the value of the record's primary key is known.  It can
  7208.                          be positioned to the first record of a set that has the
  7209.                          same secondary key.
  7210.       
  7211.                          Character Alignment -- Because the keys are ASCII
  7212.                          strings, you must be careful of the alignment of the
  7213.                          fields and, particularly with numeric keys, leading
  7214.                          characters.
  7215.  
  7216.                          Generally, alphanumeric fields used as keys will be
  7217.                          left justified.
  7218.  
  7219.                          If you want the records to be in sequence with numeric
  7220.                          keys, they must be right justified.  Remember, left
  7221.                          zero (0) fill is not the same as left blank fill.   
  7222.  
  7223.  
  7224.      F8 - Align Fields with other Fields
  7225.           Brings up this screen:
  7226.  
  7227.                 Field name     Offset   Aligned with
  7228.                [         ]     [    ]   [         ]
  7229.                [         ]     [    ]   [         ]
  7230.           .
  7231.           .
  7232.           .
  7233.                [         ]     [    ]   [         ]
  7234.  
  7235.           Aligned with   This field contains the name of a previous field within
  7236.                          this record with the same starting character position
  7237.                          as the current field.  If left blank, then the current
  7238.                          field takes the next available character position.  If
  7239.                          not blank, then it must contain the name of such a
  7240.                          field.  All later field definitions will be located
  7241.                          after this field.
  7242.  
  7243.                          Using this facility, data files may effectively have
  7244.                          more than one record format, either by redefining the
  7245.                          entire record, or by leaving the first section of the
  7246.                          record common to all formats.  For example, if we
  7247.  
  7248.  
  7249.                               Binary WorkStation Editor
  7250.                                        Page 107
  7251.  
  7252.  
  7253.  
  7254.  
  7255.  
  7256.  
  7257.  
  7258.                          wished to store invoices and invoice payments within
  7259.                          the same file, we could have the following (simplified)
  7260.                          sequence of fields:
  7261.  
  7262.           NAME      LEN  LOCATION       DESCRIPTION
  7263.           ----      ---  --------       ------------
  7264.           INVNUM    6         1         Invoice #
  7265.           TYPE      2         7         Blank if invoice, else payment number
  7266.           SHIPPER   20        9         Shipper name
  7267.           PRODNO    4         29        Product number
  7268.           QUAN      4         33        # of items shipped
  7269.           PRICE     7         37        Price each
  7270.  
  7271.      (This much defines an invoice.  Now for the fields which redefine the same
  7272.      record space for a payment entry).
  7273.  
  7274.           CHECK     6         9         Check # (aligned with SHIPPER).
  7275.           MONTH     2         15        Month of check date.
  7276.           DAY       2         17        Day of check date.
  7277.           YEAR      2         19        Year of check date.
  7278.           AMT       7         21        Month of check.
  7279.  
  7280.      In referencing this as file 1, if &TYPE[1] was non-zero, then the record
  7281.      represents a payment; that is, &CHECK[1], &MONTH[1], &DAY[1], and &AMT[1]
  7282.      represent valid data.  If &TYPE[1] is zero, then we should only deal with
  7283.      &SHIPPER[1], &PRODNO[1], &QUAN[1], and &PRICE[1], since this is an invoice
  7284.      record.
  7285.  
  7286.      Refer to sample programs and FIDS for examples of the use of aligned
  7287.      fields.
  7288.  
  7289.      F9 - Merge FID file This selection allows merging into the currently
  7290.                          displayed FID file another FID file.  You can use it to
  7291.                          make a FID for multiple screens by using the Quick FID
  7292.                          option an then the merge.  Pressing F9 will move the
  7293.                          cursor to the top of the FID screen with this message:
  7294.  
  7295.                          MERGE FILE ___________________
  7296.  
  7297.                          Enter the name of the FID file to be merged and press
  7298.                          ENTER. 
  7299.  
  7300.      Sh-F10 - Quit       Exit the FID generator.
  7301.  
  7302.      Sh-F1 - Print       Print the FID definition.
  7303.  
  7304.      Sh-F2 - Quick FID   This selection creates a FID file from an application
  7305.                          file.  All the screen data fields and their definitions
  7306.                          will be in the created FID file.  The default key will
  7307.  
  7308.  
  7309.                               Binary WorkStation Editor
  7310.                                        Page 108
  7311.  
  7312.  
  7313.  
  7314.  
  7315.  
  7316.  
  7317.  
  7318.                          be the first screen data field on the screen.  
  7319.  
  7320.                          Once the name is entered and the FID file updated from
  7321.                          the main menu, any previously generated FID with the
  7322.                          same file name will be over written with the new FID. 
  7323.                          You may modify the created FID in the same manner as
  7324.                          any other.
  7325.  
  7326.      X - Return to Main Menu
  7327.                          Returns to the main menu screen.
  7328.  
  7329.  
  7330.                              Referencing File Data Fields
  7331.                              ----------------------------
  7332.  
  7333.                                  Referencing By Name
  7334.                                  -------------------
  7335.      Fields in records described by FID files may be referenced by name like any
  7336.      other data item (variables, screen fields, registers, etc.). The syntax of
  7337.      a FID field reference is as follows:
  7338.  
  7339.           &name [file# {,array element}]
  7340.  
  7341.                &name          file field name
  7342.                file #         the file number referenced.
  7343.                array element  the number of the file field repetition, beginning
  7344.                               with 0 (zero).
  7345.  
  7346.           Remarks
  7347.           -------
  7348.           Since FID fields may have the same name in different files, or as
  7349.           screen fields or variables, the "&" denotes that a FID field is being
  7350.           referenced.  The file number may be any arithmetic expression
  7351.           resulting in the desired number. 
  7352.  
  7353.                Examples:
  7354.  
  7355.                &LASTNAME[1]        The field LASTNAME from file 1
  7356.                &LASTNAME[#N2]      The field LASTNAME from the file whose file
  7357.                                    number is in #N2.  
  7358.       
  7359.           The index is used only for FID field arrays, that is, FID fields that
  7360.           are defined with more than one repetition.  The index denotes which
  7361.           item in the FID field array is desired.  The first FID field in the
  7362.           array has an element number of zero.  Indices may range from 0 to the
  7363.           number of elements minus 1.  If no index is given for a replicated
  7364.           item, 1 is assumed.
  7365.  
  7366.                Examples:
  7367.  
  7368.  
  7369.                               Binary WorkStation Editor
  7370.                                        Page 109
  7371.  
  7372.  
  7373.  
  7374.  
  7375.  
  7376.  
  7377.  
  7378.  
  7379.                &NUMBER(1,3)        The fourth element in the file array NUMBER. 
  7380.  
  7381.                &NUMBER(#N1, #N2)   The element number contained in #N2 in file
  7382.                                    number #N1.
  7383.  
  7384.  
  7385.  
  7386.  
  7387.  
  7388.  
  7389.  
  7390.  
  7391.  
  7392.  
  7393.  
  7394.  
  7395.  
  7396.  
  7397.  
  7398.  
  7399.  
  7400.  
  7401.  
  7402.  
  7403.  
  7404.  
  7405.  
  7406.  
  7407.  
  7408.  
  7409.  
  7410.  
  7411.  
  7412.  
  7413.  
  7414.  
  7415.  
  7416.  
  7417.  
  7418.  
  7419.  
  7420.  
  7421.  
  7422.  
  7423.  
  7424.  
  7425.  
  7426.  
  7427.  
  7428.  
  7429.                               Binary WorkStation Editor
  7430.                                        Page 110
  7431.  
  7432.  
  7433.  
  7434.  
  7435.  
  7436.  
  7437.  
  7438.                                   Q - PRO 4 Commands
  7439.  
  7440.  
  7441.                             Q - P R O 4   C O M M A N D S
  7442.                             =============================
  7443.  
  7444.                                       Symbology
  7445.                                       =========
  7446.  
  7447.      Several symbols have been chosen as delimiters of portions of the commands. 
  7448.      They are:
  7449.  
  7450.      Curly Braces ({})        Enclose an optional phrase as explained in the
  7451.                               text.  The vertical lines are never part of the
  7452.                               command.
  7453.      Angle Brackets (<>)      Enclose phrases that are generic symbols.  The
  7454.                               angle brackets are never part of the command.
  7455.      Square Brackets ([ ])    Used in various contexts as actual parts of a
  7456.                               command. 
  7457.      Parentheses (( ))        Used interchangeably with square brackets and in
  7458.                               expressions in various contexts as parts of a
  7459.                               command.
  7460.  
  7461.      Structure of the Commands
  7462.      -------------------------
  7463.      A command is made up of the following elements:
  7464.  
  7465.      Label (Optional)    A numeric line number or an alphanumeric label.  An
  7466.                          alphabetic label is denoted by a leading colon (:).
  7467.      Statement           The executable statement, broken into:
  7468.  
  7469.                          VERB - The main command
  7470.                          OPERANDS - Data items
  7471.                          MODIFIERS - Additional operations for the 
  7472.                          verb
  7473.  
  7474.      Error               Line number or label to branch to on error.
  7475.  
  7476.           Example: 
  7477.           :FIND_IT   TSEAR TABLE AT #N1, #S1: NO_GOT
  7478.  
  7479.         Where:
  7480.  
  7481.                :FIND_IT  is the label
  7482.                TSEAR     is the verb
  7483.                #N1, #S1  are data items
  7484.                TABLE     is a modifier
  7485.                AT        is a modifier
  7486.                          separator for error branch
  7487.  
  7488.  
  7489.                                        Commands
  7490.                                        Page 111
  7491.  
  7492.  
  7493.  
  7494.  
  7495.  
  7496.  
  7497.  
  7498.                                   Q - PRO 4 Commands
  7499.  
  7500.  
  7501.           NO_GOT    label to branch to
  7502.      Naming Conventions
  7503.      ------------------
  7504.      Names within Q-PRO 4 follow the conventions listed below.  These
  7505.      conventions apply to screen field names, file field names, variables, and
  7506.      labels.
  7507.  
  7508.           1.   The first character of any name must be an alphabetic character.
  7509.           2.   The name may be up to 10 alphanumeric characters long.
  7510.           3.   Underline characters (_) may be embedded in the name for clarity
  7511.                and they are counted in the 10 character length.
  7512.  
  7513.           Examples:
  7514.  
  7515.                FIELD_NAME     CUST_FILE      DATA ITEMS
  7516.  
  7517.  
  7518.      Data Items
  7519.      ----------
  7520.      There are six different classifications of data items as shown below.  Each
  7521.      classification is of one or more types:  string, numeric, and Boolean.  In
  7522.      the table below, these types are represented as shown:
  7523.  
  7524.      N is Numeric (0-9, decimal point, sign)
  7525.      S is String (all alphanumerics)
  7526.      B is Boolean or bit (a bit set or reset)
  7527.  
  7528.       
  7529.               DATA ITEM            TYPE
  7530.  
  7531.           1.  Data registers       N, S
  7532.           2.  Special Registers    N, B
  7533.           3.  Screen data fields   N, S 
  7534.           4.  Literals             N, S
  7535.           5.  Variables            N, S
  7536.           6.  File data fields     N, S
  7537.  
  7538.      1.  Data Registers
  7539.      ------------------
  7540.           #N0-#N9   Numeric registers   Numeric registers may only contain
  7541.                                         numeric data (0-9 decimal point and a
  7542.                                         leading minus sign).
  7543.           #S0-#S9   String registers    String registers may contain a string of
  7544.                                         up to 255 characters.  
  7545.  
  7546.  
  7547.  
  7548.  
  7549.                                        Commands
  7550.                                        Page 112
  7551.  
  7552.  
  7553.  
  7554.  
  7555.  
  7556.  
  7557.  
  7558.                                   Q - PRO 4 Commands
  7559.  
  7560.  
  7561.  
  7562.  
  7563.      2.  Special Registers
  7564.      ---------------------
  7565.           #B0-#B9        The Boolean or flag registers. 
  7566.           #E             The error register.
  7567.           #F             A read-only numeric register which contains the current
  7568.                          screen field number.
  7569.           #K             The keyout register.  The values for this register are
  7570.                          as follows:
  7571.                        Value  Meaning
  7572.                         ---   ------- 
  7573.                          0    typed out
  7574.                          1    tabbed out
  7575.                          2    backtabbed out
  7576.                          3    cursor up 
  7577.                          4    cursor down, newline     
  7578.                          5    cursor left 
  7579.                          6    cursor right
  7580.                          7    enter 
  7581.                          8    home
  7582.                          9    any function key
  7583.                         10    break
  7584.  
  7585.           #L             The line counter register.
  7586.           #P             The page number register.
  7587.  
  7588.      3.  Screen Data Fields
  7589.      ----------------------
  7590.      Screen fields are defined by the programmer.  They may be manipulated in
  7591.      any way. 
  7592.  
  7593.      4. Literals
  7594.      -----------
  7595.      Literals (constant values) may be numeric, string or control character .
  7596.           String literal examples:  "THIS IS A STRING LITERAL"
  7597.                                     'A string literal with single quotes'
  7598.           Numeric literal examples: 19746    289567
  7599.           Control character literal examples: @44   @158  @(#N0 + 5)
  7600.  
  7601.      5. Variables 
  7602.      ------------
  7603.      Variables are data items, maintained in memory.  They may take on single
  7604.      values (in which case they are referenced directly by name), or multiple
  7605.      values (in which case we call them ARRAYS, and reference them with an
  7606.      indexing expression which names the specific element of the array we desire
  7607.  
  7608.  
  7609.                                        Commands
  7610.                                        Page 113
  7611.  
  7612.  
  7613.  
  7614.  
  7615.  
  7616.  
  7617.  
  7618.                                   Q - PRO 4 Commands
  7619.  
  7620.  
  7621.      to access).
  7622.  
  7623.      6. File Data Fields
  7624.      -------------------
  7625.      Fields in data records may be accessed in two ways, either by their
  7626.      relative positions within the record, or by their names.  The second way is
  7627.      accomplished by associating a FID (field item descriptor) file with a data
  7628.      file.  Syntax:
  7629.  
  7630.           &FIELD NAME [<FILE NUMBER> {, <INDEX>}
  7631.  
  7632.      The ampersand (&) in front of the field name tells Q-PRO 4 that this is a
  7633.      file field name.  The <FIELD NAME> tells the system where on the record the
  7634.      data is located.  The <FILE NUMBER> tells the system which file is to be
  7635.      used (since different files may have the same field names).  The optional
  7636.      index selects one element from a field array when appropriate.  Example:  
  7637.  
  7638.           &CUSTNAME[1,2]
  7639.  
  7640.      Expressions
  7641.      -----------
  7642.      An expression is a set of numeric data items joined by mathematical
  7643.      operators which Q-PRO 4 will evaluate into a number.  Many of the Q-PRO 4
  7644.      commands may use expressions.  This allows the programmer to let the
  7645.      program calculate complex relationships.
  7646.  
  7647.      For example, a particular element in an array is desired at a given time is
  7648.      5 or ARRAY[5], and at another time, it may be 6, etc.  This element may be
  7649.      calculated in an expression such that it is dynamically set instead of
  7650.      explicitly set by ARRAY[expression].  The expression is any set of numeric
  7651.      data items such as:
  7652.           
  7653.           #N1 + (#N2 * 3)
  7654.           ARRAY[#N1 + 2]
  7655.           ARRAY[#N1+(#N2 * #N3)]
  7656.           ARRAY[ARRAY[#N3]]
  7657.  
  7658.           Examples: MOVE ARRAY1[#N1 + #N2 + 3] TO ARRAY2[#N1-#N2]
  7659.                     ADD ARRAY1[#N1 + (#N2 + 3)] TO $FIELD[#F + #N1]
  7660.  
  7661.  
  7662.  
  7663.  
  7664.  
  7665.  
  7666.  
  7667.  
  7668.  
  7669.                                        Commands
  7670.                                        Page 114
  7671.  
  7672.  
  7673.  
  7674.  
  7675.  
  7676.  
  7677.  
  7678.                                   Q - PRO 4 Commands
  7679.  
  7680.  
  7681.                                    Function Summary
  7682.                                    ================
  7683.       
  7684.      $ASC(data item)     Returns the decimal for the ASCII data item 
  7685.      $ETOX(data item)    Returns e raised to the data item power
  7686.      $FIELD(data item)   Returns the screen data field value given an offset
  7687.      $INT(data item)     Returns the integer
  7688.      $LN(data item)      Returns the natural log
  7689.      $MEMEND()           Returns the top of memory
  7690.      $OFFSET(fieldname)  Returns the offset of the named field
  7691.       
  7692.  
  7693.  
  7694.  
  7695.  
  7696.  
  7697.  
  7698.  
  7699.  
  7700.  
  7701.  
  7702.  
  7703.  
  7704.  
  7705.  
  7706.  
  7707.  
  7708.  
  7709.  
  7710.  
  7711.  
  7712.  
  7713.  
  7714.  
  7715.  
  7716.  
  7717.  
  7718.  
  7719.  
  7720.  
  7721.  
  7722.  
  7723.  
  7724.  
  7725.  
  7726.  
  7727.  
  7728.  
  7729.                                        Commands
  7730.                                        Page 115
  7731.  
  7732.  
  7733.  
  7734.  
  7735.  
  7736.  
  7737.  
  7738.                                   Q - PRO 4 Commands
  7739.  
  7740.  
  7741.                                    Command Summary
  7742.                                    ===============
  7743.  
  7744.  
  7745.      ACCURACY       Sets the number of decimal places of accuracy.
  7746.      ADD            Adds two numeric data items together.
  7747.      ASEAR          Searches a memory array.
  7748.      BACKSPACE      Backspaces the file one record.
  7749.      BEGIN          Denotes the beginning of the structured construct.  
  7750.      BELL           Causes the audible alarm to sound.
  7751.      BUFFER         Changes the size of the keyboard keying buffer.
  7752.      BROFF          Disables PROC BREAK (if any).
  7753.      BRON           Enables PROC BREAK (if any).
  7754.      CALC           Calculates the value of an expression.
  7755.      CALL           Calls a subroutine.
  7756.      CENTER         Centers data in a string data item.
  7757.      CHAIN          Loads and executes another Q-PRO 4 program.
  7758.      CLEAR          Clears a data entry field.
  7759.      CLOSE          Closes a data file.
  7760.      CONCAT         Concatenates a set of string data items into one string data
  7761.                     item.
  7762.      CURSOR         Positions the cursor independently of the displayed form and
  7763.                     its fields.
  7764.      CURRENCY       Changes the currency symbol used in EDIT.
  7765.      DEBUG          For program debugging. 
  7766.      DEFSEG         For 16 bit versions for PEEK, POKE and DEBUG.
  7767.      DIV            Divides one data item by another.
  7768.      EDIT           Formats numeric data items according to a picture of the
  7769.                     desired result.
  7770.      ELSE           Alternate branch for a structured function.
  7771.      END            Marks the end of a procedure or table.
  7772.      ENDBEGIN       Denotes the end of a structured function. 
  7773.      ENDFOR         Terminate a FOR loop.
  7774.      ERASE          Removes a file from a diskette.
  7775.      ERROR          Displays error message on the bottom of the screen.
  7776.      ERRTRAP        Sets a label as an error branch, or clears such a label if
  7777.                     an error branch was previously set.
  7778.      EXEC           Runs a machine code routine. 
  7779.      FCOPY          Copies a file. 
  7780.      FILETYPE       Returns information about an open file.
  7781.      FILL           Makes field fill in unlocked screen fields any character
  7782.                     desired.
  7783.      FOR            Marks the beginning of a loop.       
  7784.      FORMLOAD       Returns control to FB on fatal error or returning to system.
  7785.      FREE           Deletes a record from an indexed file.
  7786.      FSEAR          Searches a data file on a record-by-record basis for of any
  7787.  
  7788.  
  7789.                                        Commands
  7790.                                        Page 116
  7791.  
  7792.  
  7793.  
  7794.  
  7795.  
  7796.  
  7797.  
  7798.                                   Q - PRO 4 Commands
  7799.  
  7800.  
  7801.                     logical condition.
  7802.      GET            Moves a data field from a file buffer.
  7803.      GETDATE        Loads the current system date.
  7804.      GOTO           Immediate jump to label or line number.
  7805.      HELP           Displays help screens created by the programmer.
  7806.      HOFF           Turns highlights off at the cursor position.
  7807.      HON            Turns the screen highlight on at cursor position.
  7808.      HOME           Homes the cursor.
  7809.      HOMECLEAR      Homes the cursor and clears all enterable fields.
  7810.      HOST           Establishes the host operating system. 
  7811.      IF             Conditionally executes program statements.
  7812.      INSTR          Searches a string for a substring.
  7813.      JDPACK         Calculates a Julian date and moves it into a data item.
  7814.      JDUNPACK       Converts the previously created Julian date in a data item
  7815.                     to a calendar date.
  7816.      LJUST          Left justifies data.
  7817.      KEY            Changes the file current KEY.  
  7818.      LOAD           Loads a machine code file into memory.
  7819.      LOCK           Makes an enterable screen data field not enterable.
  7820.      LPDETACH       Detaches the process from the system printer.
  7821.      LRETRY         Sets the retry count for header locking on LANs.
  7822.      MAKE           Creates a data file.
  7823.      MEMEND         Sets the high address in memory for QNE can use, normally
  7824.                     for use of machine language programs
  7825.      MOVE           Transfers data between data items.
  7826.      MUL            Multiplies two data items.
  7827.      NCHECK         Verifies that a string data item contains valid numeric
  7828.                     data.
  7829.      NEXT           Moves the cursor to a specified screen field.
  7830.      NOFORMLOAD     Resets indicator set by the FORMLOAD command.
  7831.      NOTRACE        Turns off TRACE mode.
  7832.      OPEN           Locates file on disk and readies it for I/O operations.
  7833.      PEEK           Loads data into a string from memory.
  7834.      POKE           Moves a string of data into memory. 
  7835.      POSN           Positions a random or indexed file to a record.
  7836.      PRINT          Prints directly to the screen.
  7837.      PRINTSCN       Dumps the screen to the list device.
  7838.      PROC           Denotes the start of a procedure.
  7839.      PUT            Transfers data to a file buffer or printer.
  7840.      RCLEAR         Clears the record buffer, resets the pointer.  
  7841.      READ           Used to access data records within a file.
  7842.      RENAME         Changes the name of a file.
  7843.      RESET          Clears a Boolean flag register. 
  7844.      RESTART        Resets the file buffer or performs a form feed.
  7845.      RESUME         Return control to the operator for data entry.
  7846.      RETURN         Returns control to a CALL PROC. 
  7847.  
  7848.  
  7849.                                        Commands
  7850.                                        Page 117
  7851.  
  7852.  
  7853.  
  7854.  
  7855.  
  7856.  
  7857.  
  7858.                                   Q - PRO 4 Commands
  7859.  
  7860.  
  7861.      RJUST          Right justifies data.
  7862.      RLOCK          Locks the currently positioned record in the file. 
  7863.      ROUND          Rounds a numeric quantity to some significant number of
  7864.                     digits.
  7865.      RUN            Executes another program directly from Q-PRO 4.
  7866.      RUNLOCK        Unlocks the currently locked record in the file.
  7867.      SECURE         Forces the update of an indexed file.
  7868.      SET            Sets a Boolean flag register.
  7869.      SETDATE        Sets the system date.
  7870.      SIZE           Computes the length of a string data item.
  7871.      SUB            Subtracts one data item from another.
  7872.      SYSMODE        General system command to change characteristic of backtab
  7873.                     and printer detection errors.
  7874.      SYSTEM         Gives control back to the operating system. 
  7875.      TABLE          Denotes the start of a data table.
  7876.      TRACE          Places Q-PRO 4 in a single step debugging mode.
  7877.      TSEAR          Initiates the search of a table.
  7878.      UCASE          Forces a string data item to upper case.
  7879.      UNEDIT         Removes editing characters from a string field.
  7880.      UNLOCK         Unlocks a previously locked field.
  7881.      VRBL           Establishes in-memory variables.
  7882.      WRITE          Outputs a data record to a file.
  7883.  
  7884.  
  7885.  
  7886.  
  7887.  
  7888.  
  7889.  
  7890.  
  7891.  
  7892.  
  7893.  
  7894.  
  7895.  
  7896.  
  7897.  
  7898.  
  7899.  
  7900.  
  7901.  
  7902.  
  7903.  
  7904.  
  7905.  
  7906.  
  7907.  
  7908.  
  7909.                                        Commands
  7910.                                        Page 118
  7911.  
  7912.  
  7913.  
  7914.  
  7915.  
  7916.  
  7917.  
  7918.                                   Q - PRO 4 Commands
  7919.  
  7920.  
  7921.                                   F u n c t i o n s
  7922.                                   =================
  7923.  
  7924.      $ASC
  7925.      ----
  7926.      The function $ASC returns the decimal value of the ASCII data item.
  7927.  
  7928.      Syntax: $ASC(<ASCII data item>)
  7929.  
  7930.      ASCII data item     A literal in quotes, a string register or string
  7931.                          variable.
  7932.  
  7933.      Examples:      $ASC("3")      returns 51
  7934.                     $ASC("A")      returns 65
  7935.  
  7936.  
  7937.  
  7938.  
  7939.  
  7940.  
  7941.  
  7942.  
  7943.  
  7944.  
  7945.  
  7946.  
  7947.  
  7948.  
  7949.  
  7950.  
  7951.  
  7952.  
  7953.  
  7954.  
  7955.  
  7956.  
  7957.  
  7958.  
  7959.  
  7960.  
  7961.  
  7962.  
  7963.  
  7964.  
  7965.  
  7966.  
  7967.  
  7968.  
  7969.                                        Commands
  7970.                                        Page 119
  7971.  
  7972.  
  7973.  
  7974.  
  7975.  
  7976.  
  7977.  
  7978.                                   Q - PRO 4 Commands
  7979.  
  7980.  
  7981.      $ETOX
  7982.      -----
  7983.      The $ETOX function returns the value of the natural constant e raised to
  7984.      the expression power.  On 8 bit systems, MATHLIB must be loaded.  (The
  7985.      MATHLIB command is ignored on other systems.)
  7986.  
  7987.      Syntax:   $ETOX(<expression>)
  7988.  
  7989.      expression     An evaluatable mathematical expression.
  7990.  
  7991.      Examples:      CALC EPOWER = $ETOX(#N1)
  7992.                     CALC COMPLEX = $ETOX((#N1 + #N2}2) -1)
  7993.  
  7994.  
  7995.  
  7996.  
  7997.  
  7998.  
  7999.  
  8000.  
  8001.  
  8002.  
  8003.  
  8004.  
  8005.  
  8006.  
  8007.  
  8008.  
  8009.  
  8010.  
  8011.  
  8012.  
  8013.  
  8014.  
  8015.  
  8016.  
  8017.  
  8018.  
  8019.  
  8020.  
  8021.  
  8022.  
  8023.  
  8024.  
  8025.  
  8026.  
  8027.  
  8028.  
  8029.                                        Commands
  8030.                                        Page 120
  8031.  
  8032.  
  8033.  
  8034.  
  8035.  
  8036.  
  8037.  
  8038.                                   Q - PRO 4 Commands
  8039.  
  8040.  
  8041.      $FIELD
  8042.      ------
  8043.      $FIELD is a function that returns the screen data field that corresponds to
  8044.      the offset value.  Its parameter is the number of the field to be
  8045.      addressed.  Using this function, the programmer may dynamically address and
  8046.      manipulate data in screen data fields symbolically instead of by name. 
  8047.      Refer to the Programmer's Reference Manual and sample programs for more
  8048.      detail and examples.
  8049.  
  8050.      Syntax:   $FIELD(<expression>)
  8051.  
  8052.      expression     Any mathematical expression that evaluates to an integer
  8053.                     without sign.
  8054.  
  8055.      Examples:      ADD $FIELD[#N1] TO SUM
  8056.                          Add the screen data field with the offset contained in
  8057.                          the numeric register #N1 to the screen data field (or
  8058.                          variable) SUM.
  8059.  
  8060.                     MOVE &FILE_FIELD[1,#N1] TO $FIELD[#N1 + (#N1 * 6)]
  8061.                          Move the #N1 element of the file data array FILE_FIELD
  8062.                          on file 1 to the screen data field whose offset is the
  8063.                          evaluation of the expression [#N1 + (#N1 * 6)].
  8064.  
  8065.  
  8066.  
  8067.  
  8068.  
  8069.  
  8070.  
  8071.  
  8072.  
  8073.  
  8074.  
  8075.  
  8076.  
  8077.  
  8078.  
  8079.  
  8080.  
  8081.  
  8082.  
  8083.  
  8084.  
  8085.  
  8086.  
  8087.  
  8088.  
  8089.                                        Commands
  8090.                                        Page 121
  8091.  
  8092.  
  8093.  
  8094.  
  8095.  
  8096.  
  8097.  
  8098.                                   Q - PRO 4 Commands
  8099.  
  8100.  
  8101.      $INT
  8102.      ----
  8103.      $INT is a function that returns the integer portion of a real number.  
  8104.  
  8105.      Syntax:   $INT(<numeric data item>)  
  8106.           
  8107.      numeric data item   A literal number (without quotes), numeric register,
  8108.                          numeric variable, or numeric screen data field. 
  8109.  
  8110.      Examples:      CALC #N1 =#N1 + $INT(#N2)
  8111.                          CALCulates and places in #N1 the current value of #N1
  8112.                          plus the integer portion of #N2.
  8113.  
  8114.                     CALC #N1 =$INT(5.05)
  8115.                          Result in #N1 is 5.
  8116.  
  8117.                     CALC #N1 =#N2-#N2 * $INT(#N2}#N1) 
  8118.                          The result in #N1 is modulo #n1.
  8119.  
  8120.  
  8121.  
  8122.  
  8123.  
  8124.  
  8125.  
  8126.  
  8127.  
  8128.  
  8129.  
  8130.  
  8131.  
  8132.  
  8133.  
  8134.  
  8135.  
  8136.  
  8137.  
  8138.  
  8139.  
  8140.  
  8141.  
  8142.  
  8143.  
  8144.  
  8145.  
  8146.  
  8147.  
  8148.  
  8149.                                        Commands
  8150.                                        Page 122
  8151.  
  8152.  
  8153.  
  8154.  
  8155.  
  8156.  
  8157.  
  8158.                                   Q - PRO 4 Commands
  8159.  
  8160.  
  8161.      $LN
  8162.      ---
  8163.      $LN is a function that returns the natural logarithm of the included
  8164.      expression.  $LN may be used in conjunction with ACCURACY to limit the
  8165.      accuracy and decrease the execution time.
  8166.  
  8167.      Syntax:   $LN(<expression>)
  8168.  
  8169.      expression     A mathematically evaluatable set of terms and operators.
  8170.  
  8171.      Example:       CALC COMPLEX = $LN((#N1 + #N2)  * #N3)
  8172.  
  8173.      $MEMEND()
  8174.      ---------
  8175.      The $MEMEND() function returns the current top of memory being used by
  8176.      Q-PRO 4, its file buffers and keypool.  Some of this memory, particularly
  8177.      in the keypool area can be used by the programmer for assembly language
  8178.      routines without impacting Q-PRO 4 or the remainder of memory.  When Q-PRO
  8179.      4 is loaded, the memory is laid out like this:
  8180.  
  8181.      |-----Top of memory-----------|
  8182.      |                             |
  8183.      |  This area is available     |
  8184.      |                             |
  8185.      |                             |
  8186.      |-298K (All that can be used)-|
  8187.      |                             |
  8188.      |                             | 
  8189.      |Q-PRO 4 Data area, up to 64K |
  8190.      |                             |
  8191.      |-----------------------------|
  8192.      |                             |
  8193.      | Application area, up to 64K |
  8194.      |                             |
  8195.      |-----------------------------|
  8196.      |                             |
  8197.      | Runtime Interpreter - 42K   |
  8198.      |                             |
  8199.      |-----------------------------|
  8200.      |                             |
  8201.      |    BTSYS - the file system  |
  8202.      |     (requires 100K)         |
  8203.      |-----------------------------|
  8204.      |    Operating System         |
  8205.      |                             |
  8206.      |------Bottom of Memory-------|
  8207.  
  8208.  
  8209.                                        Commands
  8210.                                        Page 123
  8211.  
  8212.  
  8213.  
  8214.  
  8215.  
  8216.  
  8217.  
  8218.                                   Q - PRO 4 Commands
  8219.  
  8220.  
  8221.      The command:
  8222.  
  8223.      MEMEND $MEMEND() - 1024
  8224.  
  8225.      produces this result
  8226.  
  8227.      |-----Top of memory-----------|
  8228.      |                             |
  8229.      |  1024 bytes available for   |
  8230.      |   assembly language program |
  8231.      |-----------------------------|
  8232.      |  Memory available for key   |
  8233.      |  pool.                      |
  8234.      |-----------------------------| 
  8235.      |Q-PRO 4 Data area, up to 64K |
  8236.      |                             |
  8237.      |-----------------------------|
  8238.      |                             |
  8239.      | Application area, up to 64K |
  8240.      |                             |
  8241.      |-----------------------------|
  8242.      |                             |
  8243.      | Runtime Interpreter - 42K   |
  8244.      |                             |
  8245.      |-----------------------------|
  8246.      |                             |
  8247.      |    BTSYS - the file system  |
  8248.      |     (requires 100K)         |
  8249.      |-----------------------------|
  8250.      |    Operating System         |
  8251.      |                             |
  8252.      |------Bottom of Memory-------|
  8253.  
  8254.      Use the MA command in DEBUG to find out the keypool size so you can
  8255.      determine exactly how much memory the program requires.
  8256.  
  8257.  
  8258.  
  8259.  
  8260.  
  8261.  
  8262.  
  8263.  
  8264.  
  8265.  
  8266.  
  8267.  
  8268.  
  8269.                                        Commands
  8270.                                        Page 124
  8271.  
  8272.  
  8273.  
  8274.  
  8275.  
  8276.  
  8277.  
  8278.                                   Q - PRO 4 Commands
  8279.  
  8280.  
  8281.      $OFFSET
  8282.      -------
  8283.      The function $OFFSET returns the offset of the named screen data field. 
  8284.      Use of this function allows generalized code for symbolic screen data
  8285.      manipulation relative to screen data fields.
  8286.  
  8287.      Syntax:   OFFSET<screen data field name>
  8288.  
  8289.      screen data field name   The name of the screen data field in quotes.
  8290.  
  8291.      Examples:           CALC #N1 = $OFFSET("DATE")
  8292.                               #N1 will contain the offset of the screen data
  8293.                               field DATE.
  8294.  
  8295.           Note that:  $OFFSET($FIELD[#F]) = #F     
  8296.       
  8297.  
  8298.  
  8299.  
  8300.  
  8301.  
  8302.  
  8303.  
  8304.  
  8305.  
  8306.  
  8307.  
  8308.  
  8309.  
  8310.  
  8311.  
  8312.  
  8313.  
  8314.  
  8315.  
  8316.  
  8317.  
  8318.  
  8319.  
  8320.  
  8321.  
  8322.  
  8323.  
  8324.  
  8325.  
  8326.  
  8327.  
  8328.  
  8329.                                        Commands
  8330.                                        Page 125
  8331.  
  8332.  
  8333.  
  8334.  
  8335.  
  8336.  
  8337.  
  8338.                                   Q - PRO 4 Commands
  8339.  
  8340.  
  8341.                                    C O M M A N D S
  8342.                                    ===============
  8343.  
  8344.      ACCURACY
  8345.      --------
  8346.      ACCURACY is used with ETOX, exponentiation and LN to set the degree of
  8347.      accuracy that the calculations will be carried out.  As all of these
  8348.      routines are mathematically converging functions, by using this command,
  8349.      execution will take only as long as required for the computation.
  8350.  
  8351.      Syntax:   ACCURACY(<numeric data item>)
  8352.  
  8353.      numeric data item   Any expression that evaluates to a whole number between
  8354.                          1 and 7.  
  8355.      Remarks             The default is 7.
  8356.  
  8357.      Examples:
  8358.                ACCURACY(#n1)
  8359.                ACCURACY(3)
  8360.        
  8361.  
  8362.  
  8363.  
  8364.  
  8365.  
  8366.  
  8367.  
  8368.  
  8369.  
  8370.  
  8371.  
  8372.  
  8373.  
  8374.  
  8375.  
  8376.  
  8377.  
  8378.  
  8379.  
  8380.  
  8381.  
  8382.  
  8383.  
  8384.  
  8385.  
  8386.  
  8387.  
  8388.  
  8389.                                        Commands
  8390.                                        Page 126
  8391.  
  8392.  
  8393.  
  8394.  
  8395.  
  8396.  
  8397.  
  8398.                                   Q - PRO 4 Commands
  8399.  
  8400.  
  8401.      ADD
  8402.      ---
  8403.      The ADD command adds two numeric data items together and optionally places
  8404.      the result in a third numeric data item.  Optionally, the data items may be
  8405.      preceded by minus sign (-).  The results of an add (or any arithmetic
  8406.      operation) may not be stored in a numeric constant.  The receiving data
  8407.      item must be a numeric data item.  For example, ADD FLD1 TO 3 is invalid.
  8408.  
  8409.      Syntax:
  8410.  
  8411.      ADD <data item 1> TO <data item 2>{GIVING <data items><B>}
  8412.  
  8413.      data item 1    A numeric data item such as a literal or numeric register. 
  8414.                     An expression is not allowed.
  8415.  
  8416.      data item 2    A numeric data item.  An expression is not allowed.  If the
  8417.                     GIVING modifier is not present, the sum of data item 1 and
  8418.                     data item 2 will be stored in data item 2 and data item two
  8419.                     must not be a literal.  
  8420.  
  8421.      data item 3    If present, the sum will be placed in this item.  Therefore,
  8422.                     it must not be a variable.
  8423.  
  8424.      Remarks        GIVING is optional serving the purpose of defining a third
  8425.                     data item in which to place the sum.  The keyword TO may be
  8426.                     replaced by a comma.
  8427.  
  8428.      Examples:
  8429.           ADD #N3 TO SUM
  8430.           ADD .5, NUMB GIVING #N1
  8431.           ADD 3 TO FLD1
  8432.           ADD FLD1 TO 3 GIVING FLD1 
  8433.  
  8434.  
  8435.  
  8436.  
  8437.  
  8438.  
  8439.  
  8440.  
  8441.  
  8442.  
  8443.  
  8444.  
  8445.  
  8446.  
  8447.  
  8448.  
  8449.                                        Commands
  8450.                                        Page 127
  8451.  
  8452.  
  8453.  
  8454.  
  8455.  
  8456.  
  8457.  
  8458.                                   Q - PRO 4 Commands
  8459.  
  8460.  
  8461.      ASEAR
  8462.      -----
  8463.      ASEAR searches a memory array by increasing element number (or optionally
  8464.      by decreasing element number) for the value of an element that satisfies an
  8465.      expression.  If an element is found that satisfies the expression, the
  8466.      element number will be returned.  If not, the error path will be taken. 
  8467.  
  8468.      Syntax 1: ASEAR <name> {DOWN} USING <result> AT <expression>:error
  8469.  
  8470.      name           The name of the array to be searched
  8471.  
  8472.      result         The location to place the array element number if a match is
  8473.                     found. 
  8474.  
  8475.      expression     The expression to evaluate the array element.  All logical
  8476.                     expressions are valid.
  8477.  
  8478.      REMARKS        The optional DOWN keyword causes the command to searches the
  8479.                     array by decreasing number.
  8480.  
  8481.      Example:
  8482.           ASEAR MONTHS USING #N1 AT "JAN" = MONTHS[#N1]
  8483.  
  8484.  
  8485.      Syntax 2: ASEAR <name> {DOWN} USING <index> <{STARTING expression2}>AT
  8486.      <expression1>{:error}
  8487.  
  8488.      array name     The array to be searched.
  8489.  
  8490.      {DOWN}         Optionally searches the array from highest order element
  8491.                     number to lowest element number.
  8492.  
  8493.      {index}        On a match of the expression, this numeric data item will
  8494.                     contain the element number with the match.
  8495.      expression1    The expression that the element must match to get a "hit".
  8496.      expression2    The expression that defines the starting place for the
  8497.                     search--optional.
  8498.      Remarks        The use of this syntax allows searching an array (up or
  8499.                     down), and continuing the search after a match by modifying
  8500.                     the variable(s) in expression2 after a match.
  8501.  
  8502.  
  8503.  
  8504.  
  8505.  
  8506.  
  8507.  
  8508.  
  8509.                                        Commands
  8510.                                        Page 128
  8511.  
  8512.  
  8513.  
  8514.  
  8515.  
  8516.  
  8517.  
  8518.                                   Q - PRO 4 Commands
  8519.  
  8520.  
  8521.      BACKSPACE
  8522.      ---------
  8523.      BACKSPACE positions a RANDOM or INDEXED file to the record previous to the
  8524.      current position.  
  8525.  
  8526.      Syntax:   BACKSPACE <file number> {:<B>error}
  8527.  
  8528.      file number    The file number as a literal, or numeric data item.
  8529.      Remarks        An end-of-file error is generated if the file is empty or
  8530.                     already positioned at the first record in the file. 
  8531.  
  8532.      Example:
  8533.  
  8534.           (scan file 1 in reverse order, assuming already at file end)
  8535.  
  8536.      1000 BACKSPACE 1 :1001
  8537.           READ 1 NOADV
  8538.           COPY * FROM 1
  8539.           GOTO 1000
  8540.      1001 ERROR "END OF FILE"
  8541.  
  8542.  
  8543.  
  8544.  
  8545.  
  8546.  
  8547.  
  8548.  
  8549.  
  8550.  
  8551.  
  8552.  
  8553.  
  8554.  
  8555.  
  8556.  
  8557.  
  8558.  
  8559.  
  8560.  
  8561.  
  8562.  
  8563.  
  8564.  
  8565.  
  8566.  
  8567.  
  8568.  
  8569.                                        Commands
  8570.                                        Page 129
  8571.  
  8572.  
  8573.  
  8574.  
  8575.  
  8576.  
  8577.  
  8578.                                   Q - PRO 4 Commands
  8579.  
  8580.  
  8581.      BEGIN
  8582.      -----
  8583.      BEGIN denotes the start of the structured construct.  (ENDBEGIN denotes the
  8584.      termination of the structured construct.)  BEGINs may be nested and may
  8585.      have any of the following modifiers.
  8586.  
  8587.      Syntax:   BEGIN {WHILE, UNTIL, IF}<logical condition>
  8588.  
  8589.      WHILE          Using this keyword, the statements within the BEGIN . . .
  8590.                     ENDBEGIN structure will be repetitively executed as long as
  8591.                     the logical condition is true.
  8592.      UNTIL          Using this keyword,  the statements within the BEGIN . . .
  8593.                     ENDBEGIN structure will be repetitively executed as long as
  8594.                     the logical condition is <BI>not  true.
  8595.      IF             When the IF keyword is used, the statements within the BEGIN
  8596.                     . . . ENDBEGIN structure will be executed once.
  8597.      logical 
  8598.        condition    A logically evaluatable expression.
  8599.  
  8600.      Remarks        BEGIN is allowed one modifier, either, IF, WHILE, or UNTIL.
  8601.  
  8602.  
  8603.      A BEGIN construct with no modifier (WHILE, UNTIL, IF) must be ended with an
  8604.      ENDBEGIN with a modifier of WHILE, UNTIL or IF.
  8605.  
  8606.  
  8607.      BEGIN WHILE logical condition>i is the start of a structured construct that
  8608.      will execute during the time that the conditional value is true.  If the
  8609.      condition remains true, the construct will execute forever.
  8610.  
  8611.  
  8612.      Examples:
  8613.  
  8614.      BEGIN WHILE A GT 0
  8615.           SUB &VALUE(100) FROM A
  8616.           READ 100
  8617.      ENDBEGIN
  8618.  
  8619.           This code will execute during the time that A is greater than 0.  If A
  8620.           is never greater than 0, the code will be ignored.
  8621.  
  8622.      BEGIN UNTIL A EQ 10
  8623.           ADD 1 TO A
  8624.      ENDBEGIN
  8625.  
  8626.           This code will continue executing as long as A is not equal to 10.
  8627.  
  8628.  
  8629.                                        Commands
  8630.                                        Page 130
  8631.  
  8632.  
  8633.  
  8634.  
  8635.  
  8636.  
  8637.  
  8638.                                   Q - PRO 4 Commands
  8639.  
  8640.  
  8641.  
  8642.      BEGIN IF A NEQ 0
  8643.           CALL ZERO_ROUT
  8644.      ENDBEGIN
  8645.  
  8646.           This code will execute only if A is not equal to 0.
  8647.  
  8648.      ELSE and ELSE IF
  8649.      ----------------
  8650.      ELSE and ELSE IF are used only with the BEGIN IF construct.  They provide
  8651.      excellent conditional controls.  The structure is:
  8652.  
  8653.      BEGIN IF<condition 1>
  8654.                statements  executed only if condition 1 is true
  8655.      ELSE IF<condition 2>
  8656.                statements  executed only if condition 2 is true
  8657.      ELSE
  8658.                statements  executed if neither condition 1 nor 
  8659.                    condition 2 is true.
  8660.      ENDBEGIN
  8661.  
  8662.      Examples:
  8663.  
  8664.      BEGIN IF #N1 = 1
  8665.                CALL SUB_ONE
  8666.                CALL SUB_ONE_A
  8667.                SET #B1
  8668.           ELSE IF #N1 = 2
  8669.                CALL SUB_TWO
  8670.                CALL SUB_TWO_A
  8671.                RESET #B1
  8672.           ELSE
  8673.                CALL MAIN_SUB
  8674.                CALL MAIN_SUB_A
  8675.      ENDBEGIN
  8676.  
  8677.           If #N1 equals 1, call subroutines SUB_ONE and SUB_ONE_A and SET #B1. 
  8678.           If #N1 equals 2, call subroutines SUB_TWO and SUB_TWO_A and RESET #B1. 
  8679.           If #N1 does not equal 1 or two, call subroutines MAIN_SUB and
  8680.           MAIN_SUB_A.
  8681.  
  8682.      A variation of the BEGIN/ENDBEGIN pairing is putting the condition after
  8683.      the ENDBEGIN.
  8684.  
  8685.      Examples:
  8686.  
  8687.  
  8688.  
  8689.                                        Commands
  8690.                                        Page 131
  8691.  
  8692.  
  8693.  
  8694.  
  8695.  
  8696.  
  8697.  
  8698.                                   Q - PRO 4 Commands
  8699.  
  8700.  
  8701.      BEGIN
  8702.           SUB 1 FROM A
  8703.      ENDBEGIN WHILE A LT 100
  8704.  
  8705.      BEGIN
  8706.           ADD 1 TO A
  8707.      ENDBEGIN UNTIL A GT #N1
  8708.  
  8709.  
  8710.  
  8711.  
  8712.  
  8713.  
  8714.  
  8715.  
  8716.  
  8717.  
  8718.  
  8719.  
  8720.  
  8721.  
  8722.  
  8723.  
  8724.  
  8725.  
  8726.  
  8727.  
  8728.  
  8729.  
  8730.  
  8731.  
  8732.  
  8733.  
  8734.  
  8735.  
  8736.  
  8737.  
  8738.  
  8739.  
  8740.  
  8741.  
  8742.  
  8743.  
  8744.  
  8745.  
  8746.  
  8747.  
  8748.  
  8749.                                        Commands
  8750.                                        Page 132
  8751.  
  8752.  
  8753.  
  8754.  
  8755.  
  8756.  
  8757.  
  8758.                                   Q - PRO 4 Commands
  8759.  
  8760.  
  8761.      BELL
  8762.      ----
  8763.      The BELL command causes the audible alarm to sound (if supported by the
  8764.      hardware).
  8765.  
  8766.      Syntax:   BELL
  8767.  
  8768.  
  8769.  
  8770.  
  8771.  
  8772.  
  8773.  
  8774.  
  8775.  
  8776.  
  8777.  
  8778.  
  8779.  
  8780.  
  8781.  
  8782.  
  8783.  
  8784.  
  8785.  
  8786.  
  8787.  
  8788.  
  8789.  
  8790.  
  8791.  
  8792.  
  8793.  
  8794.  
  8795.  
  8796.  
  8797.  
  8798.  
  8799.  
  8800.  
  8801.  
  8802.  
  8803.  
  8804.  
  8805.  
  8806.  
  8807.  
  8808.  
  8809.                                        Commands
  8810.                                        Page 133
  8811.  
  8812.  
  8813.  
  8814.  
  8815.  
  8816.  
  8817.  
  8818.                                   Q - PRO 4 Commands
  8819.  
  8820.  
  8821.      BUFFER
  8822.      ------
  8823.      The BUFFER command changes the size of the keyboard buffer (used to buffer
  8824.      up keystrokes while programming statements are being executed).  The
  8825.      default size of this buffer is 32 characters.  It may be set to any size
  8826.      between 0 and 255.
  8827.  
  8828.      Setting the buffer to zero (0) will speed processing of files and screens. 
  8829.      However, when set to 0, the BREAK procedure, if used, will be disabled. 
  8830.      Also, the machine keyboard buffer, if there is one, is flushed when a
  8831.      BUFFER statement is executed.
  8832.  
  8833.      Syntax:   BUFFER <numeric data item>
  8834.  
  8835.      numeric data item   A literal or other numeric data item.
  8836.  
  8837.      Examples:
  8838.  
  8839.           BUFFER 100
  8840.           BUFFER #N0
  8841.  
  8842.  
  8843.  
  8844.  
  8845.  
  8846.  
  8847.  
  8848.  
  8849.  
  8850.  
  8851.  
  8852.  
  8853.  
  8854.  
  8855.  
  8856.  
  8857.  
  8858.  
  8859.  
  8860.  
  8861.  
  8862.  
  8863.  
  8864.  
  8865.  
  8866.  
  8867.  
  8868.  
  8869.                                        Commands
  8870.                                        Page 134
  8871.  
  8872.  
  8873.  
  8874.  
  8875.  
  8876.  
  8877.  
  8878.                                   Q - PRO 4 Commands
  8879.  
  8880.  
  8881.      BROFF
  8882.      -----
  8883.      BROFF disables the current PROC BREAK (if any).
  8884.           
  8885.  
  8886.      Syntax:   BROFF
  8887.  
  8888.      Example:
  8889.           BROFF
  8890.  
  8891.  
  8892.  
  8893.      BRON
  8894.      ----
  8895.      BRON enables the current PROC BREAK (if any).
  8896.  
  8897.      Syntax:   BRON
  8898.  
  8899.      Example:  BRON
  8900.  
  8901.  
  8902.  
  8903.  
  8904.  
  8905.  
  8906.  
  8907.  
  8908.  
  8909.  
  8910.  
  8911.  
  8912.  
  8913.  
  8914.  
  8915.  
  8916.  
  8917.  
  8918.  
  8919.  
  8920.  
  8921.  
  8922.  
  8923.  
  8924.  
  8925.  
  8926.  
  8927.  
  8928.  
  8929.                                        Commands
  8930.                                        Page 135
  8931.  
  8932.  
  8933.  
  8934.  
  8935.  
  8936.  
  8937.  
  8938.                                   Q - PRO 4 Commands
  8939.  
  8940.  
  8941.      CALC
  8942.      ----
  8943.      CALC allows the computation of algebraic expressions in those circumstances
  8944.      where the use of the ADD, SUB, MUL, or DIV commands would be clumsy.
  8945.  
  8946.      Syntax:   CALC<data item> = <expression>
  8947.  
  8948.      data item      The data item may be any valid numeric data item.
  8949.      expression     The expression is an algebraic expression which may contain
  8950.                     nested parentheses and uses the following operators and
  8951.                     functions:
  8952.  
  8953.                + = addition             $LN       $OFFSET
  8954.                - = subtraction          $ETOX     $FIELD
  8955.                * = multiplication       $INT
  8956.                / = division
  8957.                ^ = exponentiation 
  8958.           
  8959.      Multiplication, division, and exponentiation have precedence over addition
  8960.      and subtraction, unless overridden with parentheses.   Exponentiation, $LN,
  8961.      $ETOX, and $INT require MATHLIB to be loaded on 8 bit systems.
  8962.  
  8963.      Examples:
  8964.  
  8965.           CALC TOTAL = FLD1 + FLD2 + #INT(&FLD[1])
  8966.           CALC $FIELD[#N0] = (ACCTBAL+5) } 3
  8967.           CALC AVERAGE = (SUM1+SUM2+SUM3+SUM4+SUM5)}5
  8968.           CALC SQUARE = NUM ^ 2
  8969.           CALC COMPLEX=(((FLD1+3)}(FLD2*7))-#N[CUSTTYPE])+ 11.5
  8970.  
  8971.  
  8972.  
  8973.  
  8974.  
  8975.  
  8976.  
  8977.  
  8978.  
  8979.  
  8980.  
  8981.  
  8982.  
  8983.  
  8984.  
  8985.  
  8986.  
  8987.  
  8988.  
  8989.                                        Commands
  8990.                                        Page 136
  8991.  
  8992.  
  8993.  
  8994.  
  8995.  
  8996.  
  8997.  
  8998.                                   Q - PRO 4 Commands
  8999.  
  9000.  
  9001.      CALL
  9002.      ----
  9003.      CALL invokes another procedure.  Control is returned to the statement
  9004.      following the CALL when the CALLed procedure executes a RETURN statement. 
  9005.      A maximum of 20 CALL and/or FOR statements may be nested.
  9006.  
  9007.      Syntax:   CALL <procedure>
  9008.  
  9009.      procedure      A procedure name.  Any procedure may be CALLed.  It is the
  9010.                     responsibility of the programmer to insure that the CALLed
  9011.                     procedure returns to the calling procedure.  On RETURN, the
  9012.                     next sequential statement will be executed    
  9013.  
  9014.  
  9015.      The procedure may be replaced by an indexed table name (i.e.,
  9016.      PROCTBL[#N3]).  This allows a computed call facility, affording great
  9017.      flexibility to the programmer.  The table so referenced must consist of a
  9018.      series of 1-item entries, each item being the name of a procedure.  Each
  9019.      item is referenced by its position in the table, starting with 0 as the
  9020.      index of the first position.
  9021.  
  9022.      Examples:
  9023.  
  9024.           CALL ALPHA1
  9025.           CALL PRCTABLE[#N1]
  9026.  
  9027.  
  9028.  
  9029.  
  9030.  
  9031.  
  9032.  
  9033.  
  9034.  
  9035.  
  9036.  
  9037.  
  9038.  
  9039.  
  9040.  
  9041.  
  9042.  
  9043.  
  9044.  
  9045.  
  9046.  
  9047.  
  9048.  
  9049.                                        Commands
  9050.                                        Page 137
  9051.  
  9052.  
  9053.  
  9054.  
  9055.  
  9056.  
  9057.  
  9058.                                   Q - PRO 4 Commands
  9059.  
  9060.  
  9061.      CENTER
  9062.      ------
  9063.      The CENTER command centers data in a string data item.  Centering will
  9064.      occur even in fields defined as right or left justified.
  9065.  
  9066.      Syntax:   CENTER <data item>
  9067.  
  9068.      Example:  CENTER BANNER
  9069.  
  9070.  
  9071.  
  9072.  
  9073.  
  9074.  
  9075.  
  9076.  
  9077.  
  9078.  
  9079.  
  9080.  
  9081.  
  9082.  
  9083.  
  9084.  
  9085.  
  9086.  
  9087.  
  9088.  
  9089.  
  9090.  
  9091.  
  9092.  
  9093.  
  9094.  
  9095.  
  9096.  
  9097.  
  9098.  
  9099.  
  9100.  
  9101.  
  9102.  
  9103.  
  9104.  
  9105.  
  9106.  
  9107.  
  9108.  
  9109.                                        Commands
  9110.                                        Page 138
  9111.  
  9112.  
  9113.  
  9114.  
  9115.  
  9116.  
  9117.  
  9118.                                   Q - PRO 4 Commands
  9119.  
  9120.  
  9121.      CHAIN
  9122.      -----
  9123.      The CHAIN command brings in another segment of the application.  It causes
  9124.      the named format file to be loaded from disk, its associated screen to be
  9125.      displayed, and processing to continue.  The file name may be any valid
  9126.      string data item.  All register settings, open files and file buffers are
  9127.      maintained across a chain statement, whereas variables are not.
  9128.  
  9129.      Syntax:   CHAIN <name> {:error} 
  9130.  
  9131.      filename       The actual filename in quotes or a valid filename in a
  9132.                     string data item.
  9133.      error          Label to jump to if there is an error.
  9134.      Remarks        If a string data item is to be used, it is highly
  9135.                     recommended that it be moved to a string register trimmed as
  9136.                     shown in the code below.  This will preclude trailing blanks
  9137.                     confusing the operating system.
  9138.  
  9139.                     MOVE VARIABLE TO #S0 TRIMMED
  9140.                     CHAIN #S0
  9141.  
  9142.      Examples:
  9143.           CHAIN "MENU2"
  9144.           CHAIN #S0 :100
  9145.  
  9146.  
  9147.  
  9148.  
  9149.  
  9150.  
  9151.  
  9152.  
  9153.  
  9154.  
  9155.  
  9156.  
  9157.  
  9158.  
  9159.  
  9160.  
  9161.  
  9162.  
  9163.  
  9164.  
  9165.  
  9166.  
  9167.  
  9168.  
  9169.                                        Commands
  9170.                                        Page 139
  9171.  
  9172.  
  9173.  
  9174.  
  9175.  
  9176.  
  9177.  
  9178.                                   Q - PRO 4 Commands
  9179.  
  9180.  
  9181.      CLEAR
  9182.      -----
  9183.      The CLEAR command causes the contents of a screen data field to be cleared
  9184.      to spaces.
  9185.  
  9186.      Syntax:   CLEAR <field or *>
  9187.  
  9188.      field          The literal name of the field or the result of a $FIELD
  9189.                     function.
  9190.      *              If the * option is used instead of a specific field name,
  9191.                     then all enterable, unlocked, and unduplicated fields on the
  9192.                     screen are cleared.
  9193.  
  9194.      Examples:
  9195.  
  9196.           CLEAR CUSTNO
  9197.           CLEAR $FIELD[#F]
  9198.           CLEAR *
  9199.  
  9200.  
  9201.  
  9202.  
  9203.  
  9204.  
  9205.  
  9206.  
  9207.  
  9208.  
  9209.  
  9210.  
  9211.  
  9212.  
  9213.  
  9214.  
  9215.  
  9216.  
  9217.  
  9218.  
  9219.  
  9220.  
  9221.  
  9222.  
  9223.  
  9224.  
  9225.  
  9226.  
  9227.  
  9228.  
  9229.                                        Commands
  9230.                                        Page 140
  9231.  
  9232.  
  9233.  
  9234.  
  9235.  
  9236.  
  9237.  
  9238.                                   Q - PRO 4 Commands
  9239.  
  9240.  
  9241.      CLOSE
  9242.      -----
  9243.      CLOSE causes a data file to be closed, and the directory for the disk on
  9244.      which it resides to be updated.  All files should be closed when no longer
  9245.      needed.  Q-PRO 4 will close any files left open before returning to the
  9246.      operating system.
  9247.  
  9248.      Syntax:   CLOSE <file number> {:error}
  9249.  
  9250.      file number         The file number as a literal or symbolic data item.
  9251.      error               The label to jump to if there is an error.
  9252.      Remarks             If no file number is given, then the system will close
  9253.                          all open files, and reset the file control system (the
  9254.                          currently logged drive is preserved).
  9255.  
  9256.      Examples:
  9257.           CLOSE 1
  9258.           CLOSE 99 :320
  9259.           CLOSE
  9260.  
  9261.  
  9262.  
  9263.  
  9264.  
  9265.  
  9266.  
  9267.  
  9268.  
  9269.  
  9270.  
  9271.  
  9272.  
  9273.  
  9274.  
  9275.  
  9276.  
  9277.  
  9278.  
  9279.  
  9280.  
  9281.  
  9282.  
  9283.  
  9284.  
  9285.  
  9286.  
  9287.  
  9288.  
  9289.                                        Commands
  9290.                                        Page 141
  9291.  
  9292.  
  9293.  
  9294.  
  9295.  
  9296.  
  9297.  
  9298.                                   Q - PRO 4 Commands
  9299.  
  9300.  
  9301.      COMMENT
  9302.      A COMMENT line is ignored by Q-PRO 4 and is intended to aid in the
  9303.      self-documentation of programs.  A comment line may be preceded by a line
  9304.      number or label.  Comments are not loaded at runtime.
  9305.  
  9306.      Example:
  9307.  
  9308.      * THIS IS A COMMENT
  9309.      102: * THIS IS A COMMENT WITH A LABEL
  9310.  
  9311.  
  9312.  
  9313.  
  9314.  
  9315.  
  9316.  
  9317.  
  9318.  
  9319.  
  9320.  
  9321.  
  9322.  
  9323.  
  9324.  
  9325.  
  9326.  
  9327.  
  9328.  
  9329.  
  9330.  
  9331.  
  9332.  
  9333.  
  9334.  
  9335.  
  9336.  
  9337.  
  9338.  
  9339.  
  9340.  
  9341.  
  9342.  
  9343.  
  9344.  
  9345.  
  9346.  
  9347.  
  9348.  
  9349.                                        Commands
  9350.                                        Page 142
  9351.  
  9352.  
  9353.  
  9354.  
  9355.  
  9356.  
  9357.  
  9358.                                   Q - PRO 4 Commands
  9359.  
  9360.  
  9361.      CONCAT
  9362.      ------
  9363.      CONCAT concatenates a set of string or numeric data items into one string
  9364.      data item.
  9365.  
  9366.      Syntax:   CONCAT <string> {TRIMMED} + <string>  {TRIMMED} INTO <string>
  9367.                {TRIMMED}
  9368.  
  9369.      string         A literal string or string data item.
  9370.      TRIMMED        This operator truncates trailing spaces of the string data
  9371.                     item preceding it.
  9372.      INTO           The INTO keyword points to the string data item where the
  9373.                     concatenated will be placed.  It may <BI>not be a literal,
  9374.                     however it may be one of the non-literal string data items
  9375.                     in the command.
  9376.  
  9377.      Examples:
  9378.       
  9379.           CONCAT #S1 TRIMMED + #S2 + #N3 INTO FIELD TRIMMED
  9380.           CONCAT #S1 + ". " + &FIR[1] TRIMMED + " " + &LAS INTO #S2
  9381.  
  9382.      Partial strings may be concatenated as shown below:
  9383.  
  9384.           CONCAT #S1(1,4) + #S2(2,5) INTO #S1
  9385.                This expression concatenates string register one from character
  9386.                position 1 for four characters with string register two from
  9387.                character position 2 for 5 characters into string register 1. 
  9388.                There must be data in the partial string concatenated.  
  9389.  
  9390.  
  9391.  
  9392.  
  9393.  
  9394.  
  9395.  
  9396.  
  9397.  
  9398.  
  9399.  
  9400.  
  9401.  
  9402.  
  9403.  
  9404.  
  9405.  
  9406.  
  9407.  
  9408.  
  9409.                                        Commands
  9410.                                        Page 143
  9411.  
  9412.  
  9413.  
  9414.  
  9415.  
  9416.  
  9417.  
  9418.                                   Q - PRO 4 Commands
  9419.  
  9420.  
  9421.      COPY
  9422.      ----
  9423.      COPY moves data from the screen to a indexed or random file, from the file
  9424.      to the screen, or from a file to another file.  There must be a FID file
  9425.      for any data file used.  COPY moves only fields with identical names in the
  9426.      direction given.
  9427.  
  9428.           Syntax:   COPY <file # or *> <TO <file # or *> {:error}
  9429.  
  9430.      file #         The specific file number to COPY from or to.
  9431.      *              An asterisk (*) always refers to the screen whereas a number
  9432.                     or numeric data item always refers to a file number.
  9433.      Remarks        The programmer may take advantage of this feature with
  9434.                     selective naming of the screen data fields and the file data
  9435.                     fields.
  9436.  
  9437.                     If there is data in the I/O file buffer for the target of
  9438.                     the move which does not have the same name as those in the
  9439.                     record being moved, the old data will remain.  Normally this
  9440.                     is not a problem.  If you want the output buffer to be
  9441.                     pristine, use RCLEAR before the copy.
  9442.  
  9443.      Examples:
  9444.  
  9445.           COPY 1 TO *
  9446.                Moves all file fields from the record for file # 1 to fields with
  9447.                the same name on the screen.
  9448.  
  9449.           COPY 1 TO 2
  9450.                Moves file data fields with the same name from file # 1 to file #
  9451.                2.
  9452.  
  9453.  
  9454.  
  9455.  
  9456.  
  9457.  
  9458.  
  9459.  
  9460.  
  9461.  
  9462.  
  9463.  
  9464.  
  9465.  
  9466.  
  9467.  
  9468.  
  9469.                                        Commands
  9470.                                        Page 144
  9471.  
  9472.  
  9473.  
  9474.  
  9475.  
  9476.  
  9477.  
  9478.                                   Q - PRO 4 Commands
  9479.  
  9480.  
  9481.      CURSOR
  9482.      ------
  9483.      The CURSOR command positions the cursor independently of the displayed form
  9484.      and its fields.
  9485.  
  9486.      Syntax:   CURSOR <row>,<column>
  9487.  
  9488.      row            A value or expression that evaluates from 0 to the number of
  9489.                     rows minus 1 (23 on most CRTs).
  9490.      column         The column is an expression that evaluates from 0 to the
  9491.                     number of columns minus 1 (79 on most CRTs).
  9492.      Remarks        The cursor position is maintained only until control is
  9493.                     returned to the operator.  Then the cursor will move to the
  9494.                     next enterable field.
  9495.  
  9496.      Example:
  9497.  
  9498.           CURSOR 22, #N0+5
  9499.  
  9500.  
  9501.  
  9502.  
  9503.  
  9504.  
  9505.  
  9506.  
  9507.  
  9508.  
  9509.  
  9510.  
  9511.  
  9512.  
  9513.  
  9514.  
  9515.  
  9516.  
  9517.  
  9518.  
  9519.  
  9520.  
  9521.  
  9522.  
  9523.  
  9524.  
  9525.  
  9526.  
  9527.  
  9528.  
  9529.                                        Commands
  9530.                                        Page 145
  9531.  
  9532.  
  9533.  
  9534.  
  9535.  
  9536.  
  9537.  
  9538.                                   Q - PRO 4 Commands
  9539.  
  9540.  
  9541.      CURRENCY
  9542.      --------
  9543.      The CURRENCY command allows the user to change the currency symbol used in
  9544.      the output of the EDIT statement (default is $). $ is still used as the
  9545.      character in the edit picture to denote the placement of the currency
  9546.      symbol.
  9547.  
  9548.      Syntax:   CURRENCY<symbol>
  9549.  
  9550.      symbol         may be any character string or string data item up to five
  9551.                     characters long.  If it is omitted, the system reverts to
  9552.                     using $ as the output currency symbol.
  9553.  
  9554.      Examples:
  9555.  
  9556.           CURRENCY "DM"
  9557.           CURRENCY
  9558.  
  9559.  
  9560.  
  9561.  
  9562.  
  9563.  
  9564.  
  9565.  
  9566.  
  9567.  
  9568.  
  9569.  
  9570.  
  9571.  
  9572.  
  9573.  
  9574.  
  9575.  
  9576.  
  9577.  
  9578.  
  9579.  
  9580.  
  9581.  
  9582.  
  9583.  
  9584.  
  9585.  
  9586.  
  9587.  
  9588.  
  9589.                                        Commands
  9590.                                        Page 146
  9591.  
  9592.  
  9593.  
  9594.  
  9595.  
  9596.  
  9597.  
  9598.                                   Q - PRO 4 Commands
  9599.  
  9600.  
  9601.      DEBUG
  9602.      -----
  9603.      The DEBUG command invokes the runtime debugger for program debugging.  It
  9604.      is usually invoked by a function key during program development.  When
  9605.      invoked, the following debug commands are available:
  9606.             
  9607.      ?    Displays a list of commands on the screen.
  9608.      DI   Allows the user to display a single data item. 
  9609.                For example: 
  9610.                DI #S1 - Displays the contents of string register 1.
  9611.                DI &FIELD[1]- Displays the contents of the file field 
  9612.                    FIELD from file one.
  9613.  
  9614.                (Any data item may be displayed.  Boolean (Bit) registers many
  9615.                not be displayed.)
  9616.      SI   Sets a new value for any data item.
  9617.                For example:
  9618.                SI #S0 = "ABC" - Places the string ABC in #S0.
  9619.                SI #&FIELD[1] = 100 - Moves 100 into the file field.
  9620.      DV   Displays a list of defined memory variables on the screen.
  9621.      DS   Displays a list of screen fields on the screen.
  9622.      DO   Displays a list of open files on the screen.
  9623.      DF   Displays a list of fields for a particular file number on the screen.
  9624.                For example:
  9625.                DF 1 - Displays the fields for file 1.
  9626.      DM   Displays half a screen of memory starting at the given address.
  9627.                For example:
  9628.                DM 39284 - displays memory from 39284 decimal
  9629.                DM H800  - displays memory from 800 hex
  9630.      SM   Sets memory to the value specified at the location specified.
  9631.                For example:
  9632.                SM 100=1,2,3 - Sets memory at decimal 100 to 1, 
  9633.                    at decimal 101 to 2, and at decimal 102 to 3.
  9634.                SM H100=H4F - Sets memory at Hex 100 to Hex 4F.
  9635.      DB   Display the settings of the Boolean (BIT) registers.
  9636.      SB   Set a Boolean register.
  9637.                For example:
  9638.                SB 1 - Sets register 1
  9639.  
  9640.      RB   Resets a Boolean register.
  9641.                For example:
  9642.                RB 1 - Resets register 1
  9643.      EP   Enables the printer.  Any data printed on the screen will be echoed to
  9644.           the printer.
  9645.      DP   Disables the printer.  Data printed to the screen will go to the
  9646.           screen only.
  9647.  
  9648.  
  9649.                                        Commands
  9650.                                        Page 147
  9651.  
  9652.  
  9653.  
  9654.  
  9655.  
  9656.  
  9657.  
  9658.                                   Q - PRO 4 Commands
  9659.  
  9660.  
  9661.      ET   Enables trace.  
  9662.      DT   Disables trace.
  9663.      MA   Display memory available for files and variables.
  9664.      EX   Exit Debug and return to the application program.
  9665.  
  9666.      Remark    On 16 bit systems, DM and SM are used in conjunction with the
  9667.                command DEFSEG. 
  9668.  
  9669.      Example:
  9670.  
  9671.      PROC KEY9
  9672.           DEBUG          
  9673.           END
  9674.  
  9675.  
  9676.  
  9677.  
  9678.  
  9679.  
  9680.  
  9681.  
  9682.  
  9683.  
  9684.  
  9685.  
  9686.  
  9687.  
  9688.  
  9689.  
  9690.  
  9691.  
  9692.  
  9693.  
  9694.  
  9695.  
  9696.  
  9697.  
  9698.  
  9699.  
  9700.  
  9701.  
  9702.  
  9703.  
  9704.  
  9705.  
  9706.  
  9707.  
  9708.  
  9709.                                        Commands
  9710.                                        Page 148
  9711.  
  9712.  
  9713.  
  9714.  
  9715.  
  9716.  
  9717.  
  9718.                                   Q - PRO 4 Commands
  9719.  
  9720.  
  9721.      DEFSEG
  9722.      DEFSEG is used on 16 bit versions in conjunction with PEEK's, POKE's and
  9723.      DEBUG.  Since the peek and poke commands only allow access to the 64K
  9724.      runtime data area, DEFSEG is needed to set a new data segment.
  9725.  
  9726.      Syntax:   DEFSEG <expression>
  9727.  
  9728.      expression          must evaluate to a valid integer segment
  9729.  
  9730.      Example:
  9731.           DEFSEG 80
  9732.           PEEK 1,1,prnscn_flg
  9733.  
  9734.                Looks at the 'print screen in progress' flag on an IBM PC.
  9735.  
  9736.  
  9737.  
  9738.  
  9739.  
  9740.  
  9741.  
  9742.  
  9743.  
  9744.  
  9745.  
  9746.  
  9747.  
  9748.  
  9749.  
  9750.  
  9751.  
  9752.  
  9753.  
  9754.  
  9755.  
  9756.  
  9757.  
  9758.  
  9759.  
  9760.  
  9761.  
  9762.  
  9763.  
  9764.  
  9765.  
  9766.  
  9767.  
  9768.  
  9769.                                        Commands
  9770.                                        Page 149
  9771.  
  9772.  
  9773.  
  9774.  
  9775.  
  9776.  
  9777.  
  9778.                                   Q - PRO 4 Commands
  9779.  
  9780.  
  9781.      DIV
  9782.      ---
  9783.      DIV divides one numeric data item by another and optionally places the
  9784.      result in a third.
  9785.  
  9786.      Syntax:   DIV <data item 1> INTO <data item 2> {GIVING <data item 3>}
  9787.  
  9788.      data item 1    A valid numeric data item which is the divisor.
  9789.      INTO           This verb points to the dividend.  It must be a valid
  9790.                     numeric data item.  If the answer or quotient is to be
  9791.                     stored here, it must <BI>not be a literal number.
  9792.      GIVING         Points the numeric data item where the result or quotient is
  9793.                     to be placed.
  9794.  
  9795.                     If the GIVING clause is not present, then the result is
  9796.                     stored in data item 2.
  9797.      Remarks        The keyword INTO may be replaced by a comma (,).
  9798.  
  9799.                     Refer to the Data Items section for legal types of data
  9800.                     items which may be used.
  9801.  
  9802.      Examples:
  9803.           DIV 2 INTO WHOLE GIVING HALF
  9804.           DIV #N0,#N3
  9805.           DIV COUNT,SUM GIVING AVG
  9806.  
  9807.  
  9808.  
  9809.  
  9810.  
  9811.  
  9812.  
  9813.  
  9814.  
  9815.  
  9816.  
  9817.  
  9818.  
  9819.  
  9820.  
  9821.  
  9822.  
  9823.  
  9824.  
  9825.  
  9826.  
  9827.  
  9828.  
  9829.                                        Commands
  9830.                                        Page 150
  9831.  
  9832.  
  9833.  
  9834.  
  9835.  
  9836.  
  9837.  
  9838.                                   Q - PRO 4 Commands
  9839.  
  9840.  
  9841.      EDIT
  9842.      ----
  9843.      EDIT gives the capability to format numeric data items according to a
  9844.      picture of the desired result.  This picture uses descriptor characters to
  9845.      control leading zeros, decimal point placement, etc.
  9846.  
  9847.      Syntax: EDIT <data1> USING <picture> INTO  <data2> {:<B>error}
  9848.  
  9849.      data1          Must be a numeric expression.
  9850.      picture        The format picture is a string consisting of a meaningful
  9851.                     combination of the following characters:
  9852.      "*"            Specifies that leading zero fill is to be replaced by
  9853.                     leading '*' characters instead.
  9854.  
  9855.      $              Specifies that the leftmost digit will be preceded by a
  9856.                     dollar sign.
  9857.  
  9858.      -              May be placed in leading or trailing position. Specifies
  9859.                     that if the number is negative, a sign will be inserted in
  9860.                     the designated position.
  9861.  
  9862.      +              May be placed in leading or trailing position. Specifies
  9863.                     that the appropriate sign (+ or -) will be inserted in the
  9864.                     designated position.
  9865.  
  9866.      Z              Specifies that a digit is to be placed in this position in
  9867.                     the formatted output.  Leading zeroes are suppressed.
  9868.  
  9869.      9              Specifies that a digit is to be placed in this position. 
  9870.                     Leading zeros are not suppressed.
  9871.  
  9872.      .              Specifies that a decimal point is to be placed in this
  9873.                     position.
  9874.  
  9875.      ,              Specifies that a comma will be inserted in the output area
  9876.                     if the first non-zero digit occurs to the right of the
  9877.                     comma.
  9878.       
  9879.      data2          Data item 2 may be a string field or register.  If no
  9880.                     numerically invalid characters have been introduced as a
  9881.                     result of the editing process, data item 2 may also be
  9882.                     numeric.  Refer to the UNEDIT command for removing
  9883.                     numerically invalid characters.
  9884.  
  9885.      Examples:
  9886.           EDIT 12.3 USING "9999.9" INTO #S0  =  0012.3
  9887.  
  9888.  
  9889.                                        Commands
  9890.                                        Page 151
  9891.  
  9892.  
  9893.  
  9894.  
  9895.  
  9896.  
  9897.  
  9898.                                   Q - PRO 4 Commands
  9899.  
  9900.  
  9901.           EDIT 234.98 USING "*$*ZZZ,*ZZZ.99" INTO #S1 = ***$234.98
  9902.           EDIT 1234.98 USING "*$*ZZZ,*ZZZ.99" INTO #S1 = *$1,234.98
  9903.           EDIT $FIELD[#N0] USING "999999.99" INTO $FIELD[#N0]
  9904.  
  9905.  
  9906.  
  9907.      ELSE - ELSE IF
  9908.      --------------
  9909.      An ELSE or ELSE IF is a part of the BEGIN construct and is always
  9910.      associated with a BEGIN IF.  A BEGIN may have any number of IF or ELSE IF
  9911.      statements associated with it.  See BEGIN.
  9912.  
  9913.      Examples:
  9914.      BEGIN IF #N1 GT 100
  9915.                SUB 1 FROM #N2   
  9916.           ELSE IF #N1 LT 100
  9917.                ADD 1 TO #N2
  9918.           ELSE
  9919.                MOVE 0 TO #N2
  9920.      ENDBEGIN
  9921.  
  9922.  
  9923.  
  9924.  
  9925.  
  9926.  
  9927.  
  9928.  
  9929.  
  9930.  
  9931.  
  9932.  
  9933.  
  9934.  
  9935.  
  9936.  
  9937.  
  9938.  
  9939.  
  9940.  
  9941.  
  9942.  
  9943.  
  9944.  
  9945.  
  9946.  
  9947.  
  9948.  
  9949.                                        Commands
  9950.                                        Page 152
  9951.  
  9952.  
  9953.  
  9954.  
  9955.  
  9956.  
  9957.  
  9958.                                   Q - PRO 4 Commands
  9959.  
  9960.  
  9961.      END
  9962.      ---
  9963.      END marks the end of a procedure or table.  It should be treated as any
  9964.      other executable statement, as the examples will show.  When the END
  9965.      statement in a procedure is encountered, control is turned over to the
  9966.      operator in the next enterable field for data entry.
  9967.  
  9968.      Syntax:        END
  9969.  
  9970.      Examples:
  9971.           PROC NOTHING
  9972.                END
  9973.  
  9974.           PROC VERIFY0
  9975.                IF FLD1 EQ 0 THEN END
  9976.                ERROR "SHOULD HAVE BEEN 0"
  9977.                END
  9978.  
  9979.           TABLE STATES
  9980.           "PA",     "Pennsylvania"
  9981.           "TX",     "Texas"
  9982.           "NJ",     "New Jersey"
  9983.           END
  9984.  
  9985.  
  9986.  
  9987.  
  9988.  
  9989.  
  9990.  
  9991.  
  9992.  
  9993.  
  9994.  
  9995.  
  9996.  
  9997.  
  9998.  
  9999.  
  10000.  
  10001.  
  10002.  
  10003.  
  10004.  
  10005.  
  10006.  
  10007.  
  10008.  
  10009.                                        Commands
  10010.                                        Page 153
  10011.  
  10012.  
  10013.  
  10014.  
  10015.  
  10016.  
  10017.  
  10018.                                   Q - PRO 4 Commands
  10019.  
  10020.  
  10021.      ENDBEGIN
  10022.      --------
  10023.      ENDBEGIN denotes the end of the structured construct.  It may have any of
  10024.      the following modifiers:
  10025.  
  10026.      Syntax:   ENDBEGIN
  10027.           ENDBEGIN WHILE
  10028.           ENDBEGIN UNTIL
  10029.  
  10030.  
  10031.  
  10032.  
  10033.  
  10034.  
  10035.  
  10036.  
  10037.  
  10038.  
  10039.  
  10040.  
  10041.  
  10042.  
  10043.  
  10044.  
  10045.  
  10046.  
  10047.  
  10048.  
  10049.  
  10050.  
  10051.  
  10052.  
  10053.  
  10054.  
  10055.  
  10056.  
  10057.  
  10058.  
  10059.  
  10060.  
  10061.  
  10062.  
  10063.  
  10064.  
  10065.  
  10066.  
  10067.  
  10068.  
  10069.                                        Commands
  10070.                                        Page 154
  10071.  
  10072.  
  10073.  
  10074.  
  10075.  
  10076.  
  10077.  
  10078.                                   Q - PRO 4 Commands
  10079.  
  10080.  
  10081.      ENDFOR
  10082.      ------
  10083.      ENDFOR terminates a FOR loop.  When the ENDFOR statement is executed, the
  10084.      loop variable is incremented (or decremented, if the loop increment is
  10085.      negative) and then tested for exceeding the ending value of the loop.
  10086.  
  10087.      Syntax:   ENDFOR <loop variable>
  10088.  
  10089.      loop variable       The same loop variable that began the FOR loop.
  10090.  
  10091.      Remarks             If the ending value is not exceeded, then control
  10092.                          transfers back to the start of the loop (the next
  10093.                          statement after the corresponding FOR statement).  Note
  10094.                          that the program may exit FOR-ENDFOR loops prematurely
  10095.                          via GOTO statements.  CALL-RETURN and FOR-ENDFOR
  10096.                          management takes care of any aborted loops.
  10097.  
  10098.      Examples:
  10099.      FOR #N0 = 1 TO 100
  10100.      ENDFOR #N0
  10101.  
  10102.      FOR COUNTER = 1 TO 100
  10103.      ENDFOR COUNTER
  10104.  
  10105.  
  10106.  
  10107.  
  10108.  
  10109.  
  10110.  
  10111.  
  10112.  
  10113.  
  10114.  
  10115.  
  10116.  
  10117.  
  10118.  
  10119.  
  10120.  
  10121.  
  10122.  
  10123.  
  10124.  
  10125.  
  10126.  
  10127.  
  10128.  
  10129.                                        Commands
  10130.                                        Page 155
  10131.  
  10132.  
  10133.  
  10134.  
  10135.  
  10136.  
  10137.  
  10138.                                   Q - PRO 4 Commands
  10139.  
  10140.  
  10141.      ERASE
  10142.      -----
  10143.      ERASE removes a file from a disk.
  10144.  
  10145.      Syntax:   ERASE <file name> {:<error}
  10146.  
  10147.      filename       The file name may be any string literal, field, or register.
  10148.  
  10149.      Examples:
  10150.           ERASE "TEMP.$$$" :10
  10151.           ERASE #S0
  10152.           ERASE "B:OLDFILE.DAT"
  10153.  
  10154.  
  10155.  
  10156.  
  10157.  
  10158.  
  10159.  
  10160.  
  10161.  
  10162.  
  10163.  
  10164.  
  10165.  
  10166.  
  10167.  
  10168.  
  10169.  
  10170.  
  10171.  
  10172.  
  10173.  
  10174.  
  10175.  
  10176.  
  10177.  
  10178.  
  10179.  
  10180.  
  10181.  
  10182.  
  10183.  
  10184.  
  10185.  
  10186.  
  10187.  
  10188.  
  10189.                                        Commands
  10190.                                        Page 156
  10191.  
  10192.  
  10193.  
  10194.  
  10195.  
  10196.  
  10197.  
  10198.                                   Q - PRO 4 Commands
  10199.  
  10200.  
  10201.      ERROR
  10202.      -----
  10203.      The ERROR command displays an error message on the last line of the screen
  10204.      in a format compatible with system-generated error messages (for invalid
  10205.      keystrokes, etc.).
  10206.  
  10207.      Syntax:   ERROR <message>
  10208.  
  10209.      message        The message may be any data item.
  10210.  
  10211.  
  10212.      Examples:
  10213.           ERROR "FILE NOT FOUND"
  10214.           ERROR #S1
  10215.           ERROR "UNAUTHORIZED USER"
  10216.  
  10217.  
  10218.  
  10219.  
  10220.  
  10221.  
  10222.  
  10223.  
  10224.  
  10225.  
  10226.  
  10227.  
  10228.  
  10229.  
  10230.  
  10231.  
  10232.  
  10233.  
  10234.  
  10235.  
  10236.  
  10237.  
  10238.  
  10239.  
  10240.  
  10241.  
  10242.  
  10243.  
  10244.  
  10245.  
  10246.  
  10247.  
  10248.  
  10249.                                        Commands
  10250.                                        Page 157
  10251.  
  10252.  
  10253.  
  10254.  
  10255.  
  10256.  
  10257.  
  10258.                                   Q - PRO 4 Commands
  10259.  
  10260.  
  10261.      ERRTRAP
  10262.      -------
  10263.      The ERRTRAP command sets a label as an error branch, or clears such a label
  10264.      if an error branch was previously set.  (Refer to Programmer's Reference
  10265.      Manual for sample coding and a complete discussion.)
  10266.  
  10267.      Syntax:   ERRTRAP <label>
  10268.  
  10269.      label          Any label, numeric or alphanumeric.
  10270.      Remarks        If the label is not given, then any previous ERRTRAP set is
  10271.                     cleared.
  10272.  
  10273.      Examples:
  10274.           ERRTRAP 100
  10275.           ERRTRAP
  10276.  
  10277.  
  10278.  
  10279.  
  10280.  
  10281.  
  10282.  
  10283.  
  10284.  
  10285.  
  10286.  
  10287.  
  10288.  
  10289.  
  10290.  
  10291.  
  10292.  
  10293.  
  10294.  
  10295.  
  10296.  
  10297.  
  10298.  
  10299.  
  10300.  
  10301.  
  10302.  
  10303.  
  10304.  
  10305.  
  10306.  
  10307.  
  10308.  
  10309.                                        Commands
  10310.                                        Page 158
  10311.  
  10312.  
  10313.  
  10314.  
  10315.  
  10316.  
  10317.  
  10318.                                   Q - PRO 4 Commands
  10319.  
  10320.  
  10321.      EXEC
  10322.      ----
  10323.      EXEC causes the execution of a machine code routine that has been loaded
  10324.      into memory.
  10325.  
  10326.      Syntax:   EXEC <address>, <input string> {<,output string>} {<:<BI>error}
  10327.  
  10328.      address        The memory address at which to begin execution
  10329.      input string   A required string of data to be passed to the assembly
  10330.                     language routine.
  10331.      output string  An optional string for or returned data
  10332.  
  10333.      Remarks        The use of this and other machine code interface commands
  10334.                     presupposes that the programmer knows what he/she/it is
  10335.                     doing, since a call to an invalid address can clearly blow
  10336.                     the system away.  
  10337.  
  10338.  
  10339.  
  10340.  
  10341.  
  10342.  
  10343.  
  10344.  
  10345.  
  10346.  
  10347.  
  10348.  
  10349.  
  10350.  
  10351.  
  10352.  
  10353.  
  10354.  
  10355.  
  10356.  
  10357.  
  10358.  
  10359.  
  10360.  
  10361.  
  10362.  
  10363.  
  10364.  
  10365.  
  10366.  
  10367.  
  10368.  
  10369.                                        Commands
  10370.                                        Page 159
  10371.  
  10372.  
  10373.  
  10374.  
  10375.  
  10376.  
  10377.  
  10378.                                   Q - PRO 4 Commands
  10379.  
  10380.  
  10381.      FCOPY
  10382.      ------
  10383.      FCOPY copies a file.  No wild cards are allowed.
  10384.  
  10385.      Syntax:   FCOPY <filename1> TO <filename2> {<:error}
  10386.  
  10387.      filename1      The name of the file to be copied expressed as a literal, or
  10388.                     string data item.
  10389.      TO             The pointer to the file to be copied to.  A comma may be
  10390.                     substituted for the TO. 
  10391.      filename2      The name of the file to be copied to expressed as a literal. 
  10392.  
  10393.      Remarks        No wild cards are allowed.  If the destination file exists,
  10394.                     it will be overwritten.  
  10395.        
  10396.  
  10397.  
  10398.  
  10399.  
  10400.  
  10401.  
  10402.  
  10403.  
  10404.  
  10405.  
  10406.  
  10407.  
  10408.  
  10409.  
  10410.  
  10411.  
  10412.  
  10413.  
  10414.  
  10415.  
  10416.  
  10417.  
  10418.  
  10419.  
  10420.  
  10421.  
  10422.  
  10423.  
  10424.  
  10425.  
  10426.  
  10427.  
  10428.  
  10429.                                        Commands
  10430.                                        Page 160
  10431.  
  10432.  
  10433.  
  10434.  
  10435.  
  10436.  
  10437.  
  10438.                                   Q - PRO 4 Commands
  10439.  
  10440.  
  10441.      FILETYPE
  10442.      --------
  10443.      FILETYPE returns information about open files.
  10444.  
  10445.      Syntax:   FILETYPE<fileno>
  10446.  
  10447.      fileno         The file number as expressed as a literal or numeric data
  10448.                     item.
  10449.      Remarks        FILETYPE returns the information as shown below:
  10450.  
  10451.                Indexed Files            Random Files
  10452.                #N0 - File type               File type
  10453.                #N1 - Number of keys          Record length
  10454.                #N2 - Current Key
  10455.                #N3 - Record length
  10456.  
  10457.  
  10458.      Another use of FILETYPE is to determine if a file is open or closed.  If
  10459.      the error path is taken, the file is not open.
  10460.  
  10461.      Examples:
  10462.  
  10463.           FILETYPE 1
  10464.           FILETYPE #N6 :100
  10465.  
  10466.           FILETYPE 1
  10467.           KEY 1 USING 2
  10468.           POSN 1 TO KEY RELATIVE
  10469.           READ 1
  10470.           COPY 1 TO *
  10471.           KEY 1 USING #N2
  10472.  
  10473.                This code fragment illustrates changing keys and reverting to the
  10474.                original key which will be in #N2.       
  10475.  
  10476.  
  10477.  
  10478.  
  10479.  
  10480.  
  10481.  
  10482.  
  10483.  
  10484.  
  10485.  
  10486.  
  10487.  
  10488.  
  10489.                                        Commands
  10490.                                        Page 161
  10491.  
  10492.  
  10493.  
  10494.  
  10495.  
  10496.  
  10497.  
  10498.                                   Q - PRO 4 Commands
  10499.  
  10500.  
  10501.      FILL
  10502.      ----
  10503.      The FILL command causes unentered field fill in unlocked fields to be
  10504.      changed from the default character (space) to any character desired.
  10505.  
  10506.      Syntax:   FILL <string data item>
  10507.  
  10508.      string data item    A literal or string data item.
  10509.  
  10510.      Remarks             The FILL command affects the screen display only.  The
  10511.                          data, as seen by the program, is unchanged.  The value
  10512.                          for FILL will remain in effect across chains.  Normally
  10513.                          this command is used in PROC LOAD.
  10514.  
  10515.      Examples:
  10516.           FILL "." 
  10517.           FILL #S8
  10518.  
  10519.  
  10520.  
  10521.  
  10522.  
  10523.  
  10524.  
  10525.  
  10526.  
  10527.  
  10528.  
  10529.  
  10530.  
  10531.  
  10532.  
  10533.  
  10534.  
  10535.  
  10536.  
  10537.  
  10538.  
  10539.  
  10540.  
  10541.  
  10542.  
  10543.  
  10544.  
  10545.  
  10546.  
  10547.  
  10548.  
  10549.                                        Commands
  10550.                                        Page 162
  10551.  
  10552.  
  10553.  
  10554.  
  10555.  
  10556.  
  10557.  
  10558.                                   Q - PRO 4 Commands
  10559.  
  10560.  
  10561.      FOR
  10562.      ---
  10563.      FOR is the beginning of a control loop which increments or decrements a
  10564.      field, numeric variable or numeric register from a given starting value to
  10565.      a given ending value, with any given increment.
  10566.  
  10567.      Syntax:   FOR <loop variable> = <start> TO <end> {BY <increment>}
  10568.  
  10569.      loop variable  Any numeric register, numeric variable, numeric screen data
  10570.                     field, or numeric file data field.
  10571.      start          Initial value of the loop variable.  It may be any valid
  10572.                     numeric data item.
  10573.      TO             Range pointer.
  10574.      end            The ending value of the loop variable.  It may be any valid
  10575.                     numeric data item.
  10576.      BY             Points to the increment.
  10577.      increment      Value to add to the initial value on each iteration of the
  10578.                     loop.  It must be a valid numeric data item and may be
  10579.                     negative.
  10580.      Remarks        If the BY phrase is not given, then 1 is the assumed
  10581.                     increment.  The increment may be positive (in which case the
  10582.                     loop variable increases in value from start to end), or
  10583.                     negative (in which case the loop variable decreases in value
  10584.                     from start to end). The loop variable must be a register or
  10585.                     field; the start, end, and increment values may be any valid
  10586.                     numeric expression.  FOR loops may be nested; however, the
  10587.                     total of nested CALLs and FORs may not exceed 20.
  10588.  
  10589.      FOR loops are terminated by an ENDFOR statement, which must contain the
  10590.      name of the FOR loop variable whose loop is being terminated.
  10591.  
  10592.      Examples:
  10593.      FOR #N0 = 1 TO 20 BY 5
  10594.           .
  10595.           .
  10596.      ENDFOR #N0
  10597.  
  10598.  
  10599.      FOR COUNT = (#N0+1)}5 TO -10 BY INCR*3
  10600.           .
  10601.           .
  10602.      ENDFOR COUNT
  10603.  
  10604.  
  10605.  
  10606.  
  10607.  
  10608.  
  10609.                                        Commands
  10610.                                        Page 163
  10611.  
  10612.  
  10613.  
  10614.  
  10615.  
  10616.  
  10617.  
  10618.                                   Q - PRO 4 Commands
  10619.  
  10620.  
  10621.      FORMLOAD
  10622.      --------
  10623.      FORMLOAD sets an internal flag, so that on a future exit to the operating
  10624.      system command level for any reason, the format builder program (FB) is
  10625.      executed and the current application program is loaded ready for editing. 
  10626.      This provides a convenient feature during debugging when transitions
  10627.      between the format builder module and the runtime module are frequent.  It
  10628.      is normally the first statement in PROC LOAD.
  10629.  
  10630.      Syntax:   FORMLOAD
  10631.  
  10632.      Remarks        This flag will stay on until reset by NOFORMLOAD, even
  10633.                     through CHAIN operations.
  10634.  
  10635.  
  10636.  
  10637.  
  10638.  
  10639.  
  10640.  
  10641.  
  10642.  
  10643.  
  10644.  
  10645.  
  10646.  
  10647.  
  10648.  
  10649.  
  10650.  
  10651.  
  10652.  
  10653.  
  10654.  
  10655.  
  10656.  
  10657.  
  10658.  
  10659.  
  10660.  
  10661.  
  10662.  
  10663.  
  10664.  
  10665.  
  10666.  
  10667.  
  10668.  
  10669.                                        Commands
  10670.                                        Page 164
  10671.  
  10672.  
  10673.  
  10674.  
  10675.  
  10676.  
  10677.  
  10678.                                   Q - PRO 4 Commands
  10679.  
  10680.  
  10681.      FREE
  10682.      ----
  10683.      FREE deletes a key from an indexed file and effectively deletes the record.
  10684.  
  10685.      Syntax:   FREE <file number> {:<error>}
  10686.  
  10687.      file number         The file number expressed as a valid numeric data item.
  10688.      error               Label to branch to if the FREE fails.
  10689.      Remarks             Deleted records will remain in the file with a deleted
  10690.                          record flag until a new record is added.
  10691.  
  10692.                          The key must have been previously accessed via POSN and
  10693.                          READ statements.
  10694.  
  10695.      Example:
  10696.           POSN 1 TO #S0
  10697.           READ 1
  10698.           FREE 1
  10699.  
  10700.  
  10701.  
  10702.  
  10703.  
  10704.  
  10705.  
  10706.  
  10707.  
  10708.  
  10709.  
  10710.  
  10711.  
  10712.  
  10713.  
  10714.  
  10715.  
  10716.  
  10717.  
  10718.  
  10719.  
  10720.  
  10721.  
  10722.  
  10723.  
  10724.  
  10725.  
  10726.  
  10727.  
  10728.  
  10729.                                        Commands
  10730.                                        Page 165
  10731.  
  10732.  
  10733.  
  10734.  
  10735.  
  10736.  
  10737.  
  10738.                                   Q - PRO 4 Commands
  10739.  
  10740.  
  10741.      FSEAR
  10742.      -----
  10743.      FSEAR is used to search a data file on a record-by-record basis for the
  10744.      satisfaction of any logical condition.
  10745.  
  10746.      Syntax 1: FSEAR <file #> {NOADV} AT <condition> {:error}
  10747.  
  10748.      file #         The file number of the file to be searched.
  10749.      NOADV          If NOADV , the file is left positioned at the record which
  10750.                     it was loaded.
  10751.      AT             Points to the search condition.
  10752.      Condition      Any condition which is valid in an IF statement is valid for
  10753.                     FSEAR.
  10754.      Remarks        The file is searched, starting at the current position in
  10755.                     the file.  Searching will stop when either the condition is
  10756.                     true, or end of file.  If the condition is found, the record
  10757.                     for which the condition was true will be loaded, and the
  10758.                     file left positioned at the next record in the file.
  10759.  
  10760.                     Searching begins at the current file position.  For indexed
  10761.                     files, the search sequence is the current file key. If no
  10762.                     match is found, then an end-of-file error is caused.
  10763.  
  10764.      Examples:
  10765.           FSEAR 1 NOADV AT &CUSTNO[1] > 100  :99
  10766.           FSEAR 3 AT &TYPE[3] = TYPE AND &INV[3] GEQ &INV[2] :100
  10767.  
  10768.  
  10769.      Syntax 2:      FSEAR <file #> {NOADV} USING <string data item>:error
  10770.  
  10771.      NOADV               Do not advance the file after a match.
  10772.      USING               The keyword to denote a dynamic search argument.
  10773.      string data item    A string register, string field, or string variable
  10774.                          that contains the search condition.
  10775.  
  10776.      Examples:
  10777.           A file is to be searched for a match on a last name input by a user
  10778.           from the screen.  The screen data field name is NAME and the file data
  10779.           field name is LAST.  The code looks like this:
  10780.  
  10781.           MOVE "NAME = &LAST[1]" TO #S0
  10782.           FSEAR 1 USING #S0:100
  10783.  
  10784.           The file is searched sequentially until the condition NAME = &LAST[1]
  10785.           is met.  Then the next sequential instruction will be executed.  On no
  10786.           match, the next record will be read and tested; if end of file then
  10787.  
  10788.  
  10789.                                        Commands
  10790.                                        Page 166
  10791.  
  10792.  
  10793.  
  10794.  
  10795.  
  10796.  
  10797.  
  10798.                                   Q - PRO 4 Commands
  10799.  
  10800.  
  10801.           control will pass to line number 100.  Remember, when using this
  10802.           command, strings must match exactly for a match and the FSEAR command
  10803.           will begin searching at the current file position. 
  10804.  
  10805.  
  10806.  
  10807.  
  10808.  
  10809.  
  10810.  
  10811.  
  10812.  
  10813.  
  10814.  
  10815.  
  10816.  
  10817.  
  10818.  
  10819.  
  10820.  
  10821.  
  10822.  
  10823.  
  10824.  
  10825.  
  10826.  
  10827.  
  10828.  
  10829.  
  10830.  
  10831.  
  10832.  
  10833.  
  10834.  
  10835.  
  10836.  
  10837.  
  10838.  
  10839.  
  10840.  
  10841.  
  10842.  
  10843.  
  10844.  
  10845.  
  10846.  
  10847.  
  10848.  
  10849.                                        Commands
  10850.                                        Page 167
  10851.  
  10852.  
  10853.  
  10854.  
  10855.  
  10856.  
  10857.  
  10858.                                   Q - PRO 4 Commands
  10859.  
  10860.  
  10861.      GET
  10862.      ---
  10863.      GET moves a data field from a file buffer to a register or screen field.
  10864.  
  10865.      Syntax:   GET <data name or *> FROM <file number> <B>FOR <length> {TRIMMED}
  10866.                {:error}
  10867.  
  10868.      data name or *      This may be a register or field.
  10869.  
  10870.                          If the data name is an asterisk (*), then all
  10871.                          enterable, unlocked fields on the screen are filled
  10872.                          from the current position in the file buffer, in the
  10873.                          order they appear on the screen, starting with the
  10874.                          first unprotected field on the screen.
  10875.      file number         The file number must represent an open file.
  10876.      TRIMMED             If the keyword TRIMMED is present, then trailing spaces
  10877.                          are removed from the data as it is transferred from the
  10878.                          file buffer to the data item.  This is invalid in the
  10879.                          GET * usage of the statement.
  10880.      Remarks             It is not used when the movement from file buffer is
  10881.                          done with FID names or the COPY command.  With FID
  10882.                          names use the MOVE command.
  10883.  
  10884.                          Note that for sequential files, the normal sequence of
  10885.                          statements is to issue GET's until the end of a record,
  10886.                          and then issue a READ to bypass the carriage
  10887.                          return/line feed sequence which marks the end of a
  10888.                          sequential record. For random and indexed files issue a
  10889.                          READ first, followed by GETs to extract the data from
  10890.                          the file buffer.  Each GET issued advances the file
  10891.                          buffer pointer by the length of the GET.
  10892.  
  10893.      Examples:
  10894.           GET #N0 FROM 1 FOR 5 :4444
  10895.           GET CUSTNAME FROM 12 FOR 60 TRIMMED
  10896.           GET * FROM 1
  10897.  
  10898.  
  10899.  
  10900.  
  10901.  
  10902.  
  10903.  
  10904.  
  10905.  
  10906.  
  10907.  
  10908.  
  10909.                                        Commands
  10910.                                        Page 168
  10911.  
  10912.  
  10913.  
  10914.  
  10915.  
  10916.  
  10917.  
  10918.                                   Q - PRO 4 Commands
  10919.  
  10920.  
  10921.      GETDATE
  10922.      -------
  10923.      GETDATE loads an alphanumeric data item with the current system date. 
  10924.      (Refer also to SETDATE.)
  10925.  
  10926.      Syntax:   GETDATE <string data item>
  10927.  
  10928.      string data item    Any valid string data item except a literal.
  10929.      Remarks             The format of the retrieved date is MM/DD/YYYY
  10930.                          hh:mm:ss, where:
  10931.                          MM = MONTH          hh = hours
  10932.                          DD = DAY            mm = minutes
  10933.                          YYYY = YEAR         ss = seconds
  10934.  
  10935.      Example:
  10936.           GETDATE #S0
  10937.  
  10938.  
  10939.  
  10940.  
  10941.  
  10942.  
  10943.  
  10944.  
  10945.  
  10946.  
  10947.  
  10948.  
  10949.  
  10950.  
  10951.  
  10952.  
  10953.  
  10954.  
  10955.  
  10956.  
  10957.  
  10958.  
  10959.  
  10960.  
  10961.  
  10962.  
  10963.  
  10964.  
  10965.  
  10966.  
  10967.  
  10968.  
  10969.                                        Commands
  10970.                                        Page 169
  10971.  
  10972.  
  10973.  
  10974.  
  10975.  
  10976.  
  10977.  
  10978.                                   Q - PRO 4 Commands
  10979.  
  10980.  
  10981.      GOTO
  10982.      ----
  10983.      GOTO alters the sequential flow of command execution by forcing an
  10984.      immediate jump to the program location marked by a numeric or alphanumeric
  10985.      label.
  10986.  
  10987.      Syntax:   GOTO <label or line number>
  10988.  
  10989.      label or line number     A valid label or line number.
  10990.      Remarks                  Instead of an actual label being given, the
  10991.                               program may instead give a table name and index. 
  10992.                               Here, the destination of the GOTO is chosen as the
  10993.                               corresponding element of the table.  The table
  10994.                               used must consist of a series of 1-item lines,
  10995.                               each item being a label.  The first item in the
  10996.                               table is zero (0).  See also discussion in
  10997.                               Programmer's Reference Manual.
  10998.  
  10999.      Examples:
  11000.           GOTO 100
  11001.           GOTO DEM_LABEL
  11002.           GOTO LABTBL[#N0]
  11003.  
  11004.  
  11005.  
  11006.  
  11007.  
  11008.  
  11009.  
  11010.  
  11011.  
  11012.  
  11013.  
  11014.  
  11015.  
  11016.  
  11017.  
  11018.  
  11019.  
  11020.  
  11021.  
  11022.  
  11023.  
  11024.  
  11025.  
  11026.  
  11027.  
  11028.  
  11029.                                        Commands
  11030.                                        Page 170
  11031.  
  11032.  
  11033.  
  11034.  
  11035.  
  11036.  
  11037.  
  11038.                                   Q - PRO 4 Commands
  11039.  
  11040.  
  11041.      HELP
  11042.      ----
  11043.      The HELP command allows an unlimited number of help screens to be displayed
  11044.      by an application.
  11045.  
  11046.      Help screens are normal QNE format files built by FB, without enterable
  11047.      fields or PROCs (fields and PROCs will be ignored in help screens in any
  11048.      case).
  11049.       
  11050.      Syntax:   HELP <screen> {,<screen>,<screen>. . .}{:error}
  11051.  
  11052.      screen         The name of the help screen may be a literal in quotes, or a
  11053.                     valid string data item.
  11054.      Remarks        When the first help screen is displayed, the operator may
  11055.                     either press ESCAPE (in which case no more screens are
  11056.                     displayed), or any other key (in which case the next screen
  11057.                     is displayed).  After the last screen, any key will restore
  11058.                     the data entry screen in its original form.  The error
  11059.                     branch will be taken if a help screen cannot be found.
  11060.  
  11061.      Examples:
  11062.           HELP "B:HELP1","B:HELP2",#S1:123
  11063.           IF #F EQ 10 HELP "B:FID.HLP"
  11064.  
  11065.  
  11066.  
  11067.  
  11068.  
  11069.  
  11070.  
  11071.  
  11072.  
  11073.  
  11074.  
  11075.  
  11076.  
  11077.  
  11078.  
  11079.  
  11080.  
  11081.  
  11082.  
  11083.  
  11084.  
  11085.  
  11086.  
  11087.  
  11088.  
  11089.                                        Commands
  11090.                                        Page 171
  11091.  
  11092.  
  11093.  
  11094.  
  11095.  
  11096.  
  11097.  
  11098.                                   Q - PRO 4 Commands
  11099.  
  11100.  
  11101.      HOFF
  11102.      ----
  11103.  
  11104.      Syntax:   HOFF
  11105.  
  11106.      For the use of HOFF, see HON below.
  11107.  
  11108.  
  11109.  
  11110.  
  11111.  
  11112.  
  11113.  
  11114.  
  11115.  
  11116.  
  11117.  
  11118.  
  11119.  
  11120.  
  11121.  
  11122.  
  11123.  
  11124.  
  11125.  
  11126.  
  11127.  
  11128.  
  11129.  
  11130.  
  11131.  
  11132.  
  11133.  
  11134.  
  11135.  
  11136.  
  11137.  
  11138.  
  11139.  
  11140.  
  11141.  
  11142.  
  11143.  
  11144.  
  11145.  
  11146.  
  11147.  
  11148.  
  11149.                                        Commands
  11150.                                        Page 172
  11151.  
  11152.  
  11153.  
  11154.  
  11155.  
  11156.  
  11157.  
  11158.                                   Q - PRO 4 Commands
  11159.  
  11160.  
  11161.      HON
  11162.      ---
  11163.      HON turns the screen highlight on at the current cursor position.  
  11164.  
  11165.      Syntax:   HON
  11166.  
  11167.      Remarks        If highlights are not defined for this hardware, a blank
  11168.                     will be printed.  (This is the same as having a highlight
  11169.                     character placed on the screen in the background.)  HOFF
  11170.                     will turn the highlight off.  Note that different screens
  11171.                     will react differently depending on how the highlights are
  11172.                     implemented in hardware.
  11173.  
  11174.      Examples:
  11175.           For example, suppose that you want to highlight a message on the
  11176.           screen which will read "YOU FOOL" at screen position row 2, line 10. 
  11177.           The following will always highlight it:
  11178.  
  11179.           CURSOR 2,9
  11180.           HON
  11181.           PRINT "YOU FOOL"
  11182.           CURSOR 2, 19
  11183.           HOFF
  11184.  
  11185.           Be careful with this instruction if you use a variety of hardware. 
  11186.           Note that the highlight character requires a screen position.  Data
  11187.           previously printed in this location will not be restored.  
  11188.  
  11189.  
  11190.  
  11191.  
  11192.  
  11193.  
  11194.  
  11195.  
  11196.  
  11197.  
  11198.  
  11199.  
  11200.  
  11201.  
  11202.  
  11203.  
  11204.  
  11205.  
  11206.  
  11207.  
  11208.  
  11209.                                        Commands
  11210.                                        Page 173
  11211.  
  11212.  
  11213.  
  11214.  
  11215.  
  11216.  
  11217.  
  11218.                                   Q - PRO 4 Commands
  11219.  
  11220.  
  11221.      HOME
  11222.      ----
  11223.      HOME moves the cursor to the first enterable field on the screen and
  11224.      returns control to the operator for data entry.
  11225.  
  11226.      Syntax:   HOME
  11227.  
  11228.      Remarks        No more statements in the current procedure will be
  11229.                     executed.  If HOME is executed in PROC ENTER, the fields
  11230.                     will not be cleared.
  11231.  
  11232.  
  11233.  
  11234.  
  11235.  
  11236.  
  11237.  
  11238.  
  11239.  
  11240.  
  11241.  
  11242.  
  11243.  
  11244.  
  11245.  
  11246.  
  11247.  
  11248.  
  11249.  
  11250.  
  11251.  
  11252.  
  11253.  
  11254.  
  11255.  
  11256.  
  11257.  
  11258.  
  11259.  
  11260.  
  11261.  
  11262.  
  11263.  
  11264.  
  11265.  
  11266.  
  11267.  
  11268.  
  11269.                                        Commands
  11270.                                        Page 174
  11271.  
  11272.  
  11273.  
  11274.  
  11275.  
  11276.  
  11277.  
  11278.                                   Q - PRO 4 Commands
  11279.  
  11280.  
  11281.      HOMECLEAR
  11282.      ---------
  11283.      HOMECLEAR moves the cursor to the first enterable field on the screen and
  11284.      clears all enterable fields.  As in the HOME command, control is then
  11285.      returned to the operator for data entry.
  11286.  
  11287.      Syntax:   HOMECLEAR
  11288.  
  11289.  
  11290.  
  11291.  
  11292.  
  11293.  
  11294.  
  11295.  
  11296.  
  11297.  
  11298.  
  11299.  
  11300.  
  11301.  
  11302.  
  11303.  
  11304.  
  11305.  
  11306.  
  11307.  
  11308.  
  11309.  
  11310.  
  11311.  
  11312.  
  11313.  
  11314.  
  11315.  
  11316.  
  11317.  
  11318.  
  11319.  
  11320.  
  11321.  
  11322.  
  11323.  
  11324.  
  11325.  
  11326.  
  11327.  
  11328.  
  11329.                                        Commands
  11330.                                        Page 175
  11331.  
  11332.  
  11333.  
  11334.  
  11335.  
  11336.  
  11337.  
  11338.                                   Q - PRO 4 Commands
  11339.  
  11340.  
  11341.      HOST
  11342.      ----
  11343.      The HOST command establishes the host operating system.  No files may be
  11344.      open when this command is given.  A HOST statement takes precedence over
  11345.      the setting of the host bit in SETUP.  Refer to the Programmer's Reference
  11346.      Manual for hosts supported.
  11347.  
  11348.      Syntax:   HOST <string data item>
  11349.  
  11350.      Examples:
  11351.           HOST "NETWARE"
  11352.           HOST #S1
  11353.  
  11354.      HOSTS available.  (See READ.ME for changes.)
  11355.  
  11356.                OS or LAN                     HOST
  11357.                ---------                     ----
  11358.           IBM Network or PC-MOS         IBMNET or MSNET
  11359.           PC or MS-DOS                  PC-DOS or SINGLE
  11360.           NetWare (Novell)              NETWARE
  11361.  
  11362.  
  11363.  
  11364.  
  11365.  
  11366.  
  11367.  
  11368.  
  11369.  
  11370.  
  11371.  
  11372.  
  11373.  
  11374.  
  11375.  
  11376.  
  11377.  
  11378.  
  11379.  
  11380.  
  11381.  
  11382.  
  11383.  
  11384.  
  11385.  
  11386.  
  11387.  
  11388.  
  11389.                                        Commands
  11390.                                        Page 176
  11391.  
  11392.  
  11393.  
  11394.  
  11395.  
  11396.  
  11397.  
  11398.                                   Q - PRO 4 Commands
  11399.  
  11400.  
  11401.      IF
  11402.      --
  11403.      IF allows the conditional execution of program statements.
  11404.  
  11405.      Syntax:  IF <condition> {AND/OR <condition>} {THEN} <statement>
  11406.  
  11407.      condition      A condition is the comparison of two data items of like type
  11408.                     (i.e., either both are numeric or both are string) in the
  11409.                     format <data item 1> <operation> <data item 2> using the
  11410.                     following conditional operators:
  11411.  
  11412.      EQ or =        test for item 1 equal to item 2
  11413.      NEQ or <>      test for item 1 not equal to item 2
  11414.      LT or  <       test for item 1 less than item 2
  11415.      LE or <=       test for item 1 less than or equal to item 2
  11416.      GT or >        test for item 1 greater than item 2
  11417.      GE or >=       test for item 1 greater than or equal to item 2
  11418.      NLT            test for item 1 not less than item 2
  11419.      NLE            test for item 1 not less than or equal to item2
  11420.      NGT            test for item 1 not greater than item 2
  11421.      NGE            test for item 1 not greater than or equal to item 2
  11422.      ~              condition negation operator 
  11423.  
  11424.           AND/OR
  11425.           ------
  11426.           Multiple conditions may be joined by AND and OR operators, although
  11427.           these are evaluated from left to right without relative precedence. 
  11428.           Conditions may be nested with parentheses for complex logical
  11429.           evaluations.
  11430.  
  11431.           THEN
  11432.           ----
  11433.           The keyword THEN, used for readability, is optional.
  11434.  
  11435.      Remarks        Any executable statement may be performed as a result of an
  11436.                     IF statement, including (for example) an END or another IF
  11437.                     statement.
  11438.  
  11439.      Examples:
  11440.           IF CUSTNO EQ 0 THEN ERROR "INVALID NUMBER"
  11441.           IF #B0 SET THEN CALL SUB_ROUT1
  11442.           IF TYPE EQ "A" OR TYPE EQ "F" THEN MOVE 0 TO #N0
  11443.           IF #N0 > #N1 THEN MOVE "OVERFLOW" TO STATUS
  11444.           IF JOBNAME = "ZZZZZZ" GOTO 100
  11445.           IF TYPE EQ "A" OR TYPE EQ "B" OR TYPE EQ "C" CLEAR STAT
  11446.           IF KEY EQ 0 AND NAME EQ "" OR CUSTNO NLT 1000 GOTO 2090
  11447.  
  11448.  
  11449.                                        Commands
  11450.                                        Page 177
  11451.  
  11452.  
  11453.  
  11454.  
  11455.  
  11456.  
  11457.  
  11458.                                   Q - PRO 4 Commands
  11459.  
  11460.  
  11461.           IF MONTH <= 12 AND MONTH >= 1 THEN END
  11462.           IF (MON GT 5 AND DAY LT 1) AND MOON EQ "BLUE" THEN END
  11463.           IF ~A=B THEN GOTO NOT_EQUAL
  11464.           IF #B0 SET GOTO 100
  11465.           IF #B9 RESET IF STATUS NEQ "OPEN" MOVE "CLOSED" TO MSG
  11466.           IF #B2 SET ON #B3 SET ON #B4 RESET HOMECLEAR
  11467.           IF #B[#N4] RESET CALL READREC
  11468.  
  11469.  
  11470.  
  11471.  
  11472.  
  11473.  
  11474.  
  11475.  
  11476.  
  11477.  
  11478.  
  11479.  
  11480.  
  11481.  
  11482.  
  11483.  
  11484.  
  11485.  
  11486.  
  11487.  
  11488.  
  11489.  
  11490.  
  11491.  
  11492.  
  11493.  
  11494.  
  11495.  
  11496.  
  11497.  
  11498.  
  11499.  
  11500.  
  11501.  
  11502.  
  11503.  
  11504.  
  11505.  
  11506.  
  11507.  
  11508.  
  11509.                                        Commands
  11510.                                        Page 178
  11511.  
  11512.  
  11513.  
  11514.  
  11515.  
  11516.  
  11517.  
  11518.                                   Q - PRO 4 Commands
  11519.  
  11520.  
  11521.      INSTR
  11522.      -----
  11523.      INSTR searches a string for a substring match.
  11524.  
  11525.      Syntax:   INSTR <substring> {TRIMMED}, <string> {TRIMMED}, <result>
  11526.  
  11527.      substring      Substring to be searched for in the string.
  11528.      TRIMMED        Do not use trailing blanks in the substring for the match.
  11529.      string         String to be searched.
  11530.      TRIMMED        Do not use trailing blanks in the string to be searched for
  11531.                     the match.
  11532.      result         A numeric data item to place the result of the search.  If
  11533.                     there is a match, <result> will contain the first position
  11534.                     of the match in the searched string.  If no match, its value
  11535.                     will be 0.
  11536.  
  11537.      Example:
  11538.           INSTR "ABC", &FIELD[1] TRIMMED, #N0
  11539.                Looks for the string "ABC" in the file field FIELD, TRIMMED.  If
  11540.                found, place the location of the string in #N0.  If not found
  11541.                place a 0 in #N0.
  11542.  
  11543.  
  11544.  
  11545.  
  11546.  
  11547.  
  11548.  
  11549.  
  11550.  
  11551.  
  11552.  
  11553.  
  11554.  
  11555.  
  11556.  
  11557.  
  11558.  
  11559.  
  11560.  
  11561.  
  11562.  
  11563.  
  11564.  
  11565.  
  11566.  
  11567.  
  11568.  
  11569.                                        Commands
  11570.                                        Page 179
  11571.  
  11572.  
  11573.  
  11574.  
  11575.  
  11576.  
  11577.  
  11578.                                   Q - PRO 4 Commands
  11579.  
  11580.  
  11581.      JDPACK
  11582.      ------
  11583.      JDPACK calculates a Julian date and moves it into a data item.  
  11584.  
  11585.  
  11586.      Syntax:   JDPACK <date string> INTO <data item>
  11587.  
  11588.      date string         The date string must be of the form MM/DD/YYYY.
  11589.      data item           Any numeric data item except a literal.
  11590.      Remarks             The base date is December 31, 1977.  Therefore January
  11591.                          1, 1978 will JDPACK to 1 and December 30, 1977 will
  11592.                          JDPACK to -1.  Refer to JDUNPACK for converting Julian
  11593.                          dates to calendar dates. 
  11594.  
  11595.      Example
  11596.           JDPACK "04/25/1984" INTO #N1
  11597.  
  11598.  
  11599.  
  11600.  
  11601.  
  11602.  
  11603.  
  11604.  
  11605.  
  11606.  
  11607.  
  11608.  
  11609.  
  11610.  
  11611.  
  11612.  
  11613.  
  11614.  
  11615.  
  11616.  
  11617.  
  11618.  
  11619.  
  11620.  
  11621.  
  11622.  
  11623.  
  11624.  
  11625.  
  11626.  
  11627.  
  11628.  
  11629.                                        Commands
  11630.                                        Page 180
  11631.  
  11632.  
  11633.  
  11634.  
  11635.  
  11636.  
  11637.  
  11638.                                   Q - PRO 4 Commands
  11639.  
  11640.  
  11641.      JDUNPACK
  11642.      --------
  11643.      JDUNPACK converts the previously created Julian date in a data item to a
  11644.      calendar date.
  11645.  
  11646.      Syntax:   JDUNPACK <data item1> INTO <data item2>
  11647.  
  11648.      data item1          A previously packed Julian date.
  11649.      data item2          The destination data item must be a string.
  11650.      Remarks             Refer to JDPACK for generating the Julian date in a
  11651.                          data item.
  11652.  
  11653.      Example:
  11654.           JDUNPACK  #N1 INTO #S0
  11655.  
  11656.  
  11657.  
  11658.  
  11659.  
  11660.  
  11661.  
  11662.  
  11663.  
  11664.  
  11665.  
  11666.  
  11667.  
  11668.  
  11669.  
  11670.  
  11671.  
  11672.  
  11673.  
  11674.  
  11675.  
  11676.  
  11677.  
  11678.  
  11679.  
  11680.  
  11681.  
  11682.  
  11683.  
  11684.  
  11685.  
  11686.  
  11687.  
  11688.  
  11689.                                        Commands
  11690.                                        Page 181
  11691.  
  11692.  
  11693.  
  11694.  
  11695.  
  11696.  
  11697.  
  11698.                                   Q - PRO 4 Commands
  11699.  
  11700.  
  11701.      KEY
  11702.      ---
  11703.      KEY changes the current ISAM file KEY.
  11704.           
  11705.      Syntax:        KEY <file #> <B>USING <key #> 
  11706.  
  11707.      file #         The file number expressed as a literal or numeric data item.
  11708.      key #          The key number from 0 to 9, expressed as a literal or
  11709.                     numeric data item. 
  11710.      Remarks        Key 1 is the primary key and must be unique, but the
  11711.                     alternates (2-9) may be duplicates.  Duplicates will be in
  11712.                     primary key order.  For example, a record has two keys, NAME
  11713.                     and ZIP_CODE, and there are 3 records, MIKE 19438, JOHN
  11714.                     19438, and LARRY 19454.  Reading the file in primary key
  11715.                     order the records will be in the sequence:  JOHN 19438,
  11716.                     LARRY 19454 and MIKE 19438.  Reading in the second key order
  11717.                     the record will be in the sequence:  JOHN 19438, MIKE 19438,
  11718.                     and LARRY 19454.  Refer to POSN for the method of changing
  11719.                     the key using POSN.
  11720.  
  11721.                     Key 0 puts the file in physical order.
  11722.  
  11723.      Example:
  11724.           KEY 1 USING 3
  11725.           KEY #N1 USING #N3
  11726.  
  11727.  
  11728.  
  11729.  
  11730.  
  11731.  
  11732.  
  11733.  
  11734.  
  11735.  
  11736.  
  11737.  
  11738.  
  11739.  
  11740.  
  11741.  
  11742.  
  11743.  
  11744.  
  11745.  
  11746.  
  11747.  
  11748.  
  11749.                                        Commands
  11750.                                        Page 182
  11751.  
  11752.  
  11753.  
  11754.  
  11755.  
  11756.  
  11757.  
  11758.                                   Q - PRO 4 Commands
  11759.  
  11760.  
  11761.      LJUST
  11762.      -----
  11763.      LJUST left justifies data in a data item.
  11764.  
  11765.      Syntax:        LJUST <data item>
  11766.  
  11767.      data item      Any data item.
  11768.      Remarks        Left justification will occur even in fields defined as
  11769.                     right justified.
  11770.  
  11771.      Example:
  11772.           LJUST AMOUNT
  11773.           LJUST #S3
  11774.  
  11775.  
  11776.  
  11777.  
  11778.  
  11779.  
  11780.  
  11781.  
  11782.  
  11783.  
  11784.  
  11785.  
  11786.  
  11787.  
  11788.  
  11789.  
  11790.  
  11791.  
  11792.  
  11793.  
  11794.  
  11795.  
  11796.  
  11797.  
  11798.  
  11799.  
  11800.  
  11801.  
  11802.  
  11803.  
  11804.  
  11805.  
  11806.  
  11807.  
  11808.  
  11809.                                        Commands
  11810.                                        Page 183
  11811.  
  11812.  
  11813.  
  11814.  
  11815.  
  11816.  
  11817.  
  11818.                                   Q - PRO 4 Commands
  11819.  
  11820.  
  11821.      LOAD
  11822.      ----
  11823.      The LOAD command loads a machine code file into memory at the indicated
  11824.      address.  
  11825.  
  11826.      Syntax:   LOAD <file name>, <address> {:error}
  11827.  
  11828.      file name      The name of the file to be loaded as a literal in quotes or
  11829.                     as a string data item.
  11830.      address        The address at which to load the machine language program.
  11831.      Remarks        The error branch is taken if the file cannot be opened. 
  11832.                     Otherwise, the file is loaded into memory.  The responsi-
  11833.                     bility of making sure the file fits in memory is the
  11834.                     programmer's.  Refer to the Techniques Chapter for more
  11835.                     details.
  11836.  
  11837.      Example:
  11838.           LOAD "ROUTINES.COM", 48532  :897
  11839.  
  11840.  
  11841.  
  11842.  
  11843.  
  11844.  
  11845.  
  11846.  
  11847.  
  11848.  
  11849.  
  11850.  
  11851.  
  11852.  
  11853.  
  11854.  
  11855.  
  11856.  
  11857.  
  11858.  
  11859.  
  11860.  
  11861.  
  11862.  
  11863.  
  11864.  
  11865.  
  11866.  
  11867.  
  11868.  
  11869.                                        Commands
  11870.                                        Page 184
  11871.  
  11872.  
  11873.  
  11874.  
  11875.  
  11876.  
  11877.  
  11878.                                   Q - PRO 4 Commands
  11879.  
  11880.  
  11881.      LOCK
  11882.      ----
  11883.      LOCK makes a normally enterable screen data field unavailable to the
  11884.      operator.  The operator may not enter the field until a corresponding
  11885.      UNLOCK statement is executed.
  11886.  
  11887.      Syntax:   LOCK<screen data field name>
  11888.  
  11889.      screen data field name   A valid screen data field name.
  11890.      Remarks                  Locked fields will not be accessed in GET * or PUT
  11891.                               * statements.
  11892.  
  11893.      Example:
  11894.           LOCK CUSTNO
  11895.           LOCK $FIELD[#N8]
  11896.  
  11897.  
  11898.  
  11899.  
  11900.  
  11901.  
  11902.  
  11903.  
  11904.  
  11905.  
  11906.  
  11907.  
  11908.  
  11909.  
  11910.  
  11911.  
  11912.  
  11913.  
  11914.  
  11915.  
  11916.  
  11917.  
  11918.  
  11919.  
  11920.  
  11921.  
  11922.  
  11923.  
  11924.  
  11925.  
  11926.  
  11927.  
  11928.  
  11929.                                        Commands
  11930.                                        Page 185
  11931.  
  11932.  
  11933.  
  11934.  
  11935.  
  11936.  
  11937.  
  11938.                                   Q - PRO 4 Commands
  11939.  
  11940.  
  11941.      LPDETACH
  11942.      --------
  11943.      LPDETACH detaches the current user from the multiuser or LAN system printer
  11944.      or terminates the current spool file depending on the operating system. 
  11945.      This allows access to the printer by other users.
  11946.  
  11947.      Syntax:   LPDETACH
  11948.  
  11949.      Remarks        Failure to use this command when printing from Q-PRO 4 (not
  11950.                     the Report Generator) on some operating systems will lock
  11951.                     the print spooler until a system reset.  Operating systems
  11952.                     that do not use the command will ignore it.
  11953.  
  11954.  
  11955.  
  11956.  
  11957.  
  11958.  
  11959.  
  11960.  
  11961.  
  11962.  
  11963.  
  11964.  
  11965.  
  11966.  
  11967.  
  11968.  
  11969.  
  11970.  
  11971.  
  11972.  
  11973.  
  11974.  
  11975.  
  11976.  
  11977.  
  11978.  
  11979.  
  11980.  
  11981.  
  11982.  
  11983.  
  11984.  
  11985.  
  11986.  
  11987.  
  11988.  
  11989.                                        Commands
  11990.                                        Page 186
  11991.  
  11992.  
  11993.  
  11994.  
  11995.  
  11996.  
  11997.  
  11998.                                   Q - PRO 4 Commands
  11999.  
  12000.  
  12001.      LRETRY
  12002.      ------
  12003.      LRETRY sets the retry count for header record locking on multiuser systems.
  12004.  
  12005.      Syntax:   LRETRY <numeric data item>
  12006.  
  12007.      numeric data item        Any numeric data item.
  12008.      Remarks                  It is usually used in PROC LOAD.
  12009.  
  12010.      Example:
  12011.           LRETRY  100
  12012.  
  12013.  
  12014.  
  12015.  
  12016.  
  12017.  
  12018.  
  12019.  
  12020.  
  12021.  
  12022.  
  12023.  
  12024.  
  12025.  
  12026.  
  12027.  
  12028.  
  12029.  
  12030.  
  12031.  
  12032.  
  12033.  
  12034.  
  12035.  
  12036.  
  12037.  
  12038.  
  12039.  
  12040.  
  12041.  
  12042.  
  12043.  
  12044.  
  12045.  
  12046.  
  12047.  
  12048.  
  12049.                                        Commands
  12050.                                        Page 187
  12051.  
  12052.  
  12053.  
  12054.  
  12055.  
  12056.  
  12057.  
  12058.                                   Q - PRO 4 Commands
  12059.  
  12060.  
  12061.      MAKE
  12062.      ----
  12063.      MAKE deletes a file from the directory of a diskette (if it previously
  12064.      existed), and then creates it as directed by the parameters to the
  12065.      statement.  At creation a file number is assigned.  When the file is
  12066.      created, it is immediately ready for use.
  12067.  
  12068.      In all formats, the file name may be a string literal or string data item. 
  12069.      The error branch is taken if the system is unable to create the file (e.g.,
  12070.      write-protected or full disk). (Refer to the Programmer's Reference Manual
  12071.      for a full discussion of files.)  The statement may take one of four forms.
  12072.  
  12073.      Syntax 1: (Indexed and Random files)
  12074.  
  12075.      MAKE <filename> USING <FID filena> {INDEX <INDEX filena>}, <file num>
  12076.      {:error}
  12077.  
  12078.      filename       The name of the file as a literal in quotes or a string data
  12079.                     item.
  12080.      USING          Points to the FID file name.
  12081.      FID file name  The name of the FID file as a literal in quotes or a string
  12082.                     data item.
  12083.      INDEX          Points to the index file (indexed files only).  This phrase
  12084.                     is optional.  If omitted, an index file will be created that
  12085.                     is the same name as the FID file with the extension IDX.
  12086.      INDEX file na  The name of the INDEX file as a literal in quotes or a
  12087.                     string data item.
  12088.      file number    A literal or numeric data item.  Until closed or deleted,
  12089.                     the file will be referred to by this file number.
  12090.  
  12091.      Remarks        The FID (file item description file created by the FID
  12092.                     generator program) determines if the file is random or
  12093.                     indexed.  All additional information (file type, record
  12094.                     size, key size and location, etc.) is derived from
  12095.                     information in the FID file.
  12096.  
  12097.      Examples:
  12098.           MAKE "C:NEWDATA" USING "NEWDATA.FID", 1 :654
  12099.           MAKE #S0 USING #S1 INDEX #S3, #N1: 100
  12100.  
  12101.      Syntax 2: (Sequential Files)
  12102.  
  12103.           MAKE <filename>, <file type>, <file number> {<:error>}
  12104.  
  12105.      filename       The name of the file as a literal in quotes or a string data
  12106.                     item.
  12107.  
  12108.  
  12109.                                        Commands
  12110.                                        Page 188
  12111.  
  12112.  
  12113.  
  12114.  
  12115.  
  12116.  
  12117.  
  12118.                                   Q - PRO 4 Commands
  12119.  
  12120.  
  12121.      filetype       The type of sequential (text) file.  The file types are:
  12122.                     0    sequential output
  12123.                     1    sequential input
  12124.                     4    SDF (comma delimited) output
  12125.                     5    SDF (comma delimited) input
  12126.  
  12127.      file number    A literal or numeric data item.  Until closed or deleted,
  12128.                     the file will be referred to by this file number.
  12129.  
  12130.      Examples:
  12131.  
  12132.           MAKE "B:TEMP.$$$",1,1 :100
  12133.  
  12134.           LAN and Multiuser System Optional KEYWORD
  12135.           -----------------------------------------
  12136.           MAKE has an optional keyword after the file number, UNLOCKED.  If
  12137.           UNLOCKED is not used, a file is created in the locked mode.  
  12138.  
  12139.      Examples:
  12140.      MAKE "FILE" USING "FIDFILE",1 UNLOCKED :100
  12141.  
  12142.  
  12143.  
  12144.  
  12145.  
  12146.  
  12147.  
  12148.  
  12149.  
  12150.  
  12151.  
  12152.  
  12153.  
  12154.  
  12155.  
  12156.  
  12157.  
  12158.  
  12159.  
  12160.  
  12161.  
  12162.  
  12163.  
  12164.  
  12165.  
  12166.  
  12167.  
  12168.  
  12169.                                        Commands
  12170.                                        Page 189
  12171.  
  12172.  
  12173.  
  12174.  
  12175.  
  12176.  
  12177.  
  12178.                                   Q - PRO 4 Commands
  12179.  
  12180.  
  12181.      MEMEND
  12182.      MEMEND establishes the highest address in memory that Q-PRO 4 can use,
  12183.      presumably because machine language programs will be loaded at higher
  12184.      addresses.
  12185.  
  12186.      Syntax:
  12187.      MEMEND <address in decimal {:<error>}
  12188.  
  12189.      address in decimal       The address to be set.
  12190.      Remarks                  If the system would be left with insufficient
  12191.                               memory after changing the highest address used,
  12192.                               the error trap is taken with an Out2 OF MEMORY
  12193.                               error.
  12194.  
  12195.                               No particular restrictions apply to open files or
  12196.                               declared variables when MEMEND is invoked.
  12197.  
  12198.      Example:
  12199.           MEMEND 49152
  12200.  
  12201.  
  12202.  
  12203.  
  12204.  
  12205.  
  12206.  
  12207.  
  12208.  
  12209.  
  12210.  
  12211.  
  12212.  
  12213.  
  12214.  
  12215.  
  12216.  
  12217.  
  12218.  
  12219.  
  12220.  
  12221.  
  12222.  
  12223.  
  12224.  
  12225.  
  12226.  
  12227.  
  12228.  
  12229.                                        Commands
  12230.                                        Page 190
  12231.  
  12232.  
  12233.  
  12234.  
  12235.  
  12236.  
  12237.  
  12238.                                   Q - PRO 4 Commands
  12239.  
  12240.  
  12241.      MOVE
  12242.      ----
  12243.      The MOVE command is used to transfer data between data items.  Modifiers to
  12244.      the basic command provide powerful mechanisms for handling substrings, and
  12245.      concatenating data items.Data between Data Items
  12246.  
  12247.      Syntax:
  12248.  
  12249.      MOVE <dataitem1> {<string source modifier>} TO <dataitem2> {<string
  12250.      destination modifier>} {TRIMMED}
  12251.  
  12252.      dataitem1           The data items may be numeric or string literals, or
  12253.                          any string data item (data item 2 may not be a
  12254.                          literal).  MOVEing a string to a numeric data item is
  12255.                          acceptable if the string contains only numerically
  12256.                          acceptable data.
  12257.      string source
  12258.           modifier       The string source modifier provides a way to extract
  12259.                          substrings from a string data item.  The source data
  12260.                          item must be a string to use a modifier.  The format of
  12261.                          the source modifier is:
  12262.  
  12263.                          [start position,length or *]
  12264.  
  12265.  
  12266.                               The start position may range from 1 to the length
  12267.                               of the string.  The length may not exceed the
  12268.                               length of the string.  An asterisk (*) may be
  12269.                               substituted for the length of the string, in which
  12270.                               case the right-hand portion of the string from the
  12271.                               starting position on is taken.
  12272.  
  12273.                          string destination modifier
  12274.  
  12275.                               The string destination modifier allows the
  12276.                               placement of substrings within strings, or the
  12277.                               concatenation of strings.  The format of the
  12278.                               destination modifier is:
  12279.  
  12280.  
  12281.                          [start position or *]
  12282.  
  12283.                               The source string is moved to the start position
  12284.                               of the destination string.  If an asterisk is
  12285.                               used, the source string is appended to the
  12286.                               destination string.
  12287.  
  12288.  
  12289.                                        Commands
  12290.                                        Page 191
  12291.  
  12292.  
  12293.  
  12294.  
  12295.  
  12296.  
  12297.  
  12298.                                   Q - PRO 4 Commands
  12299.  
  12300.  
  12301.  
  12302.      TRIMMED             If the keyword TRIMMED is used, trailing spaces are
  12303.                          eliminated from the source string.
  12304.  
  12305.      Examples:
  12306.  
  12307.           Simple Moves
  12308.           ------------
  12309.           MOVE A TO B
  12310.                Moves field (or variable) "A" to field (or variable) "B". 
  12311.  
  12312.           MOVE 0 TO #N0 
  12313.                Moves the number zero (0) to numeric register 0, and clears it.
  12314.  
  12315.           MOVE "PLEASE ENTER A VALID ID CODE" TO STATUSMSG
  12316.                Moves "PLEASE ENTER A VALID ID CODE" to the field (or variable)
  12317.                STATUSMSG.
  12318.  
  12319.           Partial Moves
  12320.           -------------
  12321.           MOVE "     " TO #S0[3] 
  12322.                Moves 5 blanks to string register 0 beginning in position 3.
  12323.  
  12324.           MOVE NAME[1,10] TO FNAME
  12325.                Moves characters 1 through 10 in the field (or variable) NAME to
  12326.                the field (or variable) FNAME.
  12327.  
  12328.           MOVE #S0[#N0,FLDLEN] TO #S1[*]
  12329.                Moves the contents of string register 0 from the number in
  12330.                numeric register 0 for the length contained in FLDLEN.
  12331.  
  12332.  
  12333.           Move with Trimming
  12334.           ------------------
  12335.           MOVE #S3 TO #S3 TRIMMED
  12336.                Move #S3 to itself removing trailing blanks.
  12337.  
  12338.           MOVE $FIELD[#N0][1,20] TO #S[#N1][*] TRIMMED
  12339.                Moves a screen field with the offset contained in #N0 starting in
  12340.                position 1 for 20 characters to a string register whose number is
  12341.                contained in #N1.  The asterisk indicates that the previous data
  12342.                in the string register will be left intact and the new data will
  12343.                be concatenated.  The data moved will have trailing blanks
  12344.                dropped.
  12345.  
  12346.  
  12347.  
  12348.  
  12349.                                        Commands
  12350.                                        Page 192
  12351.  
  12352.  
  12353.  
  12354.  
  12355.  
  12356.  
  12357.  
  12358.                                   Q - PRO 4 Commands
  12359.  
  12360.  
  12361.           Concatenation (attach one string data item to another) 
  12362.           -------------
  12363.           MOVE #S0 TO #S1[*]
  12364.                Concatenates the contents of #S0 to the current contents of #S1.
  12365.  
  12366.           MOVE #S0 TO #S1[*] TRIMMED
  12367.                Truncates any trailing spaces in #S0 and then concatenates the
  12368.                contents of #S0 to the current contents of #S1.
  12369.  
  12370.  
  12371.  
  12372.  
  12373.  
  12374.  
  12375.  
  12376.  
  12377.  
  12378.  
  12379.  
  12380.  
  12381.  
  12382.  
  12383.  
  12384.  
  12385.  
  12386.  
  12387.  
  12388.  
  12389.  
  12390.  
  12391.  
  12392.  
  12393.  
  12394.  
  12395.  
  12396.  
  12397.  
  12398.  
  12399.  
  12400.  
  12401.  
  12402.  
  12403.  
  12404.  
  12405.  
  12406.  
  12407.  
  12408.  
  12409.                                        Commands
  12410.                                        Page 193
  12411.  
  12412.  
  12413.  
  12414.  
  12415.  
  12416.  
  12417.  
  12418.                                   Q - PRO 4 Commands
  12419.  
  12420.  
  12421.      MUL
  12422.      ---
  12423.      MUL multiplies two data items and optionally places the result in a third.
  12424.  
  12425.      Syntax:   MUL <data item 1> TIMES <data item 2>{GIVING <data item 3>}
  12426.  
  12427.      data item 1         The multiplier must be a valid numeric data item.  
  12428.      data item 2         The multiplicand must be a valid numeric data item.
  12429.      Remarks             If the GIVING clause is not present, then the result is
  12430.                          stored in data item 2.  Optionally, the keyword TIMES
  12431.                          may be replaced with a comma.
  12432.  
  12433.      Examples:
  12434.           MUL 1.5 TIMES REGPAY GIVING OTPAY
  12435.           MUL FACTOR , BASE
  12436.  
  12437.  
  12438.  
  12439.  
  12440.  
  12441.  
  12442.  
  12443.  
  12444.  
  12445.  
  12446.  
  12447.  
  12448.  
  12449.  
  12450.  
  12451.  
  12452.  
  12453.  
  12454.  
  12455.  
  12456.  
  12457.  
  12458.  
  12459.  
  12460.  
  12461.  
  12462.  
  12463.  
  12464.  
  12465.  
  12466.  
  12467.  
  12468.  
  12469.                                        Commands
  12470.                                        Page 194
  12471.  
  12472.  
  12473.  
  12474.  
  12475.  
  12476.  
  12477.  
  12478.                                   Q - PRO 4 Commands
  12479.  
  12480.  
  12481.      NCHECK
  12482.      ------
  12483.      The NCHECK statement will verify that a string data item contains only
  12484.      numeric data; i.e. no commas, dollar signs, or other trash.
  12485.  
  12486.      Syntax:   NCHECK <data item> {<:error>}
  12487.  
  12488.      data item      the string data item to be checked.
  12489.      error          The error branch is taken if the data item is not numeric. 
  12490.                     Note that a field of all spaces is considered numerically
  12491.                     valid (0).
  12492.  
  12493.      Examples:
  12494.           NCHECK $FIELD[#N0+3] :100
  12495.           NCHECK CUSTNUM[CUSTTYPE]  :1023
  12496.  
  12497.  
  12498.  
  12499.  
  12500.  
  12501.  
  12502.  
  12503.  
  12504.  
  12505.  
  12506.  
  12507.  
  12508.  
  12509.  
  12510.  
  12511.  
  12512.  
  12513.  
  12514.  
  12515.  
  12516.  
  12517.  
  12518.  
  12519.  
  12520.  
  12521.  
  12522.  
  12523.  
  12524.  
  12525.  
  12526.  
  12527.  
  12528.  
  12529.                                        Commands
  12530.                                        Page 195
  12531.  
  12532.  
  12533.  
  12534.  
  12535.  
  12536.  
  12537.  
  12538.                                   Q - PRO 4 Commands
  12539.  
  12540.  
  12541.      NEXT
  12542.      ----
  12543.      The NEXT statement moves the cursor to a specified field and returns
  12544.      control to the operator for data entry.
  12545.  
  12546.      Syntax:   NEXT <field name or *>
  12547.  
  12548.      field name or *     The name of the screen data field in quotes or a $FIELD
  12549.                          expression.  If the asterisk is used, the cursor will
  12550.                          move to the next sequential unlocked field.
  12551.      Remarks             It is the programmer's responsibility to insure that
  12552.                          NEXT does not jump control to a non-enterable screen
  12553.                          data field.  A NEXT command with no field specified
  12554.                          will move the cursor to the next enterable unlocked
  12555.                          field. 
  12556.  
  12557.      Examples:
  12558.           NEXT ALPHA
  12559.           NEXT $FIELD[#N1]
  12560.           NEXT *
  12561.           NEXT
  12562.  
  12563.  
  12564.  
  12565.  
  12566.  
  12567.  
  12568.  
  12569.  
  12570.  
  12571.  
  12572.  
  12573.  
  12574.  
  12575.  
  12576.  
  12577.  
  12578.  
  12579.  
  12580.  
  12581.  
  12582.  
  12583.  
  12584.  
  12585.  
  12586.  
  12587.  
  12588.  
  12589.                                        Commands
  12590.                                        Page 196
  12591.  
  12592.  
  12593.  
  12594.  
  12595.  
  12596.  
  12597.  
  12598.                                   Q - PRO 4 Commands
  12599.  
  12600.  
  12601.      NOFORMLOAD
  12602.      ----------
  12603.      NOFORMLOAD turns off the indicator set by the FORMLOAD command.  This means
  12604.      that after the NOFORMLOAD command is executed, a later return to the
  12605.      operating system will not cause the execution of the format builder
  12606.      utility.
  12607.  
  12608.      Syntax:   NOFORMLOAD
  12609.  
  12610.  
  12611.  
  12612.  
  12613.  
  12614.  
  12615.  
  12616.  
  12617.  
  12618.  
  12619.  
  12620.  
  12621.  
  12622.  
  12623.  
  12624.  
  12625.  
  12626.  
  12627.  
  12628.  
  12629.  
  12630.  
  12631.  
  12632.  
  12633.  
  12634.  
  12635.  
  12636.  
  12637.  
  12638.  
  12639.  
  12640.  
  12641.  
  12642.  
  12643.  
  12644.  
  12645.  
  12646.  
  12647.  
  12648.  
  12649.                                        Commands
  12650.                                        Page 197
  12651.  
  12652.  
  12653.  
  12654.  
  12655.  
  12656.  
  12657.  
  12658.                                   Q - PRO 4 Commands
  12659.  
  12660.  
  12661.      NOTRACE
  12662.      -------
  12663.      NOTRACE turns off the TRACE mode used for single-stepping through program
  12664.      statements.  Refer to the TRACE statement for an explanation of this mode.
  12665.  
  12666.      Syntax:   NOTRACE
  12667.  
  12668.  
  12669.  
  12670.  
  12671.  
  12672.  
  12673.  
  12674.  
  12675.  
  12676.  
  12677.  
  12678.  
  12679.  
  12680.  
  12681.  
  12682.  
  12683.  
  12684.  
  12685.  
  12686.  
  12687.  
  12688.  
  12689.  
  12690.  
  12691.  
  12692.  
  12693.  
  12694.  
  12695.  
  12696.  
  12697.  
  12698.  
  12699.  
  12700.  
  12701.  
  12702.  
  12703.  
  12704.  
  12705.  
  12706.  
  12707.  
  12708.  
  12709.                                        Commands
  12710.                                        Page 198
  12711.  
  12712.  
  12713.  
  12714.  
  12715.  
  12716.  
  12717.  
  12718.                                   Q - PRO 4 Commands
  12719.  
  12720.  
  12721.      OPEN
  12722.      ----
  12723.      OPEN locates a pre-existing file on disk and readies the file for I/O
  12724.      operations.
  12725.  
  12726.      Syntax 1: (Random and Indexed Files)
  12727.  
  12728.      OPEN <filena> USING <FID filena> {INDEX <index filena>},<file num> {:error}
  12729.  
  12730.      filena         The path and name of the file to be opened.  This may be a
  12731.                     literal or valid string data item.
  12732.      USING          Points the FID file to be used to open the file.
  12733.      FID filena     The path and name of the FID file (file item description
  12734.                     file created by the FID generator program).  When the file
  12735.                     was created, the FID determined if the file was to be random
  12736.                     or indexed.  All additional information (file type, record
  12737.                     size, key size and location, etc.) is derived from
  12738.                     information in the FID file.
  12739.      INDEX          If this phrase is used, the user must specifically designate
  12740.                     the INDEX file name and path.  If it is not used, the INDEX
  12741.                     file will be understood to be the same as the FID file with
  12742.                     the extension IDX.
  12743.      file num       The number that the file will be know by henceforth.
  12744.  
  12745.      Examples:
  12746.           OPEN "C:NEWDATA" USING "NEWDATA.FID", 1 :654
  12747.  
  12748.  
  12749.      Syntax 2: (Sequential Files)
  12750.  
  12751.      OPEN <filena>, <file type>, <file num> {<:error>}
  12752.  
  12753.      filena         The name of the file as a literal in quotes or a string data
  12754.                     item.
  12755.      filetype       The type of sequential (text) file.  The file types are:
  12756.                     0    sequential output
  12757.                     1    sequential input
  12758.                     4    SDF (comma delimited) output
  12759.                     5    SDF (comma delimited) input
  12760.  
  12761.      file num       A literal or numeric data item.  Until closed or deleted,
  12762.                     the file will be referred to by this file number.
  12763.  
  12764.      Examples:
  12765.           OPEN "B:TEMP.$$$",1,1 :100
  12766.  
  12767.  
  12768.  
  12769.                                        Commands
  12770.                                        Page 199
  12771.  
  12772.  
  12773.  
  12774.  
  12775.  
  12776.  
  12777.  
  12778.                                   Q - PRO 4 Commands
  12779.  
  12780.  
  12781.           Multiuser Optional Keywords
  12782.           ---------------------------
  12783.           OPEN has two optional keywords after the file number, UNLOCKED and R/O
  12784.           (read/only). By default, a file is opened as read/write and locked. 
  12785.           These keywords may be in any order and need not appear together.
  12786.  
  12787.      Examples:
  12788.           OPEN FILE USING FIDFILE,1 UNLOCKED R/O :100
  12789.           OPEN #S0,2,128,5 UNLOCKED
  12790.  
  12791.  
  12792.  
  12793.  
  12794.  
  12795.  
  12796.  
  12797.  
  12798.  
  12799.  
  12800.  
  12801.  
  12802.  
  12803.  
  12804.  
  12805.  
  12806.  
  12807.  
  12808.  
  12809.  
  12810.  
  12811.  
  12812.  
  12813.  
  12814.  
  12815.  
  12816.  
  12817.  
  12818.  
  12819.  
  12820.  
  12821.  
  12822.  
  12823.  
  12824.  
  12825.  
  12826.  
  12827.  
  12828.  
  12829.                                        Commands
  12830.                                        Page 200
  12831.  
  12832.  
  12833.  
  12834.  
  12835.  
  12836.  
  12837.  
  12838.                                   Q - PRO 4 Commands
  12839.  
  12840.  
  12841.      PEEK
  12842.      ----
  12843.      PEEK loads data into a string from memory.
  12844.  
  12845.      Syntax:   PEEK <decimal address>, <length>, <string>
  12846.  
  12847.      decimal address     Address to PEEK
  12848.      length              The length must be less than 256 characters.  On 16 bit
  12849.                          systems PEEK may be used in conjunction with DEFSEG.
  12850.      string              String data item to place the data in.  
  12851.  
  12852.      Examples:
  12853.           PEEK 49012, 6, #S0
  12854.           PEEK #N1,#N2,WHAT 
  12855.  
  12856.  
  12857.  
  12858.  
  12859.  
  12860.  
  12861.  
  12862.  
  12863.  
  12864.  
  12865.  
  12866.  
  12867.  
  12868.  
  12869.  
  12870.  
  12871.  
  12872.  
  12873.  
  12874.  
  12875.  
  12876.  
  12877.  
  12878.  
  12879.  
  12880.  
  12881.  
  12882.  
  12883.  
  12884.  
  12885.  
  12886.  
  12887.  
  12888.  
  12889.                                        Commands
  12890.                                        Page 201
  12891.  
  12892.  
  12893.  
  12894.  
  12895.  
  12896.  
  12897.  
  12898.                                   Q - PRO 4 Commands
  12899.  
  12900.  
  12901.      POKE
  12902.      ----
  12903.      POKE moves a string of data into memory.
  12904.  
  12905.      Syntax:   POKE <decimal address>, <string>
  12906.  
  12907.      decimal address     Address to POKE.  On 16 bit systems POKE may be used in
  12908.                          conjunction with DEFSEG.
  12909.      string              String data item which contains the data.  
  12910.  
  12911.      Examples:
  12912.           POKE 50234, &DESC[#N0]
  12913.           POKE #N1, #S1
  12914.  
  12915.  
  12916.  
  12917.  
  12918.  
  12919.  
  12920.  
  12921.  
  12922.  
  12923.  
  12924.  
  12925.  
  12926.  
  12927.  
  12928.  
  12929.  
  12930.  
  12931.  
  12932.  
  12933.  
  12934.  
  12935.  
  12936.  
  12937.  
  12938.  
  12939.  
  12940.  
  12941.  
  12942.  
  12943.  
  12944.  
  12945.  
  12946.  
  12947.  
  12948.  
  12949.                                        Commands
  12950.                                        Page 202
  12951.  
  12952.  
  12953.  
  12954.  
  12955.  
  12956.  
  12957.  
  12958.                                   Q - PRO 4 Commands
  12959.  
  12960.  
  12961.      POSN
  12962.      ----
  12963.      POSN is used to access an indexed file by its key or a random file by its
  12964.      record number. 
  12965.  
  12966.      Syntax 1:
  12967.  
  12968.      POSN <file number> TO <record number/key> {RELATIVE} {:error}
  12969.  
  12970.      file number         The file number must be an open random or indexed file.
  12971.      record number/key   If the file is a random file, then it must be
  12972.                          positioned to a numeric record number (i.e., numeric
  12973.                          data item).  If the file is indexed, then it must be
  12974.                          positioned to a string value (literal or string data
  12975.                          item).  Remember: keys in indexed files are ASCII
  12976.                          strings.  If the string is not the same length as the
  12977.                          defined key field of the file, then it is padded out to
  12978.                          the right for key search purposes.  Similarly, if the
  12979.                          string is longer than the key field, it is truncated on
  12980.                          the right.
  12981.      RELATIVE            If the key is not found and the keyword RELATIVE is
  12982.                          given, then an indexed file is left positioned at the
  12983.                          next key higher than the one given.  Otherwise, the
  12984.                          file is left positioned at the end.
  12985.      error               No error is generated if the position requested is in-
  12986.                          valid (i.e., off the end of the file, or the given key
  12987.                          does not exist.) Such an error would be detected at the
  12988.                          time of the following read or write statement.
  12989.  
  12990.                          Errors generated by this statement pertain to the
  12991.                          validity of the type of key given for the file type
  12992.                          (e.g., a string key for a random file).
  12993.  
  12994.      Remarks             For indexed files, the POSN statement need not be used
  12995.                          to arrive at a specific key for a write statement, as
  12996.                          the key to be written is implicit in the data record. 
  12997.                          Such a POSN statement is automatically done before an
  12998.                          indexed write.
  12999.  
  13000.      Examples:
  13001.           POSN 1 TO 5 :100
  13002.           POSN 3 TO "*SYSTEM*" RELATIVE
  13003.           POSN 1 TO #N0
  13004.           POSN 99 TO RECNO
  13005.  
  13006.       
  13007.  
  13008.  
  13009.                                        Commands
  13010.                                        Page 203
  13011.  
  13012.  
  13013.  
  13014.  
  13015.  
  13016.  
  13017.  
  13018.                                   Q - PRO 4 Commands
  13019.  
  13020.  
  13021.  
  13022.      POSN, with the optional modifier, USING, will also change the current key.
  13023.  
  13024.      Syntax 2: (Change keys and position)
  13025.  
  13026.      POSN <file number> TO <key> {USING <key #> {:error}
  13027.  
  13028.      Remarks        Identical in function to POSN with the added capability of
  13029.                     changing the current key of an indexed file.
  13030.         
  13031.      Examples:
  13032.           POSN 1 TO &KEY[2] USING #N2 
  13033.  
  13034.  
  13035.  
  13036.  
  13037.  
  13038.  
  13039.  
  13040.  
  13041.  
  13042.  
  13043.  
  13044.  
  13045.  
  13046.  
  13047.  
  13048.  
  13049.  
  13050.  
  13051.  
  13052.  
  13053.  
  13054.  
  13055.  
  13056.  
  13057.  
  13058.  
  13059.  
  13060.  
  13061.  
  13062.  
  13063.  
  13064.  
  13065.  
  13066.  
  13067.  
  13068.  
  13069.                                        Commands
  13070.                                        Page 204
  13071.  
  13072.  
  13073.  
  13074.  
  13075.  
  13076.  
  13077.  
  13078.                                   Q - PRO 4 Commands
  13079.  
  13080.  
  13081.      PRINT
  13082.      -----
  13083.      PRINT allows the program to issue data directly to the screen at the
  13084.      current cursor position.
  13085.  
  13086.      It is most often used in conjunction with CURSOR.
  13087.  
  13088.      Syntax:   PRINT <value> {, <value>, <value> . . .}
  13089.  
  13090.      value          A value may be any numeric or string data item.  Numeric
  13091.                     values are issued to the screen as ASCII strings (use @ to
  13092.                     generate control codes).  For example, if the sequence ESC
  13093.                     (decimal 27) followed by ")" turns on an unconfigured
  13094.                     highlight, and ESC "(" turns it off, we could place a
  13095.                     highlighted message at the top of the screen as follows:
  13096.  
  13097.                     CURSOR 0,0
  13098.                     PRINT @27,')','THIS IS A TEST',@27,'('
  13099.  
  13100.      Remarks        The data displayed via the PRINT command will not be sent to
  13101.                     the printer via the PRINTSCN command.  Data displayed with
  13102.                     the PRINT command on the screen will not be restored after a
  13103.                     HELP or DEBUG command is executed.
  13104.  
  13105.  
  13106.  
  13107.  
  13108.  
  13109.  
  13110.  
  13111.  
  13112.  
  13113.  
  13114.  
  13115.  
  13116.  
  13117.  
  13118.  
  13119.  
  13120.  
  13121.  
  13122.  
  13123.  
  13124.  
  13125.  
  13126.  
  13127.  
  13128.  
  13129.                                        Commands
  13130.                                        Page 205
  13131.  
  13132.  
  13133.  
  13134.  
  13135.  
  13136.  
  13137.  
  13138.                                   Q - PRO 4 Commands
  13139.  
  13140.  
  13141.      PRINTSCN
  13142.      --------
  13143.      PRINTSCN dumps the current contents of the screen to the list device
  13144.      exactly as seen on the screen.
  13145.  
  13146.      Syntax:   PRINTSCN
  13147.  
  13148.  
  13149.  
  13150.  
  13151.  
  13152.  
  13153.  
  13154.  
  13155.  
  13156.  
  13157.  
  13158.  
  13159.  
  13160.  
  13161.  
  13162.  
  13163.  
  13164.  
  13165.  
  13166.  
  13167.  
  13168.  
  13169.  
  13170.  
  13171.  
  13172.  
  13173.  
  13174.  
  13175.  
  13176.  
  13177.  
  13178.  
  13179.  
  13180.  
  13181.  
  13182.  
  13183.  
  13184.  
  13185.  
  13186.  
  13187.  
  13188.  
  13189.                                        Commands
  13190.                                        Page 206
  13191.  
  13192.  
  13193.  
  13194.  
  13195.  
  13196.  
  13197.  
  13198.                                   Q - PRO 4 Commands
  13199.  
  13200.  
  13201.      PROC
  13202.      ----
  13203.      The PROC statement, although not an executable statement as such, is an
  13204.      important part of the command structure.  Its presence in a program denotes
  13205.      the start of a procedure.
  13206.  
  13207.      Syntax:
  13208.  
  13209.      PROC <procedure name>
  13210.  
  13211.      procedure name      This must be a literal that is not in quotes.  All
  13212.                          naming conventions apply.  See Programmer's Reference
  13213.                          Guide for more detail.
  13214.  
  13215.      Examples:
  13216.           PROC ERROR
  13217.           PROC CUSTNOP
  13218.  
  13219.  
  13220.  
  13221.  
  13222.  
  13223.  
  13224.  
  13225.  
  13226.  
  13227.  
  13228.  
  13229.  
  13230.  
  13231.  
  13232.  
  13233.  
  13234.  
  13235.  
  13236.  
  13237.  
  13238.  
  13239.  
  13240.  
  13241.  
  13242.  
  13243.  
  13244.  
  13245.  
  13246.  
  13247.  
  13248.  
  13249.                                        Commands
  13250.                                        Page 207
  13251.  
  13252.  
  13253.  
  13254.  
  13255.  
  13256.  
  13257.  
  13258.                                   Q - PRO 4 Commands
  13259.  
  13260.  
  13261.      PUT
  13262.      ---
  13263.      PUT transfers a data item to a file buffer or printer buffer for later
  13264.      output to the file or printer.
  13265.  
  13266.      Syntax:   PUT <data item or *> TO <file number> {FOR <length>} {:error}
  13267.  
  13268.      data item or *      Any data item may be used.  If the data item is an
  13269.                          asterisk (*), then all enterable, unlocked fields on
  13270.                          the screen are moved to the file buffer, in the order
  13271.                          they appear on the screen, starting with the first
  13272.                          unprotected field on the screen.  The FOR clause is not
  13273.                          used here.
  13274.      TO                  Points to the file number designator
  13275.      file number         A valid open file.  Using a file number of 0 denotes
  13276.                          that the output is to be sent to the system list
  13277.                          device, instead of a disk file.
  13278.      FOR                 If the FOR clause is not given, then the data is output
  13279.                          for the full number of character positions it currently
  13280.                          occupies.  The FOR clause may be used to place blank
  13281.                          padding on the right, or to truncate the data item, as
  13282.                          appropriate.
  13283.      Remarks             PUT is not used when FID file data is being used.  A
  13284.                          special type of data item may be used to output control
  13285.                          characters to the file.  An at sign (@) denotes that
  13286.                          the following literal value is a control character to
  13287.                          be output.  This is useful when building files to be
  13288.                          later transmitted to a remote computer, or when using
  13289.                          special features of a printer.
  13290.  
  13291.                          For SDF files, all fields are output enclosed within
  13292.                          quotes and separated by commas.
  13293.  
  13294.      Examples:
  13295.           PUT PRODNUM TO 1
  13296.           PUT @09 TO 0
  13297.           PUT " " TO 0 FOR 10
  13298.           PUT #S0 TO 5  :1000
  13299.  
  13300.  
  13301.  
  13302.  
  13303.  
  13304.  
  13305.  
  13306.  
  13307.  
  13308.  
  13309.                                        Commands
  13310.                                        Page 208
  13311.  
  13312.  
  13313.  
  13314.  
  13315.  
  13316.  
  13317.  
  13318.                                   Q - PRO 4 Commands
  13319.  
  13320.  
  13321.      RCLEAR
  13322.      ------
  13323.      RCLEAR clears the record buffer to spaces and resets the buffer pointer.
  13324.  
  13325.      Syntax:   RCLEAR <file number> 
  13326.  
  13327.      file number         The file number of an open indexed or random file.
  13328.      Remarks             This command is not used with sequential files.
  13329.  
  13330.  
  13331.       
  13332.  
  13333.  
  13334.  
  13335.  
  13336.  
  13337.  
  13338.  
  13339.  
  13340.  
  13341.  
  13342.  
  13343.  
  13344.  
  13345.  
  13346.  
  13347.  
  13348.  
  13349.  
  13350.  
  13351.  
  13352.  
  13353.  
  13354.  
  13355.  
  13356.  
  13357.  
  13358.  
  13359.  
  13360.  
  13361.  
  13362.  
  13363.  
  13364.  
  13365.  
  13366.  
  13367.  
  13368.  
  13369.                                        Commands
  13370.                                        Page 209
  13371.  
  13372.  
  13373.  
  13374.  
  13375.  
  13376.  
  13377.  
  13378.                                   Q - PRO 4 Commands
  13379.  
  13380.  
  13381.      READ
  13382.      ----
  13383.      The READ command is used to access data records within a file.
  13384.  
  13385.      Syntax:   READ <file number> {NOADV} {:error}
  13386.  
  13387.      file number         If the file number pertains to a sequential input file,
  13388.                          then the file is advanced until a carriage return/line
  13389.                          feed sequence is bypassed.  The file is positioned at
  13390.                          the start of a new record, ready for GET statements.
  13391.  
  13392.                          For random or indexed files, the file buffer is loaded
  13393.                          with a new record, the fields of which can then be
  13394.                          accessed by referring to FID fields or with GET
  13395.                          statements.
  13396.      NOADV               If the NOADV keyword is given, the file is remains
  13397.                          positioned at the same record just read.  Otherwise,
  13398.                          the file position is incremented to point to the next
  13399.                          record in the file (applies to random and indexed files
  13400.                          only).  Using NOADV whenever possible will provide
  13401.                          optimal record access time.
  13402.      error               Errors are generated if there is an attempt to go past
  13403.                          the end of a file, or to access a record with a
  13404.                          non-existent key.
  13405.  
  13406.      Examples:
  13407.           READ 3 :1000
  13408.           READ 5 NOADV
  13409.  
  13410.  
  13411.  
  13412.      RENAME
  13413.      ------
  13414.      RENAME changes the name of a file.
  13415.  
  13416.      Syntax:   RENAME <old file name>, <new file name> {:error}
  13417.  
  13418.      old file name       The name of the file to be renamed.
  13419.      new file name       The new file name.
  13420.      error               An error occurs if the old file name is non-existent,
  13421.                          or if the new file name already exists.
  13422.      Remarks             The renamed file MUST NOT be open at the time of
  13423.                          renaming. 
  13424.  
  13425.      Examples:
  13426.           RENAME "B:TEMP.DAT","MASTER.DAT"
  13427.  
  13428.  
  13429.                                        Commands
  13430.                                        Page 210
  13431.  
  13432.  
  13433.  
  13434.  
  13435.  
  13436.  
  13437.  
  13438.                                   Q - PRO 4 Commands
  13439.  
  13440.  
  13441.           RENAME #S0,$FIELD[#N9]  :1013
  13442.      RESET
  13443.      -----
  13444.      RESET clears a Boolean flag register.  Refer to the IF statement for the
  13445.      use of Boolean registers in conditional statements.
  13446.  
  13447.      Syntax:   RESET <flag register>
  13448.  
  13449.      flag register       Any of the Boolean or flag registers from #B0 to #B9.
  13450.  
  13451.      Example:
  13452.           RESET #B4
  13453.  
  13454.  
  13455.  
  13456.  
  13457.  
  13458.  
  13459.  
  13460.  
  13461.  
  13462.  
  13463.  
  13464.  
  13465.  
  13466.  
  13467.  
  13468.  
  13469.  
  13470.  
  13471.  
  13472.  
  13473.  
  13474.  
  13475.  
  13476.  
  13477.  
  13478.  
  13479.  
  13480.  
  13481.  
  13482.  
  13483.  
  13484.  
  13485.  
  13486.  
  13487.  
  13488.  
  13489.                                        Commands
  13490.                                        Page 211
  13491.  
  13492.  
  13493.  
  13494.  
  13495.  
  13496.  
  13497.  
  13498.                                   Q - PRO 4 Commands
  13499.  
  13500.  
  13501.      RESTART
  13502.      -------
  13503.      RESTART places the file buffer pointer (moved across a file buffer by
  13504.      repeated GET or PUT statements) to an arbitrary position within a file
  13505.      buffer (does not apply to sequential files).
  13506.  
  13507.      Syntax:   RESTART <file number> {TO <position>}  {:error}
  13508.  
  13509.      file number         The number of the file to be restarted.  If the file
  13510.                          number is 0, then a form feed is issued to the list
  13511.                          device, and the position value (if any) is used to
  13512.                          space down the next page.  The page number register
  13513.                          (#P) is incremented, and the line number register (#L)
  13514.                          is set to the number of lines skipped on the new page
  13515.                          (default 0).
  13516.      position            The position within the record to move the pointer to.
  13517.      Remarks             The default value for pointer placement (taken when the
  13518.                          TO phrase is not given) is the start of the file
  13519.                          buffer.
  13520.  
  13521.      Examples:
  13522.           RESTART 0
  13523.           RESTART 1 TO 25
  13524.           RESTART 89
  13525.  
  13526.  
  13527.  
  13528.  
  13529.  
  13530.  
  13531.  
  13532.  
  13533.  
  13534.  
  13535.  
  13536.  
  13537.  
  13538.  
  13539.  
  13540.  
  13541.  
  13542.  
  13543.  
  13544.  
  13545.  
  13546.  
  13547.  
  13548.  
  13549.                                        Commands
  13550.                                        Page 212
  13551.  
  13552.  
  13553.  
  13554.  
  13555.  
  13556.  
  13557.  
  13558.                                   Q - PRO 4 Commands
  13559.  
  13560.  
  13561.      RESUME
  13562.      ------
  13563.      RESUME gives control back to the operator in the current screen data field.
  13564.  
  13565.      Syntax:   RESUME
  13566.  
  13567.  
  13568.  
  13569.  
  13570.  
  13571.  
  13572.  
  13573.  
  13574.  
  13575.  
  13576.  
  13577.  
  13578.  
  13579.  
  13580.  
  13581.  
  13582.  
  13583.  
  13584.  
  13585.  
  13586.  
  13587.  
  13588.  
  13589.  
  13590.  
  13591.  
  13592.  
  13593.  
  13594.  
  13595.  
  13596.  
  13597.  
  13598.  
  13599.  
  13600.  
  13601.  
  13602.  
  13603.  
  13604.  
  13605.  
  13606.  
  13607.  
  13608.  
  13609.                                        Commands
  13610.                                        Page 213
  13611.  
  13612.  
  13613.  
  13614.  
  13615.  
  13616.  
  13617.  
  13618.                                   Q - PRO 4 Commands
  13619.  
  13620.  
  13621.      RETURN
  13622.      ------
  13623.      RETURN gives programmatic control back to a calling procedure.  Each RETURN
  13624.      executed must be matched by a previous CALL statement.  It is possible,
  13625.      however, to exit from a FOR/ENDFOR loop to return to a calling statement
  13626.      (by executing a RETURN) with no ill effects.
  13627.  
  13628.      Syntax:   RETURN
  13629.        
  13630.      Examples:
  13631.           IF #N1 = 5 RETURN
  13632.           RETURN
  13633.  
  13634.  
  13635.  
  13636.  
  13637.  
  13638.  
  13639.  
  13640.  
  13641.  
  13642.  
  13643.  
  13644.  
  13645.  
  13646.  
  13647.  
  13648.  
  13649.  
  13650.  
  13651.  
  13652.  
  13653.  
  13654.  
  13655.  
  13656.  
  13657.  
  13658.  
  13659.  
  13660.  
  13661.  
  13662.  
  13663.  
  13664.  
  13665.  
  13666.  
  13667.  
  13668.  
  13669.                                        Commands
  13670.                                        Page 214
  13671.  
  13672.  
  13673.  
  13674.  
  13675.  
  13676.  
  13677.  
  13678.                                   Q - PRO 4 Commands
  13679.  
  13680.  
  13681.      RJUST
  13682.      -----
  13683.      RJUST right justifies data in any data item.
  13684.  
  13685.      Syntax:   RJUST <data item>
  13686.            
  13687.      data item      The data item in which data is to be right justified.
  13688.  
  13689.      Example:
  13690.           RJUST #S1
  13691.       
  13692.  
  13693.  
  13694.  
  13695.  
  13696.  
  13697.  
  13698.  
  13699.  
  13700.  
  13701.  
  13702.  
  13703.  
  13704.  
  13705.  
  13706.  
  13707.  
  13708.  
  13709.  
  13710.  
  13711.  
  13712.  
  13713.  
  13714.  
  13715.  
  13716.  
  13717.  
  13718.  
  13719.  
  13720.  
  13721.  
  13722.  
  13723.  
  13724.  
  13725.  
  13726.  
  13727.  
  13728.  
  13729.                                        Commands
  13730.                                        Page 215
  13731.  
  13732.  
  13733.  
  13734.  
  13735.  
  13736.  
  13737.  
  13738.                                   Q - PRO 4 Commands
  13739.  
  13740.  
  13741.      RLOCK
  13742.      -----
  13743.      On LANs and multiuser systems RLOCK marks the data record where the file is
  13744.      currently positioned as being locked.
  13745.  
  13746.      Syntax:   RLOCK <file number> {:error}
  13747.  
  13748.      file number         The file number of the record to be locked.
  13749.      error               If the record is marked as locked, presumably by
  13750.                          another user using the RLOCK command, a branch will be
  13751.                          taken to the error label.
  13752.      Remarks             The record locked is the one currently being pointed to
  13753.                          by the file pointer.  Thus these two command sequences
  13754.                          are the same:
  13755.  
  13756.                          POSN 1 TO #S0       POSN 1 TO #S0
  13757.                          RLOCK 1:LOCKED      READ 1 NOADV
  13758.                          READ 1              RLOCK 1:LOCKED
  13759.  
  13760.  
  13761.                          At NO TIME is the record physically locked.  As it is
  13762.                          always available to the programmer, it is up to the
  13763.                          programmer to take the appropriate action for the
  13764.                          application.  RLOCK is ignored by operating systems
  13765.                          that are not multiuser.  RLOCK is always used in
  13766.                          conjunction with RUNLOCK.
  13767.  
  13768.  
  13769.                          If a record is locked in a file, another RLOCK command
  13770.                          will unlock the previously locked record as well as
  13771.                          lock the current record.  Refer to the Programmer's
  13772.                          Reference Manual for more detail.
  13773.  
  13774.      Example
  13775.           RLOCK 1: 100
  13776.           RLOCK #N1:100
  13777.  
  13778.  
  13779.  
  13780.  
  13781.  
  13782.  
  13783.  
  13784.  
  13785.  
  13786.  
  13787.  
  13788.  
  13789.                                        Commands
  13790.                                        Page 216
  13791.  
  13792.  
  13793.  
  13794.  
  13795.  
  13796.  
  13797.  
  13798.                                   Q - PRO 4 Commands
  13799.  
  13800.  
  13801.      ROUND
  13802.      -----
  13803.      ROUND is used to round a numeric quantity to some significant number of
  13804.      digits.
  13805.  
  13806.      Syntax:   ROUND <data item 1> BY <size> INTO <data item 2>
  13807.  
  13808.      data item 1         Data item 1 (which must be numeric) will be rounded off
  13809.                          to the indicated number of significant fractional
  13810.                          digits.
  13811.      data item 2         The result will be placed into data item 2.
  13812.  
  13813.      Example:
  13814.           ROUND #N0 BY 2 INTO AVERAGE
  13815.           ROUND SUM BY SIGNIF INTO SUM
  13816.  
  13817.  
  13818.  
  13819.  
  13820.  
  13821.  
  13822.  
  13823.  
  13824.  
  13825.  
  13826.  
  13827.  
  13828.  
  13829.  
  13830.  
  13831.  
  13832.  
  13833.  
  13834.  
  13835.  
  13836.  
  13837.  
  13838.  
  13839.  
  13840.  
  13841.  
  13842.  
  13843.  
  13844.  
  13845.  
  13846.  
  13847.  
  13848.  
  13849.                                        Commands
  13850.                                        Page 217
  13851.  
  13852.  
  13853.  
  13854.  
  13855.  
  13856.  
  13857.  
  13858.                                   Q - PRO 4 Commands
  13859.  
  13860.  
  13861.      RUN
  13862.      ---
  13863.      The RUN command executes another program directly from Q-PRO 4,  and
  13864.      (normally) returns to the same format file when the loaded program is done.
  13865.  
  13866.      Syntax:   RUN <program name> USING <parameter string> {NORETURN} {NOPAUSE}
  13867.      {RELOAD <name>} {:error}
  13868.  
  13869.      program name        The program named may be a literal or string data item
  13870.                          containing the name of any valid program.
  13871.      parameter string    The parameter string is a literal or string data item
  13872.                          which contains whatever parameters the program would be
  13873.                          given if executed from the system command level.  If
  13874.                          there is NO PARAMETER to be passed, then a null
  13875.                          argument should be used.
  13876.      Remarks             RUN permits the re-execution of Q-PRO 4 automatically. 
  13877.                          As control is turned over to another executable
  13878.                          program, any working values that the current Q-PRO4
  13879.                          application program was using (such as registers,
  13880.                          variables, etc) will be lost.  Files are automatically
  13881.                          closed.
  13882.  
  13883.           Keywords
  13884.           --------
  13885.  
  13886.           NORETURN       Q-PRO 4 is not re-executed upon completion of the
  13887.                          loaded program.
  13888.           NOPAUSE        Control will return to Q-PRO 4 without operator
  13889.                          intervention.
  13890.  
  13891.           RELOAD<file>   Control will go to the named Q-PRO 4 filename.
  13892.  
  13893.  
  13894.      Examples:
  13895.           RUN "WORDSTAR.EXE" USING "LETTERS.DAT"
  13896.           RUN "PIP.COM" USING "B:OLD=B:NEW" NORETURN
  13897.           RUN "REPORT.CMD" USING #S1
  13898.           RUN "\COMMAND.COM" USING "/C COPY \DATA\CUSTOMER.DAT
  13899.                \BACKUP\CUSTOMER.DAT" RELOAD "MENU.QNE"
  13900.           RUN "WORDSTAR.EXE" USING "" 
  13901.  
  13902.  
  13903.  
  13904.  
  13905.  
  13906.  
  13907.  
  13908.  
  13909.                                        Commands
  13910.                                        Page 218
  13911.  
  13912.  
  13913.  
  13914.  
  13915.  
  13916.  
  13917.  
  13918.                                   Q - PRO 4 Commands
  13919.  
  13920.  
  13921.      RUNLOCK
  13922.      -------
  13923.      On a LAN or multiuser operating system RUNLOCK unlocks the record currently
  13924.      marked as locked for a file.
  13925.  
  13926.      Syntax:   RUNLOCK <file number> {:error}
  13927.  
  13928.      file number         The file number, a literal or string data item, which
  13929.                          is to have the record unlocked.
  13930.  
  13931.      Remarks             RUNLOCK is ignored if there is no locked record. 
  13932.                          RUNLOCK is always used in conjunction with RLOCK.
  13933.  
  13934.      Example:
  13935.           RUNLOCK 1100
  13936.  
  13937.  
  13938.  
  13939.  
  13940.  
  13941.  
  13942.  
  13943.  
  13944.  
  13945.  
  13946.  
  13947.  
  13948.  
  13949.  
  13950.  
  13951.  
  13952.  
  13953.  
  13954.  
  13955.  
  13956.  
  13957.  
  13958.  
  13959.  
  13960.  
  13961.  
  13962.  
  13963.  
  13964.  
  13965.  
  13966.  
  13967.  
  13968.  
  13969.                                        Commands
  13970.                                        Page 219
  13971.  
  13972.  
  13973.  
  13974.  
  13975.  
  13976.  
  13977.  
  13978.                                   Q - PRO 4 Commands
  13979.  
  13980.  
  13981.      SECURE
  13982.      ------
  13983.      Use of SECURE in conjunction with WRITE or FREE will guard against loss of
  13984.      data because of power loss, etc.
  13985.  
  13986.      The price of safety is extra time spent updating the file (one sector read,
  13987.      one sector written) and updating the system directory for the disk on which
  13988.      the file is located.
  13989.  
  13990.      Syntax:   SECURE <file number> {:error}
  13991.  
  13992.      file number         The file number to be secured.
  13993.      Remarks             SECURE has no effect on sequential or random files.
  13994.  
  13995.      Example:
  13996.           SECURE 1
  13997.           SECURE #N[FILENO]SET
  13998.  
  13999.  
  14000.      SET
  14001.      ---
  14002.      SET sets or turns on a Boolean or flag register.
  14003.  
  14004.      Syntax:   SET <Boolean register>
  14005.  
  14006.      Boolean register    The register number from #B0 to #B9.
  14007.      Remarks             Refer to the IF statement for the use of Boolean
  14008.                          registers in conditional statements.
  14009.  
  14010.      Example:
  14011.           SET #B0
  14012.           SET #B9
  14013.  
  14014.  
  14015.  
  14016.  
  14017.  
  14018.  
  14019.  
  14020.  
  14021.  
  14022.  
  14023.  
  14024.  
  14025.  
  14026.  
  14027.  
  14028.  
  14029.                                        Commands
  14030.                                        Page 220
  14031.  
  14032.  
  14033.  
  14034.  
  14035.  
  14036.  
  14037.  
  14038.                                   Q - PRO 4 Commands
  14039.  
  14040.  
  14041.      SETDATE
  14042.      -------
  14043.      SETDATE sets the system date.
  14044.  
  14045.      Syntax:   SETDATE <date string>
  14046.  
  14047.      date string         The date to set the system to as a literal or valid
  14048.                          string data item of the format:
  14049.  
  14050.                               MM/DD/YYYY hh:mm:ss
  14051.  
  14052.                               MM = MONTH     hh = hours
  14053.                               DD = DAY       mm = minutes
  14054.                               YYYY = YEAR    ss = seconds
  14055.  
  14056.      Remarks             On PCDOS and MSDOS this will set the system date.  On
  14057.                          all others, the date will be stored in a system
  14058.                          register for later use.  The register will be preserved
  14059.                          across CHAINs (BUT NOT RUNs).  A literal or string data
  14060.                          item may be used.  Refer also to GETDATE.
  14061.  
  14062.      Examples:
  14063.           SETDATE "08/31/1987 11:23:45"
  14064.           SETDATE #S1
  14065.  
  14066.  
  14067.  
  14068.      SIZE
  14069.      ----
  14070.      SIZE computes the length of a string data item.
  14071.  
  14072.      Syntax:   SIZE <data item 1> INTO <data item 2> {TRIMMED}
  14073.  
  14074.      data item 1         Data item 1 is the string register, field, or variable
  14075.                          to be sized.
  14076.      data item 2         Data item 2 is the numeric register, field, or variable
  14077.                          into which the size should be placed.
  14078.      Remarks             Note that unlike string registers, fields and variables
  14079.                          will always give the same result unless the TRIMMED
  14080.                          form is used to drop trailing spaces, since by nature
  14081.                          fields and variables are of fixed length.
  14082.  
  14083.      Example:
  14084.           SIZE #S0 INTO #N0
  14085.           SIZE APPLE INTO WATERMELON TRIMMED
  14086.  
  14087.  
  14088.  
  14089.                                        Commands
  14090.                                        Page 221
  14091.  
  14092.  
  14093.  
  14094.  
  14095.  
  14096.  
  14097.  
  14098.                                   Q - PRO 4 Commands
  14099.  
  14100.  
  14101.      SUB
  14102.      ---
  14103.      SUB subtracts one numeric data item from another and, optionally, leaves
  14104.      the result in a third.
  14105.  
  14106.      Syntax:   SUB <dataitem1> FROM <dataitem2> {GIVING <dataitem3>}
  14107.  
  14108.      dataitem1           The number or numeric data item to be subtracted.
  14109.      dataitem2           The numeric data item to be subtracted from.
  14110.      GIVING              If the GIVING clause is not present, then the result is
  14111.                          stored in data item 2.
  14112.      Remarks             The keyword FROM may be replaced by a comma.
  14113.  
  14114.      Example:
  14115.           SUB 5 FROM RESULT GIVING NEWRES
  14116.           SUB 1 FROM COUNT
  14117.           SUB #N0 FROM #N1 GIVING #N2
  14118.  
  14119.  
  14120.  
  14121.  
  14122.  
  14123.  
  14124.  
  14125.  
  14126.  
  14127.  
  14128.  
  14129.  
  14130.  
  14131.  
  14132.  
  14133.  
  14134.  
  14135.  
  14136.  
  14137.  
  14138.  
  14139.  
  14140.  
  14141.  
  14142.  
  14143.  
  14144.  
  14145.  
  14146.  
  14147.  
  14148.  
  14149.                                        Commands
  14150.                                        Page 222
  14151.  
  14152.  
  14153.  
  14154.  
  14155.  
  14156.  
  14157.  
  14158.                                   Q - PRO 4 Commands
  14159.  
  14160.  
  14161.      SYSMODE
  14162.      -------
  14163.      SYSMODE is a system initiating command.  It has two modifiers:
  14164.  
  14165.      Syntax 1:      SYSMODE BTAB <SET or RESET>
  14166.  
  14167.      SET            SYSMODE BTAB SET specifies that a proc in a screen data
  14168.                     field that the cursor is backtabbed out of is always
  14169.                     executed.
  14170.      RESET          SYSMODE BTAB RESET specifies that a proc is not executed if
  14171.                     there is no data (default mode) in the screen data field and
  14172.                     the cursor is backtabbed out of it.
  14173.  
  14174.      Examples:
  14175.           SYSMODE BTAB SET
  14176.           SYSMODE BTAB RESET
  14177.  
  14178.      Syntax 2:      SYSMODE LPCHK <SET  or RESET>
  14179.  
  14180.      SET            On LPCHK SET the system level list device error, not the
  14181.                     Q-PRO 4 generated error, will be displayed on the screen on
  14182.                     a list device error.  This is very useful if you are
  14183.                     redirecting the output to a device other than the parallel
  14184.                     printer, so that Q-PRO 4 will not check the status.  If you
  14185.                     don't have LPCHK SET and go to the serial printer, Q-PRO 4
  14186.                     may report the printer not ready.  
  14187.      RESET          On LPCHK RESET, the Q-PRO 4 error will be displayed.  This
  14188.                     is the default mode.
  14189.      Remarks        A single SYSMODE statement can use either BTAB or LPCHK but
  14190.                     not both.  LPCHK is used for DOS and MS-DOS only.Use
  14191.                     separate SYSMODE statements for each one.
  14192.  
  14193.  
  14194.  
  14195.  
  14196.  
  14197.  
  14198.  
  14199.  
  14200.  
  14201.  
  14202.  
  14203.  
  14204.  
  14205.  
  14206.  
  14207.  
  14208.  
  14209.                                        Commands
  14210.                                        Page 223
  14211.  
  14212.  
  14213.  
  14214.  
  14215.  
  14216.  
  14217.  
  14218.                                   Q - PRO 4 Commands
  14219.  
  14220.  
  14221.      SYSTEM
  14222.      ------
  14223.      The SYSTEM command returns control to the operating system.
  14224.  
  14225.      Syntax:   SYSTEM 
  14226.  
  14227.      Remarks        If the FORMLOAD flag was set, control will then be passed to
  14228.                     the format builder utility.
  14229.  
  14230.      Example:
  14231.           SYSTEM
  14232.  
  14233.  
  14234.  
  14235.  
  14236.  
  14237.  
  14238.  
  14239.  
  14240.  
  14241.  
  14242.  
  14243.  
  14244.  
  14245.  
  14246.  
  14247.  
  14248.  
  14249.  
  14250.  
  14251.  
  14252.  
  14253.  
  14254.  
  14255.  
  14256.  
  14257.  
  14258.  
  14259.  
  14260.  
  14261.  
  14262.  
  14263.  
  14264.  
  14265.  
  14266.  
  14267.  
  14268.  
  14269.                                        Commands
  14270.                                        Page 224
  14271.  
  14272.  
  14273.  
  14274.  
  14275.  
  14276.  
  14277.  
  14278.                                   Q - PRO 4 Commands
  14279.  
  14280.  
  14281.      TABLE
  14282.      -----
  14283.      The TABLE statement denotes the start of a data table.
  14284.  
  14285.      Syntax:        TABLE <table name>
  14286.  
  14287.      table name     The name of table as a literal without quotes.
  14288.      Remarks        See the Programmer's Reference Manual for more detail on
  14289.                     handling tables.
  14290.  
  14291.      Example:
  14292.           TABLE STATES
  14293.           "PA"
  14294.           "NJ"
  14295.           "NY"
  14296.           "DE"
  14297.           END
  14298.  
  14299.      TABLE CUSTTYPE
  14300.           0,  "DEADBEAT"
  14301.           1,  "OEM"
  14302.           2,  "DIST."
  14303.           3,  "RETAILER"
  14304.           END
  14305.  
  14306.      TABLE PROCS
  14307.           PROCA
  14308.           PROCB
  14309.           PROCC
  14310.           END
  14311.  
  14312.      TABLE LABELS
  14313.           100
  14314.           200
  14315.           300
  14316.           END
  14317.  
  14318.  
  14319.  
  14320.  
  14321.  
  14322.  
  14323.  
  14324.  
  14325.  
  14326.  
  14327.  
  14328.  
  14329.                                        Commands
  14330.                                        Page 225
  14331.  
  14332.  
  14333.  
  14334.  
  14335.  
  14336.  
  14337.  
  14338.                                   Q - PRO 4 Commands
  14339.  
  14340.  
  14341.      TRACE
  14342.      -----
  14343.      The runtime execution of a program may monitored by executing the TRACE
  14344.      command.
  14345.  
  14346.      Syntax:   TRACE
  14347.  
  14348.      Remarks             Trace places the system into a "debugging" mode.  In
  14349.                          this mode, each statement is displayed on the last line
  14350.                          of the screen just before its execution.  When the user
  14351.                          presses the ESC key, the statement is executed.  This
  14352.                          allows the user to single-step through sections of
  14353.                          code.
  14354.  
  14355.                          Trace mode is turned off by the NOTRACE statement or by
  14356.                          pressing the RETURN key instead of the ESC key.  When
  14357.                          TRACE is on, pressing "D" instead of ESC will invoke
  14358.                          DEBUG after the execution of the instruction displayed
  14359.                          on the screen.
  14360.  
  14361.  
  14362.  
  14363.  
  14364.  
  14365.  
  14366.  
  14367.  
  14368.  
  14369.  
  14370.  
  14371.  
  14372.  
  14373.  
  14374.  
  14375.  
  14376.  
  14377.  
  14378.  
  14379.  
  14380.  
  14381.  
  14382.  
  14383.  
  14384.  
  14385.  
  14386.  
  14387.  
  14388.  
  14389.                                        Commands
  14390.                                        Page 226
  14391.  
  14392.  
  14393.  
  14394.  
  14395.  
  14396.  
  14397.  
  14398.                                   Q - PRO 4 Commands
  14399.  
  14400.  
  14401.      TSEAR
  14402.      -----
  14403.      The TSEAR command allows the search of a table and, optionally, the
  14404.      extraction of data from the table once a if a match for the search argument
  14405.      is found in the first column of the table.
  14406.  
  14407.      Syntax:   TSEAR <table name> AT <key> {,<data item list>} {:error}
  14408.  
  14409.      table name          The name of the table to be searched.
  14410.      key                 The data item which will be compared to the first
  14411.                          element of each line of the table for an exact match. 
  14412.                          To achieve a match, the types of the two keys must be
  14413.                          compatible (string-string or numeric-numeric). If a
  14414.                          match is not found after the first element of every
  14415.                          line is compared, the error branch is taken.
  14416.      data item list      If a match is found, then an item by item data trans-
  14417.                          ferral occurs from the data on the rest of the table
  14418.                          line.
  14419.      Remarks             The TSEAR command can also be used without the data
  14420.                          item list simply to verify the acceptability of an
  14421.                          entry for special codes, etc.  Note that a table used
  14422.                          for indexed procedures or labels cannot be used for the
  14423.                          TSEAR command, since they do not contain a key for
  14424.                          searching.  Refer to Programmer's Reference Manual for
  14425.                          a more complete discussion of table usage.
  14426.  
  14427.  
  14428.      Examples:
  14429.           TSEAR CODETBL AT USERCODE,USERTYPE :100
  14430.                Searches the table CODETBL with the argument in the field (or
  14431.                variable) USERCODE.  If there is a match in the first column of
  14432.                the table and USERCODE, the next element of the table will be
  14433.                placed in the field (or variable) USERTYPE.  If there is no match
  14434.                in the first column of the table with the contents of USERCODE,
  14435.                control goes to 100.
  14436.  
  14437.           TSEAR TRANTBL AT TRANCODE :1023
  14438.  
  14439.  
  14440.  
  14441.  
  14442.  
  14443.  
  14444.  
  14445.  
  14446.  
  14447.  
  14448.  
  14449.                                        Commands
  14450.                                        Page 227
  14451.  
  14452.  
  14453.  
  14454.  
  14455.  
  14456.  
  14457.  
  14458.                                   Q - PRO 4 Commands
  14459.  
  14460.  
  14461.      UCASE
  14462.      -----
  14463.      UCASE forces a string data item to upper case.
  14464.  
  14465.      Syntax:   UCASE <data item>
  14466.  
  14467.      data item           This must be a string data item.
  14468.  
  14469.      Example:
  14470.           UCASE #S5
  14471.           UCASE NAME
  14472.  
  14473.  
  14474.  
  14475.  
  14476.  
  14477.  
  14478.  
  14479.  
  14480.  
  14481.  
  14482.  
  14483.  
  14484.  
  14485.  
  14486.  
  14487.  
  14488.  
  14489.  
  14490.  
  14491.  
  14492.  
  14493.  
  14494.  
  14495.  
  14496.  
  14497.  
  14498.  
  14499.  
  14500.  
  14501.  
  14502.  
  14503.  
  14504.  
  14505.  
  14506.  
  14507.  
  14508.  
  14509.                                        Commands
  14510.                                        Page 228
  14511.  
  14512.  
  14513.  
  14514.  
  14515.  
  14516.  
  14517.  
  14518.                                   Q - PRO 4 Commands
  14519.  
  14520.  
  14521.      UNEDIT
  14522.      ------
  14523.      UNEDIT removes editing characters from a string field such as dollar sign
  14524.      ($) and comma (,) which usually have been placed there by the EDIT command.
  14525.  
  14526.      Syntax:   UNEDIT <string data item> INTO <data item>
  14527.  
  14528.      string data item    The string data item to be UNEDITed.
  14529.      data item           Where the UNEDITED data will be placed.
  14530.  
  14531.      Example:
  14532.           UNEDIT FIELD INTO #N1
  14533.  
  14534.  
  14535.  
  14536.  
  14537.  
  14538.  
  14539.  
  14540.  
  14541.  
  14542.  
  14543.  
  14544.  
  14545.  
  14546.  
  14547.  
  14548.  
  14549.  
  14550.  
  14551.  
  14552.  
  14553.  
  14554.  
  14555.  
  14556.  
  14557.  
  14558.  
  14559.  
  14560.  
  14561.  
  14562.  
  14563.  
  14564.  
  14565.  
  14566.  
  14567.  
  14568.  
  14569.                                        Commands
  14570.                                        Page 229
  14571.  
  14572.  
  14573.  
  14574.  
  14575.  
  14576.  
  14577.  
  14578.                                   Q - PRO 4 Commands
  14579.  
  14580.  
  14581.      UNLOCK
  14582.      ------
  14583.      The UNLOCK command unlocks a previously locked field, and makes it
  14584.      available for operator entry again.
  14585.  
  14586.      Syntax:   UNLOCK <screen data field name or *>
  14587.  
  14588.      screen data field or *   The name of the screen data field to unlock or a
  14589.                               $FIELD function.  If * is used instead of a
  14590.                               specific screen field name, all locked fields are
  14591.                               unlocked.
  14592.  
  14593.      Examples:
  14594.           UNLOCK DATE
  14595.           UNLOCK *
  14596.  
  14597.  
  14598.  
  14599.  
  14600.  
  14601.  
  14602.  
  14603.  
  14604.  
  14605.  
  14606.  
  14607.  
  14608.  
  14609.  
  14610.  
  14611.  
  14612.  
  14613.  
  14614.  
  14615.  
  14616.  
  14617.  
  14618.  
  14619.  
  14620.  
  14621.  
  14622.  
  14623.  
  14624.  
  14625.  
  14626.  
  14627.  
  14628.  
  14629.                                        Commands
  14630.                                        Page 230
  14631.  
  14632.  
  14633.  
  14634.  
  14635.  
  14636.  
  14637.  
  14638.                                   Q - PRO 4 Commands
  14639.  
  14640.  
  14641.      VRBL
  14642.      ----
  14643.      The VRBL statement establishes in-memory variables which can be used in
  14644.      exactly the same manner as screen fields, except that as their value
  14645.      changes, no change is made to the screen display.
  14646.  
  14647.      Syntax:   VRBL <name>, <type>, <length> {,<dimension>}  
  14648.  
  14649.      name           Any alphanumeric data item conforming to the Q-PRO 4 naming
  14650.                     conventions.  The name must not already be in use for
  14651.                     another variable or field.
  14652.      type           Must be an X (for string) or N (for numeric).   Note that
  14653.                     both types of variables are stored in ASCII format, enabling
  14654.                     both string and numeric types of operations on numeric
  14655.                     variables, depending on the statement involved.
  14656.      length         From 1 to 255 characters long for string variables, and from
  14657.                     1 to 20 for numeric variables.
  14658.      dimension      Specifies how many elements of <length> size will be
  14659.                     established.  The default dimension is 1.  The given
  14660.                     dimension may be from 1 to 65,000. 
  14661.  
  14662.      Remarks        Undimensioned variables are referenced exactly like fields,
  14663.                     that is, directly by name.  Dimensioned variables are
  14664.                     referenced by name and element number within brackets.  The
  14665.                     element number may be any numeric expression from 0 to the
  14666.                     number of elements minus 1.
  14667.       
  14668.                     The ideal place to declare variables is in PROC LOAD, since
  14669.                     variables must be declared, may only be declared once, and
  14670.                     are not retained across a CHAIN operation.
  14671.  
  14672.      Examples:
  14673.           VRBL PETE,  X, 10
  14674.                10-character string
  14675.  
  14676.           VRBL FIVE , N, 5, 20
  14677.                20 element array of 5-character numerics
  14678.  
  14679.  
  14680.           VRBL I, N, 4
  14681.           VRBL SARY, X, 80, 12
  14682.                .
  14683.           FOR I=0 TO 11
  14684.                MOVE "" TO SARY[I]
  14685.           ENDFOR I
  14686.                Clear the contents of a string array, using a variable as a loop
  14687.  
  14688.  
  14689.                                        Commands
  14690.                                        Page 231
  14691.  
  14692.  
  14693.  
  14694.  
  14695.  
  14696.  
  14697.  
  14698.                                   Q - PRO 4 Commands
  14699.  
  14700.  
  14701.                counter.
  14702.      WRITE
  14703.      -----
  14704.      WRITE outputs a data record to a file or issues a carriage return line feed
  14705.      to the printer.
  14706.  
  14707.      Syntax:   WRITE <file number> {NOADV} {:error}
  14708.  
  14709.      file number         The file number of the record to be written.
  14710.      NOADV               If the NOADV keyword is given (for random and indexed
  14711.                          files only), the record position in the file is not
  14712.                          advanced.  Otherwise, the record positioned is advanced
  14713.                          to the next position in the file.  Using NOADV whenever
  14714.                          possible will provide optimal record access time.
  14715.  
  14716.           Actions of WRITE With Various File Types
  14717.           ----------------------------------------
  14718.  
  14719.           Sequential files
  14720.                A data record is written and terminated by a carriage return/line
  14721.                feed sequence.
  14722.  
  14723.           Random files
  14724.                The record is written to the current position of the file.
  14725.  
  14726.           Indexed files
  14727.                The record is written to the position defined by the key of the
  14728.                record.  A POSN command before an indexed file write is therefore
  14729.                both unnecessary and wasteful.
  14730.  
  14731.           List device
  14732.                If the file number is 0, then a carriage return/line feed
  14733.                sequence is output to the list device.  The line number register
  14734.                (#L) will then be incremented automatically.
  14735.  
  14736.  
  14737.  
  14738.      Examples:
  14739.           WRITE 0
  14740.           WRITE 1 NOADV :122
  14741.  
  14742.  
  14743.  
  14744.  
  14745.  
  14746.  
  14747.  
  14748.  
  14749.                                        Commands
  14750.                                        Page 232
  14751.  
  14752.  
  14753.  
  14754.  
  14755.  
  14756.  
  14757.  
  14758.                                   Q - PRO 4 Commands
  14759.  
  14760.  
  14761.                        Q - P R O 4  E R R O R   M E S S A G E S
  14762.                        ========================================
  14763.  
  14764.                                    Trappable Errors
  14765.                                    ================
  14766.  
  14767.      #N0 Value           Message
  14768.      ---------           --------
  14769.            1        BAD DATA IN FIELD
  14770.            2        BAD SIGNED RESULT
  14771.            3        BAD OPERAND
  14772.            4        ARITHMETIC OVERFLOW
  14773.            5        NO TABLE MATCH
  14774.            6        FILE UNAVAILABLE
  14775.            7        FILE NOT OPEN
  14776.            8        BUFFER OVERFLOW
  14777.            9        OUTPUT FILE ONLY
  14778.           10        END OF RECORD
  14779.           11        END OF FILE
  14780.           12        INPUT FILE ONLY
  14781.           13        BAD DEST. START
  14782.           14        BAD REC POSN
  14783.           15        BAD INDEXED FILE
  14784.           16        NO SUCH FILE
  14785.           17        BAD FORMAT DESCRIPTOR
  14786.           18        NO DATA IN BUFFER
  14787.           19        BAD FILE NAME
  14788.           20        DISK IO ERROR
  14789.           21        NO FID FILE
  14790.           22        BAD FID FILE
  14791.           23        BAD FID ITEM INDEX
  14792.           24        MEMORY OVERFLOW ON MEMEND
  14793.           25        FILE EXCLUSION LOCK FAILED
  14794.           26        FILE SYNCH. FAILURE
  14795.           27        BAD HOST STATEMENT
  14796.           28        FILE READ ONLY
  14797.           29        EXEC ERROR
  14798.           30        LINE PRINTER ERROR (16 bit only)
  14799.           31        MATHLIB (8 bit only)
  14800.           33        FILE SYSTEM NOT LOADED
  14801.           34        DELETED RECORD READ
  14802.  
  14803.  
  14804.  
  14805.  
  14806.  
  14807.  
  14808.  
  14809.                                     Error Messages
  14810.                                        Page 233
  14811.  
  14812.  
  14813.  
  14814.  
  14815.  
  14816.  
  14817.  
  14818.                                   Q - PRO 4 Commands
  14819.  
  14820.  
  14821.                                   Error Codes for #E
  14822.                                   ------------------
  14823.  
  14824.      Error numbers found in #E under DOS are interpreted as follows:
  14825.  
  14826.           #E Value            Message
  14827.           --------         -----------
  14828.                 1        data file open
  14829.                 2        data file creation error
  14830.                 3        data file read error
  14831.                 4        data file write error
  14832.                 5        data close error
  14833.                 6        FID file open
  14834.                 7        FID file read error
  14835.                 8        FID file wrong version
  14836.                 9        Out of memory
  14837.                10        Index file error
  14838.                11        Error during handle reuse
  14839.                12        error during file system initialization
  14840.                13        data file less than the minimum length (8 characters)
  14841.                14        Unable to unlock record
  14842.                15        (reserved)
  14843.                16        Maximum indices exceeded (100 allowed)
  14844.                17        Not enough handles
  14845.                18        Activity tried on inactive file.
  14846.               100        End of file
  14847.               101        (Reserved)
  14848.               102        Illegal function on file (deleting a random record)
  14849.               103        Deleting a record before a read
  14850.               104        (Reserved)
  14851.               105        File read only
  14852.               106        Bad host value
  14853.               107        Record locked
  14854.               108        Header busy (try again)
  14855.               109        Deleted record read
  14856.               110        Bad key description list
  14857.  
  14858.  
  14859.  
  14860.  
  14861.  
  14862.  
  14863.  
  14864.  
  14865.  
  14866.  
  14867.  
  14868.  
  14869.                                     Error Messages
  14870.                                        Page 234
  14871.  
  14872.  
  14873.  
  14874.  
  14875.  
  14876.  
  14877.  
  14878.                                   Q - PRO 4 Commands
  14879.  
  14880.  
  14881.                          Cross Reference of Trappable Errors
  14882.                          ===================================
  14883.  
  14884.                           #N0                 #E
  14885.           Value          Error               Value
  14886.           ---------------------------------------
  14887.            6        File unavailable         1,2
  14888.           11        End of file              100
  14889.           18        No data in buffer        103
  14890.           21        No FID file                6
  14891.           22        Bad FID file             7,8
  14892.           24        Memory overflow            9
  14893.           25        File exclusion lock      107, 108
  14894.           27        Bad host statement       106
  14895.            8        File read only           105
  14896.           34        Deleted record read      109
  14897.           20        All other disk I/O errors  3
  14898.  
  14899.  
  14900.  
  14901.                                      BTSYS Errors
  14902.                                      ============
  14903.  
  14904.      These errors are reported as "C-Tree" errors.
  14905.  
  14906.           Error Number              Description
  14907.                231       A data file index is so corrupted that the file handler
  14908.                          cannot proceed any further.  The only recover is using
  14909.                          QMAINT to recover the file.
  14910.  
  14911.                230       This is a different error with the same cause and
  14912.                          solution as the one above.
  14913.  
  14914.       
  14915.  
  14916.  
  14917.  
  14918.  
  14919.  
  14920.  
  14921.  
  14922.  
  14923.  
  14924.  
  14925.  
  14926.  
  14927.  
  14928.  
  14929.                                     Error Messages
  14930.                                        Page 235
  14931.  
  14932.  
  14933.  
  14934.  
  14935.  
  14936.  
  14937.  
  14938.                                   Q - PRO 4 Commands
  14939.  
  14940.  
  14941.                               Error Message Descriptions
  14942.                               ==========================
  14943.  
  14944.      The following is a complete list of error messages generated by the Q-PRO 4
  14945.      system (in programs FB and QNE). Certain of the error messages generated by
  14946.      the run-time system (QNE) are either recoverable by the operator (by
  14947.      pressing ESCAPE), or are programmatically trappable. Otherwise, all
  14948.      run-time errors are fatal.
  14949.  
  14950.      , EXPECTED
  14951.      Statement syntax requires a comma.
  14952.  
  14953.      = EXPECTED
  14954.      Statement syntax required an equals sign, and there was none.
  14955.  
  14956.      " EXPECTED
  14957.      Statement contains unbalanced quotes.
  14958.  
  14959.      ] EXPECTED
  14960.      Statement contains unbalanced brackets.
  14961.  
  14962.      [ EXPECTED
  14963.      Statement syntax requires a left bracket, and none was found.
  14964.  
  14965.      ARITHMETIC OVERFLOW
  14966.      Attempt made to perform invalid calculation (such as divide by zero).
  14967.      Trappable globally as error 4.
  14968.  
  14969.      AT EXPECTED
  14970.      Statement syntax requires the keyword "at".
  14971.  
  14972.      BAD BUFFER SIZE
  14973.      An invalid value (greater than 255) as given as the keyboard buffer size in
  14974.      a BUFFER statement.
  14975.  
  14976.      BAD COMMAND STRING
  14977.      An invalid command string was given in a SYSTEM command.
  14978.  
  14979.      BAD CONDITION
  14980.      Unrecognizable condition in IF statement, or attempted to compare a number
  14981.      to a string.
  14982.  
  14983.      BAD DATA IN FIELD
  14984.      Non-numeric data exists in field (usually put there programmatically). 
  14985.      Trappable globally as error 1.
  14986.  
  14987.  
  14988.  
  14989.                                     Error Messages
  14990.                                        Page 236
  14991.  
  14992.  
  14993.  
  14994.  
  14995.  
  14996.  
  14997.  
  14998.                                   Q - PRO 4 Commands
  14999.  
  15000.  
  15001.  
  15002.      BAD DEST. START
  15003.      Program attempted a partial move from past the end of a string. Trappable
  15004.      globally as error 13.
  15005.  
  15006.      BAD EXPRESSION
  15007.      Statement contained an invalid arithmetic expression.
  15008.  
  15009.      BAD FID FILE
  15010.      An invalid file was attempted for use as a fid file.
  15011.  
  15012.      BAD FID ITEM INDEX
  15013.      An out-of-range value was given for a fid field index.
  15014.  
  15015.      BAD FIELD FILL
  15016.      Numeric calculation not possible with a numeric field whose fill character
  15017.      is other that a blank or a digit.
  15018.  
  15019.      BAD FILE FORMAT
  15020.      Locked file format was not correct.
  15021.  
  15022.      BAD FILE NAME
  15023.      Program attempted to OPEN or MAKE a file with an invalid given name. 
  15024.      Trappable locally in OPEN and MAKE.  Trappable globally as error 19.
  15025.  
  15026.      BAD FILE NUMBER
  15027.      Program attempted to OPEN or MAKE a file with a number less than 1 or
  15028.      greater than 255.
  15029.  
  15030.      BAD FILE TYPE
  15031.      Program attempted to OPEN or MAKE a file with a type not in the range 0-5.
  15032.  
  15033.      BAD FLAG REGISTER REFERENCE
  15034.      Flag register reference expected.
  15035.  
  15036.      BAD FORMAT DESCRIPTOR
  15037.      Program attempted to EDIT a numeric data item with an invalid descriptor. 
  15038.      Trappable locally in EDIT. Trappable globally as error 17.
  15039.  
  15040.      BAD FUNCTION KEY
  15041.      Undefined or non-numeric function (escape) key sequence was pressed. 
  15042.      Recoverable.
  15043.  
  15044.      BAD HOST STATEMENT
  15045.      A host statement was executed which either did not have a recognizable name
  15046.      or at a time when all files were not closed.  Trappable as error 27.
  15047.  
  15048.  
  15049.                                     Error Messages
  15050.                                        Page 237
  15051.  
  15052.  
  15053.  
  15054.  
  15055.  
  15056.  
  15057.  
  15058.                                   Q - PRO 4 Commands
  15059.  
  15060.  
  15061.  
  15062.  
  15063.      BAD INDEXED 
  15064.      Program attempted to OPEN a file with an invalid internal format as an
  15065.      indexed file. Trappable locally in OPEN.  Trappable globally as error 15.
  15066.  
  15067.      BAD INDEX LENGTH
  15068.      Program attempted to MAKE a file whose index length takes the key out of
  15069.      the first 128 bytes of the data record.
  15070.  
  15071.      BAD INDEX START 
  15072.      Program attempted to MAKE a file whose index start was greater than 128.
  15073.  
  15074.      BAD KEYSTROKE IN FIELD
  15075.      Operator keyed an invalid character for the field type.  Recoverable.
  15076.  
  15077.      BAD MODIFIER
  15078.      Invalid string starting position in MOVE modifier.
  15079.  
  15080.      BAD OPERAND
  15081.      Program attempted to store into an invalid data item. Trappable globally as
  15082.      error 3.
  15083.  
  15084.      BAD PROC FORMAT
  15085.      Illegal PROC statement.
  15086.  
  15087.      BAD PROC NAME IN FILE
  15088.      Program contains an invalid or missing procedure reference.
  15089.  
  15090.      BAD REC POSN
  15091.      Invalid value given for a record number.  Trappable locally in POSN. 
  15092.      Trappable globally as error 14.
  15093.  
  15094.      BAD REC SIZE
  15095.      Record size may not be 0.
  15096.  
  15097.      BAD REGISTER
  15098.      Program attempted to do a modified MOVE from a numeric register.
  15099.  
  15100.      BAD SIGNED RESULT
  15101.      Program attempted to put a negative number in a digit (D descriptor )
  15102.      field. Trappable globally as error 2.
  15103.  
  15104.      BAD STATEMENT
  15105.      Statement is unrecognizable.
  15106.  
  15107.  
  15108.  
  15109.                                     Error Messages
  15110.                                        Page 238
  15111.  
  15112.  
  15113.  
  15114.  
  15115.  
  15116.  
  15117.  
  15118.                                   Q - PRO 4 Commands
  15119.  
  15120.  
  15121.      BAD TABLE NAME IN FILE
  15122.      Program contains an invalid or missing table reference.
  15123.  
  15124.      BAD VRBL DECL
  15125.      Variable declaration contains an invalid parameter.
  15126.  
  15127.      BAD VRBL INDEX
  15128.      Index to a variable array exceeded the maximum value.
  15129.  
  15130.      BUFFER OVERFLOW
  15131.      Program attempted to move a file buffer pointer past the end of the file
  15132.      buffer. Trappable locally in PUT.  Trappable globally as error 8.
  15133.  
  15134.      BY EXPECTED
  15135.      Statement syntax requires the keyword "by".
  15136.  
  15137.      DEMO SYSTEM LIMITS EXCEEDED
  15138.      Program attempted to exceed limitations of the evaluation version of the
  15139.      system.
  15140.  
  15141.      DISK IO ERROR
  15142.      A hardware fault was returned by the operating system after a disk opera-
  15143.      tion.  Trappable locally in any file statement.  Trappable globally as
  15144.      error 20.
  15145.  
  15146.      DUPLICATE FIELD NAME
  15147.      Field name has already been assigned.
  15148.  
  15149.      END OF FILE
  15150.      Program attempted to read past the end of a file.  Trappable locally in GET
  15151.      (for sequential files) and READ (for random/indexed files).  Trappable
  15152.      globally as error 11.
  15153.  
  15154.      END OF RECORD
  15155.      Program attempted to GET past the end of a record.  Trappable locally in
  15156.      GET.  Trappable globally as error 10.
  15157.  
  15158.      EXEC ERROR
  15159.      The programmer has POPPED the normal return from the stack and issued a
  15160.      RETURN.  Trappable globally as error 29.
  15161.  
  15162.      ENDFOR WITHOUT FOR
  15163.      An ENDFOR statement was detected for which there was no corresponding FOR
  15164.      statement.
  15165.  
  15166.      FIELD OUT OF SCREEN RANGE
  15167.  
  15168.  
  15169.                                     Error Messages
  15170.                                        Page 239
  15171.  
  15172.  
  15173.  
  15174.  
  15175.  
  15176.  
  15177.  
  15178.                                   Q - PRO 4 Commands
  15179.  
  15180.  
  15181.      Given field length would exceed screen boundary.
  15182.  
  15183.      FIELD UNAVAILABLE
  15184.      Program attempted to NEXT to a non-enterable field.
  15185.  
  15186.      FILE EXCLUSION LOCK FAILED
  15187.      System tried to lock record 0 of an indexed file. (required for most file
  15188.      operations) and could not get the lock.  Trappable as error 25.
  15189.  
  15190.      FILE LIMITS OVERRUN
  15191.      An attempt was made to add data to a file already occupying the operating
  15192.      system maximum megabytes of data.
  15193.  
  15194.      FILE NOT OPEN
  15195.      Program failed to OPEN or MAKE file before first I/O reference. Trappable
  15196.      locally in any file statement. Trappable globally as error 7.
  15197.  
  15198.      FILE OPEN
  15199.      Program attempted to OPEN or MAKE a file using an already active file
  15200.      number.
  15201.      FILE READ ONLY
  15202.      Tried to write to a read only file.  Trappable as error 28.
  15203.           
  15204.      FILE SYNCH. FAILURE
  15205.      Files are said to be out of synch when one process reads a record with
  15206.      apparently valid index links, which is then discovered to have been deleted
  15207.      by some other process.  Trappable as error 26.
  15208.  
  15209.      FILE UNAVAILABLE
  15210.      File does not exist. Trappable locally in OPEN. Trappable globally as error
  15211.      6.
  15212.  
  15213.      FOR EXPECTED
  15214.      Statement syntax requires the keyword "FOR".
  15215.  
  15216.      FORMAT LOAD OVERRUN
  15217.      The format file indicated will not fit in memory.
  15218.  
  15219.      FORMAT CREATE ERROR
  15220.      The format file can not be created due to disk error or filled directory.
  15221.  
  15222.      FORMAT MEMORY OVERFLOW
  15223.      No room left in memory for a new field definition.
  15224.  
  15225.      FORMAT WRITE ERROR
  15226.      The format file cannot be saved on disk (I/O error or full disk).
  15227.  
  15228.  
  15229.                                     Error Messages
  15230.                                        Page 240
  15231.  
  15232.  
  15233.  
  15234.  
  15235.  
  15236.  
  15237.  
  15238.                                   Q - PRO 4 Commands
  15239.  
  15240.  
  15241.  
  15242.      FROM EXPECTED
  15243.      Statement syntax requires the keyword "from".
  15244.  
  15245.      INCONSISTENT "MAY ENTER" ENTER">
  15246.      The given MAY ENTER value does not agree with the given MUST ENTER value
  15247.      (if MUST ENTER is Y, then MAY ENTER must be Y as well).
  15248.  
  15249.      INPUT FILE ONLY
  15250.      Program attempted to write to an input sequential file. Trappable locally
  15251.      in PUT or WRITE. Trappable globally as error 12.
  15252.  
  15253.      INTO EXPECTED
  15254.      Statement syntax requires the keyword "into".
  15255.      INVALID DESCRIPTOR TYPE
  15256.      Field descriptor was an invalid character.
  15257.  
  15258.      INVALID FIELD LENGTH
  15259.      The given field length was zero, or non-numeric.
  15260.  
  15261.      INVALID FIELD NAME
  15262.      A field name must be maximum ten alphanumeric characters, starting with an
  15263.      alphabetic.
  15264.  
  15265.      INVALID FILE NAME
  15266.      Indicated file name does not obey system rules for an unambiguous file
  15267.      name.
  15268.  
  15269.      INVALID "JUSTIFY"
  15270.      The value for the justification field must be L or R.
  15271.  
  15272.      INVALID PARAGRAPH NUMBER
  15273.      A non-numeric paragraph number was requested.
  15274.  
  15275.      INVALID "MAY ENTER"
  15276.      The value for the may-enter field must be Y or N.
  15277.  
  15278.      INVALID "MUST ENTER"
  15279.      The value for the must-enter field must be Y or N.
  15280.  
  15281.      INVALID "MUST FILL"
  15282.      The value for the must-fill field must be Y or N.
  15283.  
  15284.      INVALID "MUST TAB"
  15285.      The value for the must-tab field must be Y or N.
  15286.  
  15287.  
  15288.  
  15289.                                     Error Messages
  15290.                                        Page 241
  15291.  
  15292.  
  15293.  
  15294.  
  15295.  
  15296.  
  15297.  
  15298.                                   Q - PRO 4 Commands
  15299.  
  15300.  
  15301.      INVALID PROCEDURE NAME
  15302.      A procedure name must be a maximum of ten alphanumeric characters, starting
  15303.      with an alphabetic.
  15304.  
  15305.      INVALID SELECTION
  15306.      A non-existent or non-numeric selection was made from the main menu.
  15307.  
  15308.      INVALID X COORDINATE
  15309.      Given row coordinate is non-numeric, or exceeds the length of the screen.
  15310.      INVALID Y COORDINATE
  15311.      Given column coordinate is non-numeric, or exceeds the width of the screen.
  15312.      LINE PRINTER ERROR
  15313.      Printer not ready.  Trappable globally as error 30.
  15314.  
  15315.      MATHLIB NOT LOADED
  15316.      (8 bit only)  Attempted to use $LN, $ETOX, $INT, or exponentiation without
  15317.      MATHLIB loaded.  Trappable globally as error 31.
  15318.  
  15319.      MEMORY OVERFLOW
  15320.      Format file will not fit in available memory, or there is no space to open
  15321.      a new file, or no space to allocate a new variable, or expression required
  15322.      too much temporary storage to execute.
  15323.  
  15324.      MISSING FILE NAME
  15325.      Statement syntax requires a file name.
  15326.  
  15327.      MUST ENTER FIELD
  15328.      Operator attempted to exit a field without entering any data.  Recoverable.
  15329.  
  15330.      MUST FILL FIELD
  15331.      Operator attempted to exit a field without filling it.  Recoverable.
  15332.  
  15333.      NEW FILE
  15334.      The given file name does not exist; it will be created at file save time.
  15335.  
  15336.      NO DATA IN BUFFER
  15337.      Program attempted to delete an indexed record without first loading the
  15338.      record. Trappable locally in FREE.  Trappable globally as error 18.
  15339.  
  15340.      NO ENTERABLE FIELDS
  15341.      Format file contains no enterable fields.
  15342.  
  15343.      NO FILE
  15344.      Attempted to initially load a non-existent format file.
  15345.  
  15346.      NO FORMAT DEFINED
  15347.  
  15348.  
  15349.                                     Error Messages
  15350.                                        Page 242
  15351.  
  15352.  
  15353.  
  15354.  
  15355.  
  15356.  
  15357.  
  15358.                                   Q - PRO 4 Commands
  15359.  
  15360.  
  15361.      The indicated menu selection requires the previous selection of main menu
  15362.      choice N.
  15363.  
  15364.      NO FID FILE
  15365.      A fid file was named in an OPEN or MAKE statement which does not exist.
  15366.  
  15367.      NO MORE ROOM FOR PARAGRAPH
  15368.      Updating the indicated paragraph would exceed memory space.
  15369.  
  15370.      NON-NUMERIC FIELD
  15371.      Program attempted to perform arithmetic with non-numeric data.
  15372.  
  15373.      NO SUCH FILE
  15374.      Program attempted to CHAIN to a non-existent file. Trappable globally as
  15375.      error 16.
  15376.  
  15377.      NO SUCH TABLE
  15378.      Program referenced a non-existent table.
  15379.  
  15380.      NO SUCH FIELD OR VRBL
  15381.      Referenced field or variable does not exist.
  15382.  
  15383.      NO SUCH LABEL
  15384.      Referenced label does not exist.
  15385.  
  15386.      NO TABLE MATCH
  15387.      Program executed a TSEAR statement that resulted in no match being found.
  15388.      Trappable locally in TSEAR. Trappable globally as error 5.
  15389.  
  15390.      OUTPUT FILE ONLY
  15391.      Program attempted to GET or READ an output sequential file. Trappable
  15392.      locally in GET and READ.  Trappable globally as error 9.
  15393.  
  15394.      RECURSIVE ERROR
  15395.      An error in closing a file caused the system to go into termination logic,
  15396.      which also attempts to close the file. Rather than hang up in an infinite
  15397.      attempt to deal with the offending file, this error message is displayed
  15398.      and QNE reboots directly.
  15399.  
  15400.      RETURN WITHOUT CALL
  15401.      Program attempted to RETURN without a corresponding CALL.
  15402.  
  15403.      STACK OVERFLOW
  15404.      Program executed too many nested CALL statements.
  15405.  
  15406.      TO EXPECTED
  15407.  
  15408.  
  15409.                                     Error Messages
  15410.                                        Page 243
  15411.  
  15412.  
  15413.  
  15414.  
  15415.  
  15416.  
  15417.  
  15418.                                   Q - PRO 4 Commands
  15419.  
  15420.  
  15421.      Statement syntax requires the keyword "to".
  15422.  
  15423.      USING EXPECTED
  15424.      Statement syntax requires the keyword "using".
  15425.  
  15426.      WHAT?
  15427.      User attempted to load a non-format file for editing.
  15428.  
  15429.  
  15430.  
  15431.  
  15432.  
  15433.  
  15434.  
  15435.  
  15436.  
  15437.  
  15438.  
  15439.  
  15440.  
  15441.  
  15442.  
  15443.  
  15444.  
  15445.  
  15446.  
  15447.  
  15448.  
  15449.  
  15450.  
  15451.  
  15452.  
  15453.  
  15454.  
  15455.  
  15456.  
  15457.  
  15458.  
  15459.  
  15460.  
  15461.  
  15462.  
  15463.  
  15464.  
  15465.  
  15466.  
  15467.  
  15468.  
  15469.                                     Error Messages
  15470.                                        Page 244
  15471.  
  15472.  
  15473.  
  15474.  
  15475.  
  15476.  
  15477.  
  15478.                                   Q - PRO 4 Commands
  15479.  
  15480.  
  15481.                                         QMAINT
  15482.                                         ======
  15483.  
  15484.      Overview
  15485.      --------
  15486.      QMAINT.EXE packs, verifies or recovers an indexed file.  QMAINT may be run
  15487.      from the command line with prompting or the entire command with parameters
  15488.      may be typed from the command line or executed from a RUN command or a .BAT
  15489.      file.  Under MS-DOS and PC-DOS, the full 64 character file names may be
  15490.      used.
  15491.  
  15492.      Prompted Execution
  15493.      ------------------
  15494.      Typing QMAINT on the command line followed by a Return will display this
  15495.      prompt:
  15496.  
  15497.           File Maintenance Utility
  15498.           Copyright (c) QNE International, 1985
  15499.  
  15500.      Menu selections are:
  15501.  
  15502.      1 - PACK
  15503.           Pack compresses the index file.  It is never mandatory to run PACK but
  15504.           if the indexed data file has a large number of deleted records, PACK
  15505.           will reclaim the space in the index file.  This will reduce the size
  15506.           of the index file.  PACK creates a temporary file and copies the file
  15507.           to be packed to it.  After a successful pack the original index file
  15508.           will be erased and the packed file renamed to the original.
  15509.  
  15510.      2 - VERIFY
  15511.           Verify checks the data file and the index file for validity.  This
  15512.           utility should be run if the indexed data file is suspected of being
  15513.           corrupted.  If there is any error message during the execution, then
  15514.           the file should be RECOVERed.  Verify does not use any disk space.  
  15515.           Verify rebuilds the deleted record chain as it goes, automatically.
  15516.  
  15517.      3 - RECOVER
  15518.           Recover restores a data file's index to a usable condition.  Note that
  15519.           index files get corrupted, not data files.  Most of the time corrup-
  15520.           tion of an index file can be traced to one of the following causes:
  15521.  
  15522.      o    The user turning off the machine before the files are closed.
  15523.      o    Trying to use the same index file for two data files.
  15524.      o    Miscellaneous hardware, power and operating software problems.      
  15525.  
  15526.      First the old index file is erased first and then a new one is built.
  15527.  
  15528.  
  15529.                                       Utilities
  15530.                                        Page 245
  15531.  
  15532.  
  15533.  
  15534.  
  15535.  
  15536.  
  15537.  
  15538.                                   Q - PRO 4 Commands
  15539.  
  15540.  
  15541.  
  15542.      X - Exit
  15543.      --------
  15544.      Return to operating system.
  15545.  
  15546.      Making any menu selection, except X, will display these prompts:
  15547.  
  15548.      Please enter data file name        Type the name of the data file and its
  15549.                                         extension followed by a Return.
  15550.  
  15551.      Please enter IDX file name:        Type the name of the index file and its
  15552.                                         extension.  If the name of the index
  15553.                                         file is the same as the data file and
  15554.                                         only the extension is different, you may
  15555.                                         omit the index file name and press
  15556.                                         Return.  QMAINT will assume that the
  15557.                                         index file is the same name as the data
  15558.                                         file with the extension "FID".
  15559.  
  15560.      Please enter FID file name:        Type the name of the FID file including
  15561.                                         its extension.  If the name of the FID
  15562.                                         file is the same as the data file and
  15563.                                         only the extension is different, you may
  15564.                                         omit the FID file name and press Return. 
  15565.                                         QMAINT will assume that the index file
  15566.                                         is the same name as the data file with
  15567.                                         the extension "IDX".
  15568.  
  15569.      Please enter options (RESULT,CONTINUE,VERBOSE):
  15570.  
  15571.      The Options are:
  15572.  
  15573.           RESULT    If any of the functions fail the file, QMAINT.BAD, will be
  15574.                     created (but will be empty). If RESULT is not specified and
  15575.                     an error occurs, a return code of 1 will be set when the
  15576.                     program exits (DOS only).  This return code may be used
  15577.                     logically in a DOS BAT file, e.g., "IF NOT ERROR LEVEL 0
  15578.                     GOTO . . . ." (See Batch Processing Commands in DOS 2.0 and
  15579.                     higher manuals.)
  15580.  
  15581.           CONTINUE  used only with VERIFY.  If specified, the verify function
  15582.                     will not stop after a verify error.
  15583.  
  15584.           VERBOSE   Display key values instead of flashing  "WORKING".
  15585.  
  15586.      Select the options desired and press Return.  An appropriate message will
  15587.  
  15588.  
  15589.                                       Utilities
  15590.                                        Page 246
  15591.  
  15592.  
  15593.  
  15594.  
  15595.  
  15596.  
  15597.  
  15598.                                   Q - PRO 4 Commands
  15599.  
  15600.  
  15601.      display.
  15602.  
  15603.      Execution from the Command Line
  15604.      -------------------------------
  15605.      QMAINT may be run from the command line by typing the command in the syntax
  15606.      shown below:
  15607.  
  15608.      QMAINT <function><filename>{parameters}
  15609.  
  15610.      where:
  15611.  
  15612.      <function>          PACK,  VERIFY, or RECOVER
  15613.  
  15614.      <filename>          datafile name \FIDfile name\\INDEX file name.  If the
  15615.                          FID or index file name is omitted, it will be assumed
  15616.                          to be the same as the datafile name with the proper
  15617.                          extensions.
  15618.  
  15619.      <parameters>        Optionally RESULT, CONTINUE, VERBOSE.  These options
  15620.                          are the same as shown above.
  15621.  
  15622.      Execution from the RUN Command or a .BAT file
  15623.      ---------------------------------------------
  15624.      The RUN command and the .BAT file syntax are identical to the command line
  15625.      syntax.
  15626.  
  15627.      Examples:
  15628.      QMAINT PACK data1.dat FID data1.fid INDEX data1.idx VERBOSE
  15629.           PACK a file named DATA1.DAT whose FID file is DATA1.FID and whose
  15630.           index file is DATA1.IDX and display the activity as it occurs.
  15631.  
  15632.      Note that the FID file name is preceded with the keyword "FID" and the
  15633.      index file name is preceded with the keyword "INDEX".
  15634.  
  15635.      QMAINT PACK DATA1.DAT VERBOSE
  15636.           VERIFY a file named DATA1.DAT whose FID file is DATA1.FID and whose
  15637.           index file is DATA1.IDX.  If verify fails create the file QMAINT.BAD. 
  15638.           If verify fails, continue with the verification.  Display the activity
  15639.           as it occurs.
  15640.  
  15641.      QMAINT VERIFY data1.dat FID data1.fid INDEX data1.idx RESULT, CONTINUE,    
  15642.         VERBOSE
  15643.      or
  15644.  
  15645.      QMAINT VERIFY DATA1.DAT RESULT,CONTINUE,VERBOSE
  15646.  
  15647.  
  15648.  
  15649.                                       Utilities
  15650.                                        Page 247
  15651.  
  15652.  
  15653.  
  15654.  
  15655.  
  15656.  
  15657.  
  15658.                                   Q - PRO 4 Commands
  15659.  
  15660.  
  15661.                           Q N E   I N T E R N A T I O N A L
  15662.  
  15663.                                       Order Form
  15664.  
  15665.      Please send:
  15666.  
  15667.      ___ Copies of Q-PRO 4 at $50.00 each                   __________
  15668.      ___ Copies of Q-PRO 4 Plus $90.00 each                 __________
  15669.      ___ Copies of Author's LockUp at $150.00 each          __________
  15670.      ___ Report Generator distribution licence at
  15671.           $150.00 each                                      __________
  15672.      ___ Copies of Q2C at $250.00 each                      __________
  15673.      ___ Membership in QNE User's Group at $25.00 each      __________
  15674.      ___ One year of telephone technical support at
  15675.            $150.00 per year                                 __________
  15676.      ___ Q-Query, post relational query language at
  15677.            $50.00 each                                      __________ 
  15678.  
  15679.                               Subtotal                      __________
  15680.  
  15681.      Shipping:(UPS Ground, US $7.00)                        __________
  15682.      Pennsylvania and New Jersey residents please
  15683.           add 6% sales tax                                  __________
  15684.  
  15685.                               Total                        $__________
  15686.       
  15687.                           
  15688.      Name: ______________________________________________________
  15689.  
  15690.      Company: ___________________________________________________
  15691.  
  15692.      Address: ___________________________________________________
  15693.  
  15694.      City: _________________________  State:_____  ZIP:__________
  15695.  
  15696.      Telephone: ______________________  FAX:_____________________
  15697.  
  15698.      Payment by: __MC  __ VISA  __Check
  15699.  
  15700.      Cardnumber __________________________________  Expiration ___/___
  15701.  
  15702.      Signature: _______________________________________________
  15703.  
  15704.      To place your order send this form or call (800)333-0448.
  15705.  
  15706.      Sorry, NO COD's
  15707.  
  15708.  
  15709.                                       Utilities
  15710.                                        Page 248
  15711.