This chapter describes the ways the Compaq BASIC Translator handles exceptions, and lists common exception statements with their translated equivalents.

The Translator attempts to map between VAX BASIC or DEC BASIC and Visual Basic error codes. It produces the closest error code that can easily be constructed. Use caution when dealing with explicit VAX BASIC or DEC BASIC error codes, which may differ from those in Visual Basic.

6.1 Error Handling Overview

Because Visual Basic does not have WHEN or HANDLER statements, the Translator produces an approximation by using ON ERROR statements. In many cases, the Translator will produce error handling code that works the same way as the original WHEN and HANDLER statements. The translated error handling code will not always run the same way as the original because the subtleties of the error handling systems often do not match. Therefore, you need to review the translation of all exception handling code to ensure that it continues to work properly.

In VAX BASIC or DEC BASIC, only one error can be processed at a time. If an error occurs during execution of error-handling code, before a RESUME, RETRY, or EXIT HANDLER statement is executed, control passes to the VAX BASIC or DEC BASIC error handler, which causes the program to exit.

In Visual Basic, each error handler can handle only one error at a time. If an error handler encounters an error, Visual Basic looks at the procedure that called it to check for an enabled error handler that is not actively handling an error, and so on up the calling stack.

6.1.1 Methods of Handling Exceptions

There are two mechanisms in the Translator for dealing with exceptions: use of the Visual Basic native error handling mechanism, and DECBAS_ routines for error number compatibility. These mechanisms are described in this section.

Visual Basic Error Handling

The primary and underlying method is the Visual Basic native error mechanism. This mechanism is controlled primarily by means of the Visual Basic run-time system and the ERR and ERROR objects. Once an error has occurred, one of two things will happen:

• If no user error handler is currently in effect (via the On Error Goto construct), the program is terminated and a dialog box containing the error number and identifying text is displayed.
• If a user error handler is in effect, control is transferred to the handler where the error information can be retrieved by use of ERR and ERROR object methods and the ERROR function.

DECBAS_ Routines for Error Number Compatibility

The second method is provided for VAX BASIC or DEC BASIC error number compatibility. This consists of the DECBAS_CAUSEERROR, DECBAS_ERR, and DECBAS_ERT$ routines. These routines behave in the same way as their VAX BASIC or DEC BASIC counterparts.

VAX BASIC or DEC BASIC errors are kept separate from Visual Basic errors by means of the DECBAS_CAUSEERROR and DECBAS_ERR routines. DECBAS_CAUSEERROR adds a fixed offset to the error number prior to raising it with the Visual Basic Err.Raise Number statement. This yields a value that does not conflict with any error values currently used by Visual Basic.

Likewise, DECBAS_ERR checks whether the current error is within the range of values covered by VAX BASIC or DEC BASIC errors. If the error is within this range, the offset is subtracted from the error number which then yields the original VAX BASIC or DEC BASIC error number.

If the error number is not an offset of a VAX BASIC or DEC BASIC error, the error is assumed to be a Visual Basic run-time error and is converted to its closest VAX BASIC or DEC BASIC equivalent. There are many Visual Basic errors that do not translate very well or at all to VAX BASIC or DEC BASIC errors. If these compatibility functions are used in an application, you should modify your code to properly handle Visual Basic error codes.

It is recommended that you do not process application-defined errors with DECBAS_CAUSEERROR and DECBAS_ERR. Process errors of this type by using the Visual Basic ERR object.

6.1.2 Translating Statements

Some error handling statements translate to the same words in Visual Basic as in VAX BASIC or DEC BASIC. They usually mean the same thing, but there can be differences. The following table shows some VAX BASIC or DEC BASIC error handling statements with the corresponding Visual Basic translation.

Table 6-1 Translation of Exception Handling Statements

VAX BASIC or DEC BASIC Command	Visual Basic Command
ON ERROR GOTO HANDLE_ERROR	ON ERROR GOTO HANDLE_ERROR
ON ERROR GOTO 0	ON ERROR GOTO 0 1
ON ERROR GO BACK	ON ERROR GOTO 0 2
RETRY	RESUME
RESUME label	RESUME label
RESUME	RESUME NEXT 3
WHEN ERROR IN protected statements USE handler statements END WHEN	ON ERROR GOTO DECBAS_000001 translated protected statements ON ERROR GOTO outer_handler_label GOTO DECBAS_000002 DECBAS_000001: translated handler statements RESUME NEXT DECBAS_000002: 4
WHEN ERROR USE handler_label protected statements END WHEN	ON ERROR GOTO handler_label translated protected statements ON ERROR GOTO outer_handler_label 4
HANDLER handler_label handler statements END HANDLER	GOTO DECBAS_000003 handler_label: translated handler statements RESUME NEXT DECBAS_000003:
CONTINUE	RESUME NEXT
CONTINUE label	RESUME label

See the examples for the WHEN ERROR statement in Chapter 7.

Part 2 provides reference material on all the VAX BASIC or DEC BASIC statements and functions and their Translator equivalents.

This chapter provides reference material on all of the VAX BASIC or DEC BASIC statements and functions and their Translator equivalents. The statements and functions are listed in alphabetical order and each description contains the following sections:

Definition	A description of the VAX BASIC or DEC BASIC statement or function.
Translated Equivalent	The equivalent Visual Basic statement or function or the run-time routine.
Remarks	Explanatory remarks concerning any differences between the original statement or function and the translated Visual Basic statement or function.
Example	If appropriate, one or more examples of VAX BASIC or DEC BASIC input to the Translator and the resulting translated output. Examples are sometimes edited for readability, with line breaks occurring at places other than what you see on your screen. Comments in examples are added for explanation and are not necessarily part of the code.

VAX BASIC or DEC BASIC and Visual Basic differ in their conventions for capitalization. In this manual, VAX BASIC or DEC BASIC statements and routines in text are entirely in uppercase (for example, ABS). Visual Basic statements and routines in text are in mixed case and bolded (for example, Abs). In examples, case can vary. The Translator itself produces code that to a large extent matches the case of the input code (virtually all user identifiers match the original case, and some of the language keywords also match the original while other keywords appear in all uppercase); whereas the Translated Equivalent sections in this chapter show it in the conventional Visual Basic form with initial capital letters. Note that both the VAX BASIC or DEC BASIC compiler and the Visual Basic compiler are case insensitive, so there is no functional difference.

The VAX BASIC or DEC BASIC ABS function returns a floating-point number that equals the absolute value of a specified floating-point expression.

Translated Equivalent

Example

VAX BASIC or DEC BASIC Input

XX = ABS (-3.5)

Translator Output

XX=ABS(-3.5)

The VAX BASIC or DEC BASIC ABS% function returns an integer that equals the absolute value of a specified integer expression.

Translated Equivalent

Remarks

If you specify a floating-point expression for int-exp, DECBAS_ABSP% truncates it to an integer of the default integer size and stores it as an integer type.

Example

VAX BASIC or DEC BASIC Input

I = ABS% (-4)

Translator Output

I=DECBAS_ABSP%(-4)

The VAX BASIC or DEC BASIC ASCII (ASC) function returns the ASCII value in numeric representation of a string's first character. For the empty string, a zero result is returned.

Translated Equivalent

Remarks

The Translator converts the ASCII (ASC) function to the Visual Basic Asc function.

In the case of an empty string, Asc does not return 0 (zero). You can manually edit your source to call the routine DECBAS_ASCII, which does handle this case correctly. DECBAS_ASCII copies the behavior of VAX BASIC or DEC BASIC ASCII (ASC) exactly.

Example

VAX BASIC or DEC BASIC Input

I = ASC ("abc") I = ASCII ("xyz")

Translator Output

I=ASC("abc") I=ASC("xyz")

The VAX BASIC or DEC BASIC ATN function returns the arctangent (angular value) of a specified tangent in radians or degrees.

Translated Equivalent

Remarks

The process of translation to the Visual Basic Atn function raises floating-point differences. For more information, see Chapter 4.

Only values in radians are supported by Visual Basic.

Example

VAX BASIC or DEC BASIC Input

XX = ATN (.5)

Translator Output

XX=ATN(.5)

The VAX BASIC or DEC BASIC BUFSIZ function returns the record buffer size, in bytes, of a specified channel.

Translated Equivalent

Remarks

For information about I/O differences, see Chapter 5.

Example

VAX BASIC or DEC BASIC Input

BUFFERSIZE = BUFSIZ (0)

Translator Output

BUFFERSIZE=DECBAS_BUFSIZ(0)

The VAX BASIC or DEC BASIC CALL statement transfers control to a subprogram, external function, or other callable routine. You can pass arguments to the routine and, optionally, specify passing mechanisms. When the called routine finishes executing, control returns to the calling program.

Translated Equivalent

Remarks

Within the context of a CALL statement, the Translator discards the parameter-passing clauses BY DESC, BY VALUE, and BY REF. (Visual Basic does not support BY DESC within any context.)

The Visual Basic keywords ByVal and ByRef are valid only when making a call to a DLL procedure and can be used to describe how arguments are to be treated by the called procedure.

For more information, see the Visual Basic documentation.

Example

VAX BASIC or DEC BASIC Input

CALL SUBRTN (A, B BY DESC, C BY VALUE, D BY REF)

Translator Output

CALL SUBRTN(A,B,C,D)

The VAX BASIC or DEC BASIC CAUSE ERROR statement allows you to artificially generate a VAX BASIC or DEC BASIC run-time error and transfer program control to a VAX BASIC or DEC BASIC error handler.

Translated Equivalent

Remarks

The DECBAS_CAUSEERROR routine adds a fixed offset to err-num prior to calling the Visual Basic Err.Raise method. The Translator function DECBAS_ERR should be used to retrieve errors generated in this manner.

For more information on error handling and, specifically, on mapping error numbers, see Chapter 6.

Example

VAX BASIC or DEC BASIC Input

CAUSE ERROR 50

Translator Output

DECBAS_CAUSEERROR 50

The VAX BASIC or DEC BASIC CCPOS function returns the current character or cursor position of the output record on a specified channel.

Translated Equivalent

Remarks

For more information on I/O issues, see Chapter 5.

Example

VAX BASIC or DEC BASIC Input

V = CCPOS (1%)

Translator Output

V=DECBAS_CCPOS(1)

The VAX BASIC or DEC BASIC CHAIN statement transfers control from the current program to another executable image. CHAIN closes all files, then requests that the new program begin execution. Control does not return to the original program when the new image finishes executing.

Translated Equivalent

Remarks

The Translator does not support a conversion of the VAX BASIC or DEC BASIC CHAIN statement. Programs using this statement require recoding. The Translator issues the following error message:

%DB2VB-E-FEAUNTRANS, Feature is untranslatable

Example

VAX BASIC or DEC BASIC Input

CHAIN "prog2"

Translator Output

CHAIN"prog2" *** Untranslatable ***

The VAX BASIC or DEC BASIC CHANGE statement either converts a string of characters to their ASCII integer values or converts a list of numbers to a string of ASCII characters.

Translated Equivalent

String Variable to Array
DECBAS_CHANGE str-exp, num-array-name

Array to String Variable
DECBAS_CHANGE num-array-name, str-var

Example

VAX BASIC or DEC BASIC Input

CHANGE "string" TO NUMS CHANGE NUMS TO SS

Translator Output

DECBAS_CHANGE"string",NUMS DECBAS_CHANGE NUMS,SS

The VAX BASIC or DEC BASIC CHR$ function returns a 1-character string that corresponds to the ASCII value that you specify.

Translated Equivalent

Remarks

The Translator actually produces code with the dollar sign ($) retained; however, functionally the code is the equivalent of the Visual Basic function Chr.

Visual Basic raises an error for values not in the range 0 to 255. You can change CHR(val) to CHR(val mod 256) if necessary.

Example

VAX BASIC or DEC BASIC Input

SS = CHR$ (65)

Translator Output

SS=CHR$(65)

The VAX BASIC or DEC BASIC CLOSE statement ends I/O processing to a device or file on the specified channel.

Translated Equivalent

Remarks

For more information on I/O issues, see Chapter 5.

Example

VAX BASIC or DEC BASIC Input

CLOSE #1, #2, #3

Translator Output

DECBAS_CLOSE 1,2,3