HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

By default, sequential files allow records to cross or span block boundaries. If records cross block boundaries, RMS packs records into the file end-to-end throughout the file, leaving space for control information and padding.

The NOSPAN clause overrides this default, forcing records to fit into individual blocks (with space provided for control information and padding). When block boundaries restrict records, fixed-length records must be less than 512 bytes, and variable-length records less than 510 bytes. This can waste extra bytes at the end of each block. However, when records span block boundaries, RMS writes records end-to-end without regard for block boundaries. For example, if you specify NOSPAN, only four 120-byte records fit into a disk block. If you do not specify NOSPAN, BASIC begins writing the fifth record in the block, and continues writing that record in the next block. This minimizes wasted disk space and improves the file's capacity, at the minimal expense of increased processing overhead.

13.8.9 RECORDTYPE Clause

The RECORDTYPE clause lets you specify record formats that are compatible with files created by other language processors. You can choose one of four qualifiers: LIST, FORTRAN, ANY, and NONE. The default for BASIC is LIST, which specifies carriage return format. This is standard for ASCII text files and means that carriage control is performed by RMS when writing the file to a unit-record device.

If your program accesses a file created with a Fortran language processor, use the FORTRAN qualifier. In the following example, the FORTRAN qualifier sets the FORTRAN carriage control attribute in the RAT field in the FAB. For more information about the FAB control structure, see Section 13.8.11. The first byte of the record is assumed to be the carriage control information. For example:

OPEN "FIL.DAT" FOR INPUT AS FILE #1%,      &
     ORGANIZATION SEQUENTIAL, RECORDTYPE FORTRAN

If your program accesses a file created by an unknown language processor or by DCL, use the ANY qualifier; this qualifier causes BASIC to handle any record attribute type. If you create a file with the ANY qualifier, BASIC uses the default of LIST. For example:

OPEN "FIL.DAT" FOR INPUT AS FILE #1%,       &
     ORGANIZATION INDEXED, RECORDTYPE ANY

If you specify the TEMPORARY clause in the OPEN statement, BASIC deletes that file in any one of the following cases:

• When you close the file
• When the program aborts or exits
• When your process terminates

No entry for this file is made in any directory.

13.8.11 USEROPEN Clause

The USEROPEN clause specifies an external long function that BASIC executes when you open or create a file. (You do not need to declare the USEROPEN routine with an EXTERNAL FUNCTION statement.) This procedure can then specify additional OPEN parameters for the file. For example:

OPEN "FILE.DAT" FOR INPUT AS FILE #2%,      &
     ORGANIZATION INDEXED, USEROPEN Myopen, MAP ABC

The code in Myopen determines how the file FILE.DAT is opened. The Run-Time Library sets up six RMS control structures before calling the USEROPEN procedure. Table 13-4 defines these structures and their meanings.

A USEROPEN procedure should not alter the allocation of these structures, although it can modify the contents of many of the fields. You should not modify fields set by other OPEN statement keywords. For example, you should use the RECORDSIZE clause, not a USEROPEN routine, to set the record length.

The allocation of the RMS control structures (except for the RAB) lasts only for the duration of the OPEN statement. Therefore, your USEROPEN can retain only the RAB address for use after the OPEN operation is complete. Note that any additional structures that you allocate and link into the RMS structures must be unlinked before exiting the USEROPEN.

The following steps describe the execution of the USEROPEN routine:

1. BASIC performs normal OPEN statement processing up to the point where it would call the RMS OPEN/CREATE and CONNECT routines. BASIC then passes control to the USEROPEN routine.
2. BASIC passes the address of the FAB as the first parameter, the address of the RAB as the second parameter, and the address of the user-specified channel number as the third parameter to the routine.
3. The USEROPEN routine can modify the contents of the RMS control structures, and it must call the RMS OPEN or RMS CREATE routine and the RMS CONNECT routine and return the status in R0.

Example 13-1 shows how to create a USEROPEN routine to obtain a RAB address.

%TITLE  "Example USEROPEN"
%SBTTL  "Useropen Routine to obtain RAB address"
%IDENT  "Version 1.1"

FUNCTION LONG Get_rab_address ( Fabdef User_fab, Rabdef User_rab,
                              LONG Channel )
!++
! FUNCTIONAL DESCRIPTION:
!
!   Save the address of the RMS Record Access Block allocated by the caller
!   in a global symbol.  Open the file and return the status from RMS.
!
! FORMAL PARAMETERS (Standard for all BASIC USEROPEN procedures)
!
!   User_fab    Address of RMS File Access Block
!   User_rab    Address of RMS Record Access Block
!   Channel     Logical Unit assigned to file by caller.
!
! RETURN VALUE:    RMS Status value
!
! GLOBAL COMMON USAGE
!
!   RAB_ptr     Single longword PSECT used to pass RAB address to caller.
!
!--
    OPTION  INACTIVE = SETUP,           &
         CONSTANT TYPE = INTEGER,       &
         TYPE = EXPLICIT

    %NOLIST
    %INCLUDE "$FABDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    %INCLUDE "$RABDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    %INCLUDE "$RMSDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    %INCLUDE "STARLET" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET"
    %LIST
    !+
    !   Common area used to pass RAB address to caller.
    !-
    COMMON     (RAB_ptr)    LONG     rab_address

    DECLARE LONG    Rms_status
    !+
    !   Save RAB address in global symbol known to caller.
    !   Perform standard RMS open sequence
    !-
    Rab_address = LOC(User_rab::rab$b_bid)

    Rms_status = Sys$open( User_fab )

    IF Rms_status = Rms$_normal
    THEN
        Rms_status = Sys$connect( User_rab )
    END IF

END FUNCTION Rms_status

The WINDOWSIZE clause specifies the number of block retrieval pointers in memory for the file. WINDOWSIZE is not a file attribute, and therefore can be changed any time you open a file.

Retrieval pointers are associated with the file header and point to contiguous blocks on disk. By keeping retrieval pointers in memory, you can reduce the I/O associated with locating a record because the operating system does not have to access the file header for pointers as frequently. The number of retrieval pointers in memory at any one time is determined by the system default or by the value you supply in the WINDOWSIZE clause. The usual default number of retrieval pointers is 7.

A value of zero specifies the default number of retrieval pointers. A value of --1 specifies mapping the entire file, if possible. Values from --128 to --2 are reserved.

The PRINT USING statement controls the appearance and location of data on a line of output. With it, you can create formatted lists, tables, reports, and forms. This chapter describes how to format data with the PRINT USING statement.

14.1 Overview of the PRINT USING Statement

The ability to format data with the PRINT USING statement is useful because the way in which HP BASIC displays data with the PRINT statement is often limited. For example, a program might use floating-point numbers to represent dollars and cents. The PRINT statement displays floating-point numbers with up to six digits of accuracy, and places the decimal point anywhere in that 6-digit field. In contrast, PRINT USING lets you display floating-point numbers in the following ways:

• Rounded to a number of specified decimal places
• Vertically aligned on the decimal point
• Preceded by a dollar sign
• With commas every third digit to the left of the decimal point

Formatting monetary values in this way provides a more readable report. Another use for formatted numeric values might be to print checks on a printer. PRINT USING lets you print numbers with a dollar sign and an asterisk-filled field preceding the first digit.

PRINT USING also formats string data. With it you can left- and right-justify string expressions, or center a string expression over a specified column position. Further, the PRINT USING statement can contain string literals. These are strings that do not control the format of a print item, but instead are printed exactly as they appear in the format string.

It is recommended that you declare all format expressions as string constants. When you do this the HP BASIC compiler instructs the Run-Time Library to compile the string at compile time rather than at run time, thus improving the performance of your code.

14.2 Using Format Strings

Format strings determine the way in which items are to be printed in the output file. Format strings can be any of the following:

• String variables
• String literals
• Named string constants
• A combination of the previous strings

The PRINT USING statement must contain one or more format strings. Each format string is made up of one format field. Each format field controls the output of one print item and can contain only certain characters, as described throughout the chapter.

The PRINT USING statement must also contain a list of items you want printed. To format print items, you must separate them with commas or semicolons. Separators between print items do not affect output format as they do with the PRINT statement. However, if a comma or semicolon follows the last print item, HP BASIC does not return the cursor or print head to the beginning of the next line after it prints the last item in the list.

When HP BASIC encounters an invalid character within the current format field, it automatically ends the format field; therefore, you do not need to delimit format fields. The character that terminates the previous field can be either a new format field or a string literal.

In the following example, the first three characters in the format string (###) make up a valid numeric format field. The fourth character (A) is invalid in a numeric format field; therefore, HP BASIC ends the first format field after the third character. HP BASIC continues to scan the format string, searching for a character that begins a format field. The first such character is the number sign at character position 7. Therefore, the characters at positions 4, 5, and 6 are treated as a string literal. The characters at positions 7, 8, and 9 make up a second valid numeric format field.

PRINT USING "###ABC###", 123, 345

Output

123ABC345

When the statement executes, HP BASIC prints the first number in the list using the first format field, then prints the string literal ABC, and finally prints the second number in the list using the second format field. If you were to supply a third number in the list, HP BASIC would reuse the first format string. This is called reversion.

PRINT USING "###ABC###", 123, 345,
564

Output

123ABC345
564ABC

Because any character not part of a format field is printed just as it appears in the format field, you can use a space or multiple spaces to separate format fields in the format string as shown in the following example:

DECLARE STRING CONSTANT format_string = "###.##  ###.##"
DECLARE SINGLE A,B
A = 2.565
B = 100.350
PRINT USING format_string, A, B, A, B

Output

  2.57  100.35
  2.57  100.35

When the HP BASIC compiler encounters the PRINT USING statement, HP BASIC prints the value of A (rounded according to PRINT USING rules), three spaces, then the value of B. HP BASIC prints the three spaces because they are treated as a string literal in the format string. Notice that when HP BASIC reuses a format string, it begins on a new line.

14.3 Printing Numbers

With the PRINT USING statement, you can specify:

• The number of digits to print, thus rounding the number to a given place
• The decimal point location, thus vertically aligning numbers at the decimal point
• Special symbols, including trailing minus signs (-), asterisk-filled number fields, floating currency symbols, embedded commas, and E notation
• Debits and credits
• Leading zeros or leading spaces
• Blank-if-zero fields
• A special character that is to be printed as a literal

Unlike the PRINT statement, PRINT USING does not automatically print a space before and after a number. Unless you reserve enough digit positions to contain the integer portion of the number (and a minus sign, if necessary), HP BASIC prints a percent sign (%) to signal this condition and displays the number in PRINT format.

14.3.1 Specifying the Number of Digits

You reserve places for digits by including a number sign (#) for each digit position. If you print negative numbers, you must also reserve a place for the minus sign.

PRINT USING "###",123      !Three places reserved
PRINT USING "#####",12345  !Five places reserved
PRINT USING "####",-678    !Four places reserved
END

Output

123
12345
-678

If there are not enough digits to fill the field, HP BASIC prints spaces before the first digit.

format_string$ = "#####"
PRINT USING format_string$, 1
PRINT USING format_string$, 10
PRINT USING format_string$, -1709
PRINT USING format_string$, 12345
END

Output

     1
    10
 -1709
 12345

If you have not reserved enough digits to print the fractional part of a number, HP BASIC rounds the number to fit the field.

PRINT USING "###",126.7
PRINT USING "#",5.9
PRINT USING "#",5.4
END

Output

127
6
5

If you have not reserved enough places to print a number's integer portion, HP BASIC prints a percent sign as a warning followed by the number in PRINT statement format. After HP BASIC prints the number, it completes the rest of the list in PRINT USING format.

In the following example, PRINT USING displays the first number. Because there are not enough places to the left of the decimal point to display a 3-digit number, BASIC prints the second number in PRINT statement format, with a space before and after, but includes a percent sign warning.

PRINT USING "###", 256
PRINT USING "##", 256
END

Output

256
% 256

The decimal point's position in the format string determines the number of reserved places on either side of it. If the print item's fractional part does not use all of the reserved places to the right of the decimal point, BASIC fills the remaining spaces with zeros.

DECLARE STRING CONSTANT FM = "##.###"
PRINT USING FM, 15.72
PRINT USING FM, 39.3758
PRINT USING FM, 26

Output

15.720
39.376
26.000

If there are more fractional digits than reserved places to the right of the decimal point, BASIC rounds the number to fit the reserved places. Note that there must be enough places reserved to the left of the decimal point for the integer portion of the number. Otherwise, BASIC prints the number in PRINT format preceded by a percent sign. The following example shows how PRINT USING rounds numbers when you specify decimal point location:

PRINT USING "##.##", 25.789
PRINT USING "##.###", 100.2
PRINT USING "#.##",.999
END

Output

25.79
% 100.2
1.00

BASIC fills all reserved spaces to the left of the decimal point with specified digits, spaces, or the minus sign.

PRINT USING "##.##", 5.25
PRINT USING "##.##", -5.25
PRINT USING "###.##,-5.25
END

Output

 5.25
-5.25
 -5.25

Special symbols let you print numbers with trailing minus signs, asterisk-fill fields, floating currency symbols, commas, or E notation. You can also specify debits, credits, leading zeros, leading blanks, and blank-if-zero fields. Table 14-1 summarizes these special characters.

.