HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
Reference Manual

The %IF-%THEN-%ELSE-%END %IF directive lets you conditionally include source code or execute another compiler directive.

Format

Syntax Rules

• Lex-exp is always a LONG integer.
• Lex-exp can be any of the following:
  • A lexical constant named in a %LET directive.
  • An integer literal, with or without the percent sign suffix.
  • A lexical built-in function.
  • Any combination of the above, separated by valid lexical operators. Lexical operators include logical operators, relational operators, and the arithmetic operators for addition (+), subtraction (-), multiplication (*), and division (/).
• Code is HP BASIC program code. It can be any HP BASIC statement or another compiler directive, including another %IF directive. You can nest %IF directives to eight levels.

Remarks

• The %IF directive can appear anywhere in a program where a space is allowed, except within a quoted string. This means that you can use the %IF directive to make a whole statement, part of a statement, or a block of statements conditional.
• %THEN, %ELSE, and %END %IF do not have to be on the same physical line as %IF.
• If lex-exp is true, HP BASIC processes the %THEN clause. If lex-exp is false, HP BASIC processes the %ELSE clause. If there is no %ELSE clause, HP BASIC processes the %END %IF clause. The HP BASIC compiler includes statements in the %THEN or %ELSE clause in the source program and executes directives in order of occurrence.
• You must include the %END %IF clause. Otherwise, HP BASIC assumes the remainder of the program is part of the last %THEN or %ELSE clause and signals the error "MISENDIF, missing END IF directive" when compilation ends.

Example

%IF (%VARIANT = 2)
%THEN DECLARE SINGLE hourly_pay(100)
%ELSE %IF (%VARIANT = 1)
      %THEN DECLARE DOUBLE salary_pay(100)
      %ELSE %ABORT "Can't compile with specified variant"
      %END %IF
%END %IF
     .
     .
     .
PRINT %IF (%VARIANT = 2)
      %THEN 'Hourly Wage Chart'
            GOTO Hourly_routine
      %ELSE 'Salaried Wage Chart'
            GOTO Salary_routine
      %END %IF

The %INCLUDE directive lets you include HP BASIC source text from another program file in the current program compilation. HP BASIC also lets you access Oracle CDD/Repository record definitions from the Common Data Dictionary (CDD) and access commonly used routines from text libraries.

Format

Including a File
%INCLUDE str-lit

Including a CDD Definition
%INCLUDE %FROM %CDD str-lit

Including a File from a Text Library
%INCLUDE str-lit %FROM %LIBRARY [str-lit]

Syntax Rules

• Including a File
  Str-lit must be a valid file specification for the file to be included.
• Including a CDD Definition
  Str-lit specifies a CDD path name enclosed in quotation marks. The path name can be in either DMU or CDO format. This directive lets you extract a RECORD definition from the dictionary.
• Including a File from a Text Library
  • Str-lit specifies a particular module to be included.
  • The optional str-lit identifies a specific text library in which the included module resides. If the library name is not specified, BASIC uses the logical name BASIC$LIBRARY with a default file specification of BASIC.TLB. If BASIC$LIBRARY is undefined, BASIC uses SYS$LIBRARY:BASIC$STARLET.TLB.

Remarks

• Any statement that appears after an END statement inside an included file causes HP BASIC to signal an error.
• Only a line number or a comment field can appear on the same physical line as the %INCLUDE directive.
• The HP BASIC compiler includes the specified source file in the program compilation at the point of the %INCLUDE directive and prints the included code in the program listing file if the compilation produces one.
• The included file cannot contain line numbers. If it does, HP BASIC signals the error "Line number may not appear in %INCLUDE file."
• All statements in the accessed file are associated with the line number of the program line that contains the %INCLUDE directive. This means that a %INCLUDE directive cannot appear before the first line number in a source program if you are using line numbers.
• A file accessed by %INCLUDE can itself contain a %INCLUDE directive.
• All %IF directives in an included file must have a matching %END %IF directive in the file.
• You can control whether or not included text appears in the compilation listing with the /[NO]SHOW=INCLUDE qualifier. When you specify /SHOW=INCLUDE, the compilation listing file identifies any text obtained from an included file by placing a mnemonic in the first character position of the line on which the text appears. The "n" specifies that the text was either accessed from a source file or from a text library. The "I" tells you that the text was accessed with the %INCLUDE directive and n is a number that tells you the nesting level of the included text. See the HP BASIC for OpenVMS User Manual for more information about listing mnemonics.
• Including a File
  If you do not specify a complete file specification, HP BASIC uses the default device and directory and the file type .BAS.
• Including a CDD Definition
  • There are two types of CDD path names: full and relative. A full path name begins with CDD$TOP and specifies the complete path to the record definition. A relative path name begins with any string other than CDD$TOP and is appended to the current CDD$DEFAULT.
  • In Oracle CDD/Repository, the path names described previously are known as DMU path names, as distinct from CDO path names. You can specify either a full DMU path name, a full CDO path name, or a relative path name. A full path name consists of a dictionary origin followed by a dictionary path. A full DMU path name has CDD$TOP as its origin. A full CDO path name has an anchor as its origin. See Oracle CDD/Repository documentation for detailed information about path names.
  • If the record definition being accessed is in a CDO-format dictionary, you can create a dependency relationship in the dictionary between a dictionary representation of your program and the record definitions that you include in the program. The dictionary representation of the program is called a compiled module entity.
  • If you specify the /DEPENDENCY_DATA qualifier to the compiler and your CDD$DEFAULT points to a CDO-format dictionary, a compiled module entity is created for each compilation unit at compile time in CDD$DEFAULT. No compiled module entity is created if both conditions are not true.
  • If a compiled module entity exists for the program, an %INCLUDE %FROM %CDD directive specifying a record description in a CDO-format dictionary creates a relationship between the compiled module entity and the CDO-format record definition.
  • If the record description specified in the path name exists, it is copied to the program, whether a compiled module entity can be created or not.
  • When you use the %INCLUDE directive to extract a record definition from the CDD, HP BASIC translates the CDD definition to the syntax of the HP BASIC RECORD statement.
  • You can use the /SHOW=CDD_DEFINITIONS qualifier to specify that translated CDD definitions (in RECORD statement syntax) are included in the compilation listing file. HP BASIC places a "C" in column 1 when the translated RECORD statement appears in the listing file.
  • When you specify /SHOW=NOCDD_DEFINITIONS, HP BASIC does not include the CDD definition in the listing file. However, BASIC still includes the names, data types, and offsets of the CDD record components in the program listing's allocation map.
  • See the HP BASIC for OpenVMS User Manual and the Oracle CDD/Repository documentation for more information about dictionary data definitions.
• Including a File from a Text Library
  • The HP BASIC compiler searches through the specified text library for the module named and compiles the module upon encountering the %INCLUDE directive.
  • HP BASIC allows only 16 text libraries to be opened at one time; therefore, you cannot have %INCLUDE directives from a text library nested more than 16 levels deep. If you exceed this maximum, HP BASIC signals an error message.
  • If you do not specify a directory name and file type, HP BASIC uses the default device and directory and the file type .TLB.
  • HP BASIC provides the text library BASIC$STARLET. BASIC$STARLET 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 HP OpenVMS Command Definition, Librarian, and Message Utilities Manual.

Examples

Example 1

!Including a File
%INCLUDE "YESNO"

Example 2

!Including a CDD Definition
%INCLUDE %FROM %CDD "CDD$TOP.EMPLOYEE"

Example 3

!Including a CDD Definition with a CDO-format path name
%INCLUDE %FROM %CDD "MYNODE::MY$DISK:[MY_DIR]PERSONNEL.EMPLOYEE"
!The anchor is MYNODE::MY$DISK:[MY_DIR]

Example 4

!Including a File from a Text Library
%INCLUDE "EOF_CHECK" %FROM %LIBRARY "SYS$LIBRARY:BASIC_LIB.TLB"

The %LET directive declares and provides values for lexical variables. You can use lexical variables only in conditional expressions in the %IF-%THEN-%ELSE directive and in lexical expressions in subsequent %LET directives.

Format

Syntax Rules

• Lex-var is the name of a lexical variable. Lexical variables are always LONG integers.
• Lex-var must be preceded by a percent sign (%) and cannot end with a dollar sign ($) or percent sign.
• Lex-exp can be any of the following:
  • A lexical variable named in a previous %LET directive.
  • An integer literal, with or without the percent sign suffix.
  • A lexical built-in function.
  • Any combination of the above, separated by valid lexical operators. Lexical operators can be logical operators, relational operators, and the arithmetic operators for addition (+), subtraction (-), multiplication (*), and division (/).

Remarks

• Only a line number or a comment field can appear on the same physical line as the %LET directive.
• You cannot change the value of lex-var within a program unit once it has been named in a %LET directive. For more information about coding conventions, see the HP BASIC for OpenVMS User Manual.

Example

%LET %DEBUG_ON = 1%

The %LIST directive causes the HP BASIC compiler to start or resume accumulating compilation information for the program listing file.

Format

Syntax Rules

None

Remarks

• Only a line number or a comment field can appear on the same physical line as the %LIST directive.
• The %LIST directive has no effect unless you requested a listing file. For more information about listing file format, see the HP BASIC for OpenVMS User Manual.
• As soon as it encounters the %LIST directive, the HP BASIC compiler starts or resumes accumulating information for the program listing file. Thus, the directive itself appears as the next line in the listing file.

Example

%LIST

The %NOCROSS directive causes the HP BASIC compiler to stop accumulating cross-reference information for the program listing file.

Format

Syntax Rules

None

Remarks

• Only a line number or a comment field can appear on the same physical line as the %NOCROSS directive.
• The HP BASIC compiler stops accumulating cross-reference information for the program listing file immediately after encountering the %NOCROSS directive.
• The %NOCROSS directive has no effect unless you request a listing file and cross-reference information.
• It is recommended that you do not embed a %NOCROSS directive within a statement. Embedding a %NOCROSS directive within a statement makes the accumulation of cross-reference information unpredictable. For more information about listing file format, see the HP BASIC for OpenVMS User Manual.

Example

%NOCROSS

The %NOLIST directive causes the HP BASIC compiler to stop accumulating compilation information for the program listing file.

Format

Syntax Rules

None

Remarks

• Only a line number or a comment field can appear on the same physical line as the %NOLIST directive.
• As soon as it encounters the %NOLIST directive, the HP BASIC compiler stops accumulating information for the program listing file. Thus, the directive itself does not appear in the listing file.
• The %NOLIST directive has no effect unless you requested a listing file.
• In HP BASIC, you can override all %NOLIST directives in a program with the /SHOW=OVERRIDE qualifier. For more information about listing file format, see the HP BASIC for OpenVMS User Manual.

Example

%NOLIST

The %PAGE directive causes HP BASIC to begin a new page in the program listing file.

Format

Syntax Rules

None

Remarks

• Only a line number or a comment field can appear on the same physical line as the %PAGE directive.
• The %PAGE directive has no effect unless you request a listing file.

Example

%PAGE

The %PRINT directive lets you insert a message into your source code that the HP BASIC compiler prints during compilation.

Format

Syntax Rules

None

Remarks

• Only a line number or a comment field can appear on the same physical line as the %PRINT directive.
• HP BASIC will print the message specified as soon as it encounters a %PRINT directive. Str-lit is displayed on the terminal screen and in the compilation listing.

Example

%IF %DEBUG = 1% %THEN
%PRINT "This is a debug compilation"

Output

%BASIC-S-USERPRINT, This is a debug compilation

The %REPORT directive lets you record a dependency relationship between the compiled module entity for your program and the data definitions in Oracle CDD/Repository dictionaries. The data definitions are not copied into the program.

Format

Syntax Rules

• Str-lit specifies a path name in a CDO-format dictionary. It can be either a DMU-format path name or a CDO-format path name, enclosed in quotation marks. This specifies a dictionary entity, such as a form definition or an Rdb/VMS database, that the program references.
• Relationship-type specifies a valid Oracle CDD/Repository protocol; it must be enclosed in quotation marks if specified. The default relationship-type is CDD$COMPILED_DEPENDS_ON.

Remarks

• For this directive to be meaningful, you must specify the /DEPENDENCY_DATA qualifier at compile time. If /DEPENDENCY is not specified, the compiler will simply check the syntax and otherwise ignore the %REPORT directive.
• Your current CDD$DEFAULT and str-lit must refer to CDO-format dictionaries (not necessarily the same one).
• If you specify the /DEPENDENCY_DATA qualifier to the compiler, and if CDD$DEFAULT points to a CDO-format dictionary, a compiled module entity is created in CDD$DEFAULT for each compilation unit. No compiled module entity is created if both conditions are not true.
• The %REPORT %DEPENDENCY directive creates a dependency relationship in the dictionary between the compiled module entity for the program and the CDO-format dictionary entity to which it refers.

Example

!Establish access to the form PINK_SLIP in a dictionary
!on a specified node, and report the program's dependency
!relationship with the form.
%REPORT %DEPENDENCY "MYNODE::MY$DISK:[MYDIR]PERSONNEL.FORMS.PINK_SLIP"
!Relationship is CDD$COMPILED_DEPENDS_ON, the default.

The %SBTTL directive lets you specify a subtitle for the program listing file.

Format

Syntax Rules

Str-lit can contain up to 31 characters.

Remarks

• HP BASIC truncates extra characters from str-lit and does not signal a warning or error. Str-lit is truncated at 31 characters.
• Only a line number or a comment field can appear on the same physical line as the %SBTTL directive.
• The specified subtitle appears underneath the title on the second line of all pages of source code in the listing file until the HP BASIC compiler encounters another %SBTTL or %TITLE directive. HP BASIC clears the subtitle field before the allocation map section of the listing is generated. This way, you only get a subtitle on the listing pages that contain source code.
• Because HP BASIC associates a subtitle with a title, a new %TITLE directive sets the current subtitle to the null string. In this case, no subtitle appears in the listing until HP BASIC encounters another %SBTTL directive.
• If you want a subtitle to appear on the first page of your listing, the %SBTTL directive should appear at the beginning of your program, immediately after the %TITLE directive. Otherwise, the subtitle will start to appear only on the second page of the listing.
• If you want the subtitle to appear on the page of the listing that contains the %SBTTL directive, the %SBTTL directive should immediately follow a %PAGE directive or a %TITLE directive that follows a %PAGE directive.
• The %SBTTL directive has no effect unless you request a listing file.

Example

100     %TITLE "Learning to Program in HP BASIC"
        %SBTTL "Using FOR-NEXT Loops"
        REM     THIS PROGRAM IS A SIMPLE TEST
200     DATA    1, 2, 3, 4
   .
   .
   .
        NEXT I%
300     END

Output

TEST$MAIN                      Learning to Program in HP BASIC
                               Using FOR-NEXT Loops

     1         100     %TITLE "Learning to Program in HP BASIC"
     2                 %SBTTL "Using FOR-NEXT Loops"
     3                 REM THIS PROGRAM IS A SIMPLE TEST
     4         200     DATA  1, 2, 3, 4
   .
   .
   .
    10                 NEXT I%
    11         300     END