The CAUSE ERROR statement allows a program to artificially generate an error when the program would not otherwise do so. You can force any BASIC run-time error. You must specify the number of the error the compiler should force; the error numbers are listed in Appendix B. The following statement forces an end-of-file error (ERR=11) to occur:

CAUSE ERROR 11%

You can use this feature to debug an error handler during program development, as shown in the following example:

WHEN ERROR IN . . . CAUSE ERROR 11% . . . USE SELECT ERR CASE = 11% PRINT "Trapped an end of file on device" CONTINUE CASE ELSE EXIT HANDLER END WHEN

16.3 Using the ON ERROR Statements

BASIC supports ON ERROR statements as an alternative to WHEN blocks primarily for compatibility with existing programs. WHEN ERROR blocks are similar to declarative statements in that they do not depend on run-time flow of control. The ON ERROR statements, however, affect error handling only if the statements execute at run time. For example, if a GOTO statement precedes an ON ERROR statement, the ON ERROR statement will not have any effect because it does not execute.

WHEN ERROR blocks let you handle errors that occur in a specific range of statements. ON ERROR statements let you specify a general error handler that is in effect until you specify another ON ERROR statement or until you pass control to the BASIC error handler.

The ON ERROR statements are documented in the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual. This section briefly describes the main features of the ON ERROR statements.

The ON ERROR statements can be used to transfer control to a labeled block of error handling code. If you have executed an ON ERROR statement and an error occurs, the ON ERROR statement immediately transfers control to the label or line number that starts the error handling code. Otherwise, the ON ERROR statement specifies the branch to be taken in the event of an error.

There are three forms of the ON ERROR statement:

• ON ERROR GOTO 0
  The ON ERROR GOTO 0 statement reverts control to BASIC default error handling in one of two ways:
  • If an error is pending, execution of the ON ERROR GOTO 0 statement returns control to the BASIC error handler immediately.
  • If no error is pending, an ON ERROR GOTO 0 statement disables your current error handler. The BASIC error handler handles all subsequent errors until another ON ERROR statement is executed, unless an error occurs in a WHEN ERROR protected region.
• ON ERROR GOTO target
  The ON ERROR GOTO target statement reverts control to the target when subsequent errors occur that are not handled by WHEN block handlers.

• ON ERROR GO BACK
  The ON ERROR GO BACK statement transfers control to the calling program's error handler if an error occurs in the subprogram or DEF function. If you use ON ERROR GO BACK in a PROGRAM unit (outside of a DEF function) and no other outer protected region exists, it is equivalent to ON ERROR GOTO 0 and BASIC default error handling is in effect. With ON ERROR GO BACK, if an error occurs in the execution of a function or subprogram, the error is passed to either the error handler of the surrounding program module (in the case of a DEF function definition) or to the error handler of the calling program (in the case of a separately compiled subprogram).
  An error handler in the DEF function does not permanently override an error handler in the main program. BASIC saves the error handler in the main program when you transfer into a DEF, and restores it when you return.

The ON ERROR GOTO statement is usually placed before any other executable statements. The following example clears end-of-file errors and passes all other errors back to the BASIC default error handling procedures:

5 ON ERROR GOTO Error_handler . . . Error_handler: !Trap end of file on device IF ERR = 11 THEN RESUME 1000 ELSE ON ERROR GO BACK END IF

The ON ERROR GOTO statement remains in effect after your program successfully handles an error. When the system signals another error, control once again transfers to the specified error handler.

Every ON ERROR error handler must end with one of the following statements:

• RESUME [target]
• ON ERROR GOTO 0
• ON ERROR GO BACK

If none of these statements is present, the BASIC error handler aborts your program with the fatal error "Error trap needs RESUME" as soon as an END, END SUB, END DEF, END FUNCTION, END PROGRAM, or END PICTURE statement is encountered. The RESUME statement, like the RETRY and CONTINUE statements, clears the error condition.

You can resume execution at any line number or label that is in the same module as the RESUME statement, unless that line or target is inside a DEF function, a WHEN ERROR protected region, or a handler. In general, RESUME without a target transfers control to the beginning of the program block where the error occurred.

• If you resume execution at a multistatement line, execution begins at the first statement after the line number or label---not necessarily at the statement that generated the error.
• If an entire loop block is associated with a single line number or label and an error occurs within the loop, RESUME with no target transfers control to the statement immediately after the FOR, WHILE, or UNTIL statement, not to the line number or label.

For more information about the RESUME statement, see the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual.

Using both ON ERROR statements and WHEN ERROR constructs in the same program is not recommended. However, when this is the case, the order of handler priorities is as follows:

1. Control passes to the handler associated with the innermost WHEN ERROR block.
2. If protected regions are nested, the pending error is handled by the handler associated with the next outer WHEN ERROR block.
3. When no outer protected regions can handle the error, and if an ON ERROR statement is in effect, control transfers to the target of the next outer ON ERROR statement (if one is present).
4. If no outer handler is available or can handle the error, the error is passed to BASIC default error handling. Default error handling is equivalent to ON ERROR GOTO 0 for main procedures, and ON ERROR GO BACK for SUBs, FUNCTIONs, and DEFs.

For information about specific run-time errors, see Appendix B.

Compiler directives are instructions that tell BASIC to perform certain operations as it translates a source program. This chapter describes how to control program compilation using compiler directives.

17.1 Overview of Compiler Directives

With compiler directives, you can do the following:

• Place program titles and subtitles in the header that appears on each page of the listing file.
• Place a program version identification string in both the listing file and the object module.
• Start or stop the inclusion of listing information for selected parts of a program.
• Start or stop the inclusion of cross-reference information for selected parts of a program.
• Include BASIC code from another source file or a text library.
• Include CDD/Repository record definitions in a BASIC program.
• Record dependency relationships in CDD/Repository.
• Display a message at compile time.
• Conditionally compile parts of a program.
• Terminate compilation.

When using compiler directives, follow these rules:

• Directives must begin with a percent sign (%).
• Directives can be preceded by an optional line number.
• Directives must be the only text on the line (except for %IF-%THEN-%ELSE-%END %IF).
• Directives cannot appear within a quoted string.
• Directives cannot follow an END, END SUB, or END FUNCTION statement.

The following compiler listing directives let you control the content and appearance of the compilation listing:

• %TITLE places a title string on the first line of the listing header.
• %SBTTL places a subtitle string on the second line of the listing header.
• %IDENT places an identification string on the second line of the listing header and within the object module.
• %PAGE causes BASIC to skip to top-of-form in the output listing.
• %NOLIST causes BASIC to stop accumulating information for the output listing.
• %LIST causes BASIC to resume accumulating information for the output listing.
• %NOCROSS causes BASIC to stop accumulating cross-reference information for the output listing.
• %CROSS causes BASIC to resume accumulating cross-reference information for the output listing.

These directives are described in the following sections.

The listing control directives have no effect if no source program listing is being produced. Similarly, the %CROSS and %NOCROSS directives have no effect if no cross-reference listing is being produced. However, the %IDENT directive places the specified text in the object module whether or not a listing is produced.

17.2.1 %TITLE and %SBTTL Directives

The %TITLE directive lets you specify a line of text that appears on the first line of every page in the compilation listing. This text line is a quoted string of up to 45 characters (31 characters in Alpha BASIC) and normally contains the source program title and other information.

If the %TITLE directive is the first source text in a module, then the quoted string appears in the first line of every page of the compilation listing; otherwise, the quoted string appears in the first line of every subsequent page in the compilation listing. That is, if BASIC encounters a %TITLE directive after it has begun creating a page in the output listing, the title information will not appear on that page. Rather, it appears on all of the following pages until it encounters another %TITLE directive.

%TITLE must appear on its own line. For example:

%TITLE "File OPEN Subprogram -- Author Hugh Ristics" SUB FILSUB (STRING F_NAME)

The %SBTTL directive lets you specify a line of text that appears on the second line of every page in the compilation listing (beneath the title). If BASIC encounters a %SBTTL directive after it has begun creating a page in the output listing, the subtitle information will not appear on that page. Rather, it appears on all following pages until it encounters another %SBTTL or %TITLE directive. If you want the subtitle to appear on the first page, the %SBTTL directive must appear directly after the %TITLE directive.

Any number of %SBTTL directives can appear in a source file; thus, you can use subtitle text to identify parts of the source program. As in %TITLE, the text you use in %SBTTL must be a quoted string not exceeding 45 characters (31 characters in Alpha BASIC). Note, however, that subtitle information appears on listing pages that contain the actual source code.

The following example shows the use of both %TITLE and %SBTTL directives. The first line of the listing's first page contains "Payroll Program" and the second line contains "Constant Declarations". When BASIC encounters the %SBTTL directive, the second line on each subsequent page becomes "Subroutines". When BASIC encounters the %SBTTL directive, the second line on each subsequent page becomes "Error Handler".

%TITLE "Payroll Program" %SBTTL "Constant Declarations" . . . %SBTTL "Subroutines" . . . %SBTTL "Error Handler" . . .

You can use multiple %TITLE directives in a single source file; however, whenever BASIC encounters a %TITLE directive, the %SBTTL information is set to the null string. Therefore, if you want to display subtitle information, each new %TITLE directive should be accompanied by a new %SBTTL directive.

17.2.2 %IDENT Directive

The %IDENT directive identifies the version of a program module. The identification text must be a quoted string of up to 31 characters. The information contained within the identification text appears in the listing file and the object module. Thus, the map file created by the OpenVMS Linker also contains this information.

The identification text appears in the first 31 character positions of the second line on each subsequent listing page. In the following example, the %IDENT information appears as the first entry on the second line of the listing. The information is also included in the object module if the compilation produces one. If the linker generates a map listing, this information also appears there.

%IDENT "V5.3" SUB PAY . . .

If your source module contains multiple %IDENT directives, BASIC signals a warning and uses the version specified in the first %IDENT directive.

17.2.3 %PAGE Directive

The %PAGE directive causes BASIC to begin a new page in the listing file. In the following example, the %PAGE directives cause BASIC to skip to a new page in the listing file just before each new subtitle. Note that, to have title and subtitle information appear in the heading of each page, you cannot place a line number between the %PAGE, %TITLE, and %SBTTL directives.

%TITLE "Payroll Program" %SBTTL "Constant Declarations" . . . %PAGE %SBTTL "Subroutines" . . . %PAGE %SBTTL "Error Handler" . . .

17.2.4 %LIST and %NOLIST Directives

%LIST and %NOLIST are complementary directives. The %LIST directive causes BASIC to resume adding information to the listing file, while the %NOLIST directive causes BASIC to stop adding information to the listing file. Therefore, you can control which parts of the source program are to be listed.

In the following example, when BASIC encounters the %LIST directive, it resumes adding new information to the listing file:

%TITLE "Payroll Program" %SBTTL "Constant Declarations" . . . %NOLIST . . . %LIST . . . %PAGE %SBTTL "Subroutines" . . . %PAGE %SBTTL "Error Handler" . . .

If you have not requested the creation of a compilation listing, the %LIST and %NOLIST directives have no effect.

If a program line contains a syntax error, BASIC overrides the %NOLIST directive for that line and produces the normal error diagnostics in the listing file.

17.2.5 %CROSS and %NOCROSS Directives

The %CROSS and %NOCROSS directives are complementary. The %CROSS directive causes BASIC to resume adding cross-reference information, while the %NOCROSS directive causes BASIC to stop adding cross-reference information to the listing file. Therefore, you can specify that only certain parts of the source program are to be cross-referenced.

In the following example, as soon as BASIC encounters the %CROSS directive, it resumes adding new cross-reference information to the listing file:

%TITLE "Payroll Program" %SBTTL "Constant Declarations" . . . %NOCROSS . . . %CROSS . . . %PAGE %SBTTL "Subroutines" . . . %PAGE %SBTTL "Error Handler" . . .

If you have not requested the creation of a cross-reference listing, the %CROSS and %NOCROSS directives have no effect.

17.3 Accessing External Source Files

The %INCLUDE directive lets you access BASIC source text from a file into the source program. The %INCLUDE directive also lets you access record definitions in CDD/Repository as well as access source text from a text library. The line on which a %INCLUDE directive resides can be continued, but cannot contain any other directives or statements.

If you are including a source text file, you must supply a file specification. If you do not provide a file type, BASIC uses the default type .BAS. For example:

%INCLUDE "KEN.BAS"

If you are including a CDD/Repository definition, you must supply a valid CDD/Plus path specification to extract a RECORD definition from CDD/Repository. For example:

%INCLUDE %FROM %CDD "CDD$TOP.EMPLOYEE"

See the CDD/Repository CDO Reference Manual for more information about CDD/Repository.

If you are including source text from a text library, you must supply the name of the text module you wish to include as well as the name of the library where the module resides. If you do not specify a library name, BASIC uses the default library, BASIC$LIBRARY. Moreover, if you do not specify a directory name or file type, BASIC uses the default device and the file type .TLB. If the BASIC$LIBRARY logical name is undefined, SYS$LIBRARY:BASIC$STARLET.TLB is used. The default file specification is BASIC.TLB.

In the following example, when BASIC encounters the %INCLUDE directive, the compiler searches through the library SYS$LIBRARY:BASIC_LIB.TLB for the specified module DMB_TEST and compiles the text as if it were placed in the position of the %INCLUDE directive:

%INCLUDE "DMB_TEST" %FROM %LIBRARY "SYS$LIBRARY:BASIC_LIB.TLB"

BASIC supplies the text library BASIC$STARLET located in SYS$LIBRARY. This text library contains condition codes and other symbols defined in the system object and shareable image libraries. Using the definitions from BASIC$STARLET allows you to reference condition codes and other system-defined symbols as local, rather than global symbols.

To create your own text libraries using the OpenVMS Librarian utility, see the VMS Librarian Utility Manual.

All file specifications, CDD/Repository path specifications, text modules, and library specifications must be string literals enclosed in quotation marks.

The source files accessed with %INCLUDE cannot contain line numbers. This requirement means that all statements in the accessed file are associated with the BASIC line containing the %INCLUDE directive if line numbers are being used. Therefore, if you are using line numbers, a %INCLUDE directive cannot appear before the first line number in a source program. A file accessed by %INCLUDE can itself contain a %INCLUDE directive.

When a program is compiled, BASIC inserts the included text at the point at which it encounters the %INCLUDE directive. The compilation listing identifies any text obtained from an included file by placing a mnemonic in the first character position of the line in which the text appears. "In" specifies text that was either accessed from a source file or from a text library, and "Cn" specifies a record definition that was accessed from CDD/Repository. Both the I and the C tell you that the text was accessed with the %INCLUDE directive, and n tells you the nesting level of the included text.

The %INCLUDE directive is useful when you want to share code among multiple program modules. To do this, you must first create a file that contains the shareable code, then include that file in all the modules that require it. Thus, you reduce the chance of a typographical error.

You can prevent the %INCLUDE file code from appearing in the compilation listing by using the BASIC command qualifier /SHOW=NOINCLUDE or /SHOW=NOCDD_DEFINITIONS. For text files and text library modules, use the qualifier /SHOW=NOINCLUDE. For CDD/Repository definitions, use the qualifier /SHOW=NOCDD_DEFINITIONS.