home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tcl7.0b1 / doc / error.n < prev    next >
Encoding:
Text File  |  1993-04-16  |  3.0 KB  |  72 lines
  1. '\"
  2. '\" Copyright (c) 1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/error.n,v 1.1 93/04/16 17:23:32 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS error tcl
  25. .BS
  26. '\" Note:  do not modify the .SH NAME line immediately below!
  27. .SH NAME
  28. error \- Generate an error
  29. .SH SYNOPSIS
  30. \fBerror \fImessage\fR ?\fIinfo\fR? ?\fIcode\fR?
  31. .BE
  32.  
  33. .SH DESCRIPTION
  34. .PP
  35. Returns a TCL_ERROR code, which causes command interpretation to be
  36. unwound.  \fIMessage\fR is a string that is returned to the application
  37. to indicate what went wrong.
  38. .PP
  39. If the \fIinfo\fR argument is provided and is non-empty,
  40. it is used to initialize the global variable \fBerrorInfo\fR.
  41. \fBerrorInfo\fR is used to accumulate a stack trace of what
  42. was in progress when an error occurred; as nested commands unwind,
  43. the Tcl interpreter adds information to \fBerrorInfo\fR.  If the
  44. \fIinfo\fR argument is present, it is used to initialize
  45. \fBerrorInfo\fR and the first increment of unwind information
  46. will not be added by the Tcl interpreter.  In other
  47. words, the command containing the \fBerror\fR command will not appear
  48. in \fBerrorInfo\fR; in its place will be \fIinfo\fR.
  49. This feature is most useful in conjunction with the \fBcatch\fR command:
  50. if a caught error cannot be handled successfully, \fIinfo\fR can be used
  51. to return a stack trace reflecting the original point of occurrence
  52. of the error:
  53. .DS
  54. \fBcatch {...} errMsg
  55. set savedInfo $errorInfo
  56. \&...
  57. error $errMsg $savedInfo\fR
  58. .DE
  59. .PP
  60. If the \fIcode\fR argument is present, then its value is stored
  61. in the \fBerrorCode\fR global variable.  This variable is intended
  62. to hold a machine-readable description of the error in cases where
  63. such information is available; see the section BUILT-IN VARIABLES
  64. below for information on the proper format for the variable.
  65. If the \fIcode\fR argument is not
  66. present, then \fBerrorCode\fR is automatically reset to
  67. ``NONE'' by the Tcl interpreter as part of processing the
  68. error generated by the command.
  69.  
  70. .SH KEYWORDS
  71. error, errorCode, errorInfo
  72.