home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / DMSERROR.ZIP / DMSERROR.DOC < prev    next >
Encoding:
Text File  |  1988-09-22  |  15.5 KB  |  533 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.                                    DMSERROR
  27.  
  28.                    An Runtime Error System for Clipper S'87
  29.  
  30.  
  31.  
  32.                                     v.1.00
  33.                                   Bob Laszko
  34.                               September 15, 1988
  35.  
  36.  
  37.                                 Copyright 1988
  38.                             Data Management Systems
  39.                               All rights reserved
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.          INTRODUCTION
  74.  
  75.               Runtime "critical" error reporting in Clipper has always
  76.          been less than ideal. Versions prior to S'87 displayed a
  77.          cryptic "proc:ANYPROC  line:1001  Type conflict in SUBSTR
  78.          QUIT (Q/A/I)". As developers, we could decipher this message
  79.          (most of the time) and take the appropriate corrective
  80.          action. But our clients would go nuts. One or two were alert
  81.          enough to print the screen and press Q (we remembered to
  82.          include this in our system documentation). Some would press
  83.          A, restart the application, and wonder why it wouldn't work
  84.          anymore. Others would call (always at 2:00 am) to tell you
  85.          that the funny "PROC:" thing is on the screen again. Then
  86.          there were the few that never saw the error message at all
  87.          and rebooted their machines when "the keyboard locked up".
  88.          What a circus !!!
  89.  
  90.               Clipper S'87 was supposed to alleviate this with a
  91.          developer-definable runtime error system; and to a degree
  92.          they succeeded. ALTERROR.PRG is great for debugging. The
  93.          error is trapped and the debugger is called. ERRORSYS.PRG, as
  94.          a end-user error reporting system, is worse than the older
  95.          versions. The same "proc...line...error" message appears, but
  96.          the application dumps unceremoniously to DOS. If your
  97.          installations are like ours, the application was called from
  98.          a batch file or a menu system - as soon as the application
  99.          quits, the screen clears and the error message is gone !!
  100.  
  101.               The people at Nantucket probably knew that ERRORSYS was
  102.          fairly primitive, and decided to provide the source code so
  103.          that if we didn't like it (we don't), we could create our own
  104.          (we did). DMSERROR is the result of our design spec for a
  105.          runtime error system that is simple enough for the end user
  106.          to understand, while containing all the information that the
  107.          developer requires to indentify the problem.
  108.  
  109.               When an error is encountered, an error message is
  110.          displayed via DMSOOPS. Dependent upon the error class, the
  111.          user is given the choice of printing the error message and/or
  112.          quitting; or attempting to correct the problem and trying
  113.          again.
  114.  
  115.  
  116.          LEGAL, RIGHTS, & OTHER STUFF
  117.  
  118.               DMSERROR, as distributed in it's present form, is a
  119.          copyrighted product. It is not released into the public domain.
  120.          Data Management Systems reserves all rights to DMSERROR as
  121.          provided by US Copyright laws. You may use DMSERROR in your
  122.          applications, both personal and commercial, without royalty
  123.          obligations.
  124.  
  125.               Although a great deal of time and effort have been spent
  126.          designing, coding and debugging this utility, it cannot be
  127.  
  128. ────────────────────────────────────────────────────────────────────────────────
  129. DMSERROR v.1.0       Copyright 1988 Data Management Systems               - 1 -
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.          certain that it is totally error free. It should be clearly
  139.          understood that DMSERROR is released "as is". Data Management
  140.          Systems makes no warranties, expressed nor implied, of
  141.          merchantability and fitness for a particular purpose. In no
  142.          event shall Data Management Systems be liable for any direct,
  143.          indirect, or consequential damages, real or imagined.
  144.  
  145.  
  146.          CLIPPER'S ERROR CLASSES
  147.  
  148.               There are seven classes of errors trapped by Clipper:
  149.  
  150.                    Database
  151.                    Expression
  152.                    Miscellaneous
  153.                    Print
  154.                    Open
  155.                    Undefined
  156.                    Other
  157.  
  158.               DMSERROR will report only the first six error classes.
  159.          Class Other is handled internally by Clipper without hooks to
  160.          the Runtime Error System. Following is a discussion of how
  161.          DMSERROR deals with each of these errors. For a more complete
  162.          understanding of Nantucket's overall error trapping and
  163.          reporting system it is strongly advised that you review
  164.          appendix F, Runtime Error System, of the Clipper manual. This
  165.          document deals solely with how DMSERROR displays and deals with
  166.          the errors that are passed by Clipper.
  167.  
  168.  
  169.          DMSERROR AS THE RUNTIME ERROR SYSTEM
  170.  
  171.          Database Errors
  172.  
  173.               Defined as occurring when any action affects a database
  174.          between the time is is USEd and CLOSEd. Clipper passes the
  175.          following parameters to DMSERROR:
  176.  
  177.                     Procedure name
  178.                     Line number
  179.                     Error type
  180.  
  181.                A database error is considered un-recoverable by
  182.          DMSERROR. A message is displayed and the user is given the
  183.          choice of printing the error message and the application's
  184.          screen where the error occurred, and / or quitting to DOS.
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194. ────────────────────────────────────────────────────────────────────────────────
  195. DMSERROR v.1.0       Copyright 1988 Data Management Systems               - 2 -
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.          Expression Error
  205.  
  206.                Defined as occurring whenever there is an evaluation of
  207.          an expression. Clipper passes the following parameters to
  208.          DMSERROR:
  209.  
  210.                     Procedure name
  211.                     Line number
  212.                     Error type
  213.                     Expression (that caused the error)
  214.                     Operands (within the expression)
  215.  
  216.                An expression error (other than divide by zero) is
  217.          considered un-recoverable by DMSERROR. A message is displayed
  218.          and the user is given the choice of printing the error
  219.          message and the application's screen where the error occurred,
  220.          and / or quitting to DOS.
  221.  
  222.                When a divide by zero error occurs, whether using the /
  223.          or % operator, DMSERROR will return 0 or the dividend of the
  224.          modulus operation (respectively) back to the procedure. This
  225.          code is found at lines 73 - 80 in DMSERROR.PRG. No error
  226.          message is displayed in this instance.
  227.  
  228.          Miscellaneous Error
  229.  
  230.               Defined as unclassified and occur when the other error
  231.          functions cannot deal with the error. Clipper passes the
  232.          following parameters to DMSERROR:
  233.  
  234.                     Procedure name
  235.                     Line number
  236.                     Error type
  237.                     Expression (that caused the error)
  238.  
  239.                A miscellaneous error is considered un-recoverable by
  240.          DMSERROR. A message is displayed and the user is given the
  241.          choice of printing the error message and the application's
  242.          screen where the error occurred, and / or quitting to DOS.
  243.  
  244.          Print Error
  245.  
  246.               Defined as occurring when any print operation is or
  247.          becomes not ready. It should be noted that this error traps
  248.          only output through a parallel printer. Redirection to a
  249.          serial port or a network spooler is handled by the Open Error
  250.          function. Clipper passes the following parameters to
  251.          DMSERROR:
  252.  
  253.                     Procedure name
  254.                     Line number
  255.  
  256.               A print error stands a chance of being corrected. A
  257.          message is displayed to this affect and the user is given
  258.          some common problems to look for. If the problem is
  259.  
  260. ────────────────────────────────────────────────────────────────────────────────
  261. DMSERROR v.1.0       Copyright 1988 Data Management Systems               - 3 -
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.          corrected, the print operation is continued, otherwise it
  271.          will be aborted. It is important to note that the BREAK
  272.          command is used to abort the print operation (see line 507 in
  273.          DMSERROR.PRG). Using this would assume that you have
  274.          surrounded the print operation with BEGIN SEQUENCE...END
  275.          SEQUENCE. If this is not the case line 507 could be deleted,
  276.          in which case a RETURN(.F.) is executed. This will tell the
  277.          procedure to skip the line that caused the print error. See
  278.          the Clipper manual for more information on this method.
  279.  
  280.          Open Error
  281.  
  282.               Defined as occurring when a file operation fails, or
  283.          output to a serial device develops a problem. Clipper passes
  284.          the following parameters to DMSERROR:
  285.  
  286.                     Procedure name
  287.                     Line number
  288.                     Error type
  289.                     Expression (that caused the error)
  290.                     Operand (within the expression)
  291.  
  292.               The error message displayed here is multi-purpose. It
  293.          informs the user that an open error has occurred and lists
  294.          some possible corrective measures to take. It will also
  295.          display the error type and expression to aid in diagnosing
  296.          the problem. If it can be corrected, the operation can be
  297.          retried, otherwise the error message can be printed and / or
  298.          the program quit.
  299.  
  300.                If the error was caused by a failed file operation
  301.          (other than under a network and the error is caused by a
  302.          USE), it is considered un-recoverable and the appropriate
  303.          action taken.
  304.  
  305.               If the error was caused under a network by the USE
  306.          command, a RETURN(.F.) is executed. This will tell the
  307.          procedure to skip the command and continue with the next line
  308.          of code. This code is found at lines 273 - 276 in
  309.          DMSERROR.PRG. No error message is displayed in this instance.
  310.  
  311.               If the error was caused by a problem with serial
  312.          redirection of a print operation and the problem can be
  313.          corrected, the operation can be attempted again. Otherwise
  314.          the program should be quit.
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326. ────────────────────────────────────────────────────────────────────────────────
  327. DMSERROR v.1.0       Copyright 1988 Data Management Systems               - 4 -
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.          Undefined Error
  337.  
  338.               Defined as occurring when a variable (memory or field) is
  339.          referred to before being defined. Clipper passes the
  340.          following parameters to DMSOOPS:
  341.  
  342.                     Procedure name
  343.                     Line number
  344.                     Error type
  345.                     Expression (that caused the error)
  346.                     Operand (within the expression)
  347.  
  348.                An undefined error is considered un-recoverable by
  349.          DMSERROR. A message is displayed and the user is given the
  350.          choice of printing the error message and the application's
  351.          screen where the error occurred, and / or quitting to DOS.
  352.  
  353.  
  354.          DMSERROR SUPPORT FUNCTIONS AND PROCEDURES
  355.  
  356.              To create as professional a runtime error system as
  357.          possible, DMSERROR is supported by a number of external
  358.          functions and procedures:
  359.  
  360.          DMSOOPS
  361.  
  362.               Also written by Data Management Systems, this is the
  363.          vehicle for the error message displays. Version 1.10 update
  364.          09/15/88 is included with DMSERROR.ARC in its entirety. See
  365.          DMSOOPS.DOC for more information.
  366.  
  367.          EXXTEND
  368.  
  369.               Written by J. Scott Emerich, these functions return the
  370.          status of many of Clipper's SET commands. Both DMSERROR and
  371.          DMSOOPS require these functions. See EXXTEND.DOC for more
  372.          information.
  373.  
  374.          PRT_SCRN
  375.  
  376.               Written by Ray Love, this is a CALLable print screen
  377.          routine that is compatible with all versions of Clipper.
  378.          DMSERROR uses this to print the error message screens. See
  379.          PRT_SCRN.DOC for more information.
  380.  
  381.          ETOC()
  382.  
  383.               Beginning at line 520 in DMSERROR.PRG, this function
  384.          takes any expression (memvar, field, etc) and returns it's
  385.          type as a character string. This is used by DMSERROR to
  386.          display the error operands, but is written for generic use
  387.          with any program.
  388.  
  389.  
  390.  
  391.  
  392. ────────────────────────────────────────────────────────────────────────────────
  393. DMSERROR v.1.0       Copyright 1988 Data Management Systems               - 5 -
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.          COMPILING AND LINKING
  403.  
  404.               DMSERROR can be compiled into a stand-alone .OBJ file
  405.          for inclusion at link time. You could also place it within
  406.          your standard procedure .PRG file.
  407.  
  408.               To compile with Clipper for a stand-alone .OBJ:
  409.  
  410.                    CLIPPER DMSERROR
  411.  
  412.               To link with PLINK86:
  413.  
  414.                     PLINK86 FILE <your files>, EXXTEND, PRT_SCRN, ;
  415.                             DMSERROR LIB CLIPPER, EXTEND
  416.  
  417.               To link with TLINK:
  418.  
  419.                     TLINK <your files> EXXTEND PRT_SCRN DMSERROR ;
  420.                           ,,,CLIPPER EXTEND
  421.  
  422.                When using PLINK86 as the linker, you will receive an
  423.          error 11 warning for each of the DMSERROR functions. Error 11
  424.          means that duplicate definitions exist. Since CLIPPER.LIB
  425.          already contains the same error functions, this is
  426.          unavoidable - but not critical. The functions in DMSERROR
  427.          will become the default for the runtime error system. You
  428.          could avoid the warning messages by renaming DMSERROR.OBJ to
  429.          ERRORSYS.OBJ or ALTERROR.OBJ, but this is not recommended.
  430.  
  431.  
  432.          FUTURE OF DMSERROR
  433.  
  434.               The only modification that we have considered for
  435.          DMSERROR would be to include "Print to disk" as on option to
  436.          recovering from a print error. This was left out as a
  437.          possibility for the future.
  438.  
  439.  
  440.          DATA MANAGEMENT SYSTEMS ??
  441.  
  442.               We are a custom software house located in Fallbrook,
  443.          California. Founded in 1983, our primary vehicle of
  444.          development is Clipper. We also provide consulting, training,
  445.          data processing, hardware & software resale, and preventive
  446.          maintenance.
  447.  
  448.  
  449.               Please send any comments, suggestions, or gripes to:
  450.  
  451.               Bob Laszko
  452.               Data Management Systems
  453.               PO Box 3104
  454.               Fallbrook, Ca  92028
  455.               (619) 728-0984
  456.  
  457.  
  458. ────────────────────────────────────────────────────────────────────────────────
  459. DMSERROR v.1.0       Copyright 1988 Data Management Systems               - 6 -
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.               BBS support is provided via The File Bank's Clipper
  469.          Support Conference. This is one of the premier BBS's in
  470.          Southern California with something of interest from the
  471.          novice to the guru !! It is owned and operated by Bob Laszko
  472.          (this author's father). You can reach The File Bank at
  473.          (619) 728-4318.
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524. ────────────────────────────────────────────────────────────────────────────────
  525. DMSERROR v.1.0       Copyright 1988 Data Management Systems               - 7 -
  526.  
  527.  
  528.  
  529. .0       Copyright 1988 Data Management Systems               - 7 -
  530.  
  531.  
  532.  
  533.