|
HP OpenVMS Systems Documentation |
|
HP BASIC for OpenVMS
|
| Previous | Contents | Index |
Compiler directives are instructions that tell HP BASIC to perform
certain operations as it translates a source program. This chapter
describes how to control program compilation using compiler directives.
16.1 Overview of Compiler Directives
With compiler directives, you can do the following:
When using compiler directives, follow these rules:
The following compiler listing directives let you control the content and appearance of the compilation 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.
16.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 31 characters 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 31 characters. 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.
16.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.
16.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" . . . |
%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.
16.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.
16.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.
16.4 Controlling Compilation
BASIC lets you control the compilation of a program by creating and testing lexical constants. You create and assign values to lexical constants with the %LET directive. These constants are always LONG integers.
You control the compilation by using the %IF-%THEN-%ELSE-%END %IF directive to test these lexical constants. Thus, you can conditionally:
BASIC also supplies the lexical built-in function %VARIANT that can be used to conditionally control compilation.
%IF-%THEN-%ELSE-%END %IF uses lexical expressions to determine whether to execute directives in the %THEN clause or the %ELSE clause. The following sections describe the use of:
The %LET directive creates and assigns values to lexical constants. Lexical constants are always LONG integers. These constants control the execution of the %IF-%THEN-%ELSE-%END %IF directive.
All lexical constants must be created with %LET before they can be used in a %IF-%THEN-%ELSE-%END %IF directive, and each lexical constant must be created with a separate %LET directive. All lexical constant names must also be preceded by a percent sign and cannot end with a dollar sign or percent sign.
A lexical expression can be any of the following:
The %LET directive lets you create constants that control conditional compilation. For example:
%LET %debug_on = 0% |
See Section 16.4.5 for an example of using %LET with %IF-%THEN-%ELSE.
16.4.2 %VARIANT Directive
The %VARIANT directive is a built-in lexical function that returns an integer. The value of this returned integer is determined by:
The %VARIANT function returns the variant value set with either of these methods.
The default value for the %VARIANT function is zero. See Section 16.4.5
for an example of controlling compilation with %VARIANT.
16.4.3 %ABORT Directive
The %ABORT directive terminates the compilation and displays a message you provide.
The text must be a quoted string literal. This information is displayed
to SYS$ERROR and in the compilation listing if one is being created.
BASIC stops the compilation and terminates the listing file as soon as
it encounters a %ABORT directive, and so BASIC does not perform syntax
checking on the remainder of the program. See Section 16.4.5 for an
example of using %ABORT.
16.4.4 %PRINT Directive
The %PRINT directive allows you to insert a message into your source code that the BASIC compiler displays at compile time.
The text must be a quoted string literal. This information is displayed
to SYS$ERROR and in the compilation listing if one is being created.
BASIC prints the message specified as soon as it encounters a %PRINT
directive. See Section 16.4.5 for an example of using %PRINT.
16.4.5 %IF-%THEN-%ELSE-%END %IF Directive
The %IF-%THEN-%ELSE-%END %IF directive lets you do the following things conditionally:
This directive differs from all others in that it can appear anywhere in a program where a space is allowed, except within a quoted string.
You must include %END %IF. Otherwise, the rest of the source program becomes part of the %THEN or %ELSE clause. You must also include a lexical expression and some BASIC source code.
The truth or falsity of the lexical expression determines whether BASIC compiles the source code in the %THEN clause or the %ELSE clause. If the lexical expression is true, BASIC does not compile the source code in the %ELSE clause. If the lexical expression is false, BASIC does not compile the source code in the %THEN clause. However, HP BASIC does check for lexical errors (such as illegally formed numeric constants) in the uncompiled block of code. If an uncompiled block of code contains a lexical error, HP BASIC signals an error.
Even though HP BASIC compiles only one block of code in an %IF-%THEN-%ELSE-%END-%IF directive, you cannot use the same line number in both a %THEN block and an %ELSE block. If you specify the same line number, the first occurrence of the line number is replaced by the second when the program is compiled.
The following example uses the %VARIANT directive, which returns the value set by the SET VARIANT command or /VARIANT qualifier:
%IF (%VARIANT = 2%) %THEN DECLARE LONG int_array(100) %ELSE DECLARE WORD int_array(100) %END %IF |
This directive allows for two possibilities. If you compile this program with a /VARIANT=2 qualifier, then BASIC creates an array of longword integers. If you compile this program with any other variant value, BASIC creates an array of word integers.
Because %IF can appear within a program line, you can express the same directive this way:
DECLARE %IF (%VARIANT=2%) %THEN LONG %ELSE WORD %END %IF int_array(100) |
A %THEN or %ELSE clause can also contain other compiler directives. For example, the following program creates the lexical constant %my_constant and assigns it a value of 8. The %IF directive evaluates the conditional expression ((%my_constant + %VARIANT) >= 10%). If this expression is true, BASIC executes the %THEN clause, aborting the compilation and issuing an error message. If the expression is false, BASIC prints the specified message and continues to compile your program without aborting the compilation.
%LET %my_constant = 8%
%IF ( (%my_constant + %VARIANT) >= 10% )%THEN
%ABORT "Cannot compile with VARIANT >= 2"
%ELSE
%PRINT "Successful Compilation"
%END %IF
|
The compilation listing shows you which clause was actually compiled.
16.4.6 %DEFINE and %UNDEFINE Directives
The %DEFINE directive allows you to assign a value to an identifier. The %UNDEFINE directive will remove the value.
The representation of this value stays in force until a corresponding
%UNDEFINE directive or the end of the source module is encountered.
16.5 Record Dependency Relationships in CDD/Repository
By using the %INCLUDE %FROM %CDD or the %REPORT %DEPENDENCY directives in conjunction with the /DEPENDENCY_DATA qualifier in the BASIC command, you can record dependency relationships in a CDO dictionary between a compiled module entity and included records or other referenced dictionary entities.
See Chapter 21 for more information about record dependency relationships.
| Previous | Next | Contents | Index |