TclJava Library Procedures - TclException manual page

  EXCEPTION
    tcl.lang.TclException -- This class is used to signal exception conditions in the execution of Tcl scripts.
  CONSTRUCTORS
  METHODS
    int getCompletionCode()
  ARGUMENTS
  DESCRIPTION
    getCompletionCode
      TCL.ERROR
      TCL.RETURN
      TCL.BREAK
      TCL.CONTINUE
    TclException(int ccode)
    TclException(Interp interp, String msg, int ccode)
    TclException(Interp interp, String msg)
  EQUIVALENT C FUNCTIONALITY
  SEE ALSO
  KEYWORDS

### EXCEPTION

tcl.lang.TclException -- This class is used to signal exception conditions in the execution of Tcl scripts.

### CONSTRUCTORS

TclException(int ccode)

TclException(Interp interp, String msg, int ccode)

TclException(Interp interp, String msg)

### METHODS

int getCompletionCode()

### ARGUMENTS

Interp interp ()
  Internal representation to be stored in newly created TclObject.

String msg ()
  Error message to store in the interp's result object.

int ccode ()
  Completion code to store inside the TclException.

### DESCRIPTION

getCompletionCode
  The getCompletionCode method is used to retrieve the completion code of the command that threw the exception. The following are the four possible integer values for the completion code:

  TCL.ERROR
    The command couldn't be completed successfully; the interpreter's result describes what went wrong.

  TCL.RETURN
    The command requests that the current procedure return; the interpreter's result contains the procedure's return value.

  TCL.BREAK
    The command requests that the innermost loop be exited; the interpreter's result is meaningless.

  TCL.CONTINUE
    Go on to the next iteration of the current loop; the interpreter's result is meaningless.

TclException(int ccode)
  This constructor creates a TclException with the completion code ccode.

TclException(Interp interp, String msg, int ccode)
  This constructor extends the above constructor. If interp is non-null, its result object will be set to contain msg.

TclException(Interp interp, String msg)
  This constructor is the same as the above constructor, except that the completion code is set to TCL.ERROR.

### EQUIVALENT C FUNCTIONALITY

The Exception handling syntax in the C API can be represented by the following canonical C code:

    int foo(Tcl_Interp interp, ...)
    	{
    	    if (ok) {
    		Tcl_SetResult(interp, result);
    		return TCL_OK;
    	    } else {
    		Tcl_SetResult(interp, "err message ...");
    		return TCL_ERROR;
    	    }
    	}

The return value of the foo() procedure is the completion code. TCL_OK indicates a normal completion status, and all other values indicate an exception. The above code can be written in Java as:

    void foo(Interp interp, ...)
    	{
    	    if (ok) {
    		interp.setResult(result);
    	    } else {
    		interp.setResult("err message ...");
    		throw new TclException(TCL.ERROR);
    	    }
    	}

In the Java API, foo()'s return type is void. Rather than returning the completion code, the completion code is either stored in a TclException or implied to be OK. If the foo() method completes normally, no TclException is thrown, and the completion code is implied to be OK. Otherwise, an exception is thrown with the desired completion code (TCL.ERROR in the example above).

### SEE ALSO

TclNumArgsException, TclRuntimeError, Interp

### KEYWORDS

error, exception, return, result

    Copyright © 1996-1998 Sun Microsystems, Inc.
    Copyright © 1995-1997 Roger E. Critchlow Jr.