# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

# PRINT USING

> The PRINT USING statement generates output formatted according to a format string (either numeric or string) to a terminal or a terminal-format file.

## Format

## Syntax Rules

1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#). If you do not specify a channel, BASIC prints to the controlling terminal.
2. Str-exp is the format string. It must contain at least one valid format field and must be followed by a separator (comma or semicolon) and at least one expression.

   Note It is recommended that you use compile-time constant expressions for str-exp whenever possible. When you do this, the BASIC compiler compiles the string at compilation time rather than at run time, thus improving the performance of your program.

3. Output-list specifies the expressions to be printed.
   - Exp can be any valid expression.
   - A comma or semicolon must separate each expression.
   - A comma or semicolon is optional after the last expression in the list.

## Remarks

1. The PRINT USING statement can print up to:
   - Three digits of precision for BYTE integers
   - Five digits of precision for WORD integers
   - Ten digits of precision for LONG integers
   - Nineteen digits of precision for QUAD integers
   - Six digits of precision for SINGLE floating-point numbers
   - Sixteen digits of precision for DOUBLE floating-point numbers
   - Fifteen digits of precision for GFLOAT floating-point numbers
   - Thirty-three digits of precision for HFLOAT floating-point numbers
   - Six digits of precision for SFLOAT floating-point numbers
   - Fifteen digits of precision for TFLOAT floating-point numbers
   - Thirty-three digits of precision for XFLOAT floating-point numbers
   - Thirty-one digits of precision for DECIMAL numbers
   - The string length for STRING values
2. A terminal or terminal-format file must be open on the specified channel or BASIC signals an error.
3. The separator characters (comma or semicolon) in the PRINT USING statement do not control the print format as in the PRINT statement. The print format is controlled by the format string; therefore, it does not matter whether you use a comma or semicolon.
4. Formatting Numeric Output
   - The number sign (#) reserves space for one sign or digit.
   - The comma (,) causes BASIC to insert commas before every third significant digit to the left of the decimal point. In the format field, the comma must be to the left of the decimal point, and to the right of the rightmost dollar sign, asterisk, or number sign. A comma reserves space for a comma or digit.
   - The period (.) inserts a decimal point. The number of reserved places on either side of the period determines where the decimal point appears in the output.
   - The hyphen (-) reserves space for a sign and specifies trailing minus sign format. If present, it must be the last character in the format field. It causes BASIC to print negative numbers with a minus sign after the last digit, and positive numbers with a trailing space. The hyphen (-) can be used as part of a dollar sign ($$) format field.
   - The letters CD (Credit/Debit) enclosed in angle brackets (<CD>) print CR (Credit Record) after negative numbers or zero and DR (Debit Record) after positive numbers. If present, they must be the last characters in the format field. The Credit/Debit format can be used as part of a dollar sign ($$) format field.
   - Four carets(^^^^) specify E-format notation for floating-point and DECIMAL numbers. They reserve four places for SINGLE, DOUBLE, SFLOAT, and DECIMAL values; five places for GFLOAT and TFLOAT values; and six places for HFLOAT and XFLOAT values. If present, they must be the last characters in the format field.
   - Two dollar signs ($$) reserve space for a dollar sign and a digit and cause BASIC to print a dollar sign immediately to the left of the most significant digit.
   - Two asterisks (**) reserve space for two digits and cause BASIC to fill the left side of the numeric field with leading asterisks.
   - A zero enclosed in angle brackets (<0>) prints leading zeros instead of leading spaces.
   - A percent sign enclosed in angle brackets (<%>) prints all spaces in the field if the value of the print item is zero.

     Note You cannot specify the dollar sign ($$), asterisk-fill (**), and zero-fill (<0>) formats within the same print field. Similarly, BASIC does not allow you to specify the zero-fill (<0>) and the blank-if-zero (<%>) formats within the same print field.

   - An underscore (_) forces the next formatting character in the format string to be interpreted as a literal. It affects only the next character. If the next character is not a valid formatting character, the underscore has no effect and will itself be printed as a literal.
5. BASIC interprets any other characters in a numeric format string as string literals.
6. Depending on usage, the same format string characters can be combined to form one or more print fields within a format string. For example:
   - When a dollar sign ($$) or asterisk-fill (**) format precedes a number sign (#) , it modifies the number sign format. The dollar sign or asterisk-fill format reserves two places, and with the number signs forms one print field. For example:

     $$### | Forms one field and reserves five spaces
     **## | Forms one field and reserves four spaces

     When these formats are not followed by a number sign or a blank-if-zero (<%>) format, they reserve two places and form a separate print field.
   - When a zero-fill (<0>) or blank-if-zero format precedes a number sign, it modifies the number sign format. The <0> or <%> reserves one place, and with the number signs forms one print field. For example:

     <0>#### | Forms one field and reserves five spaces
     <%>### | Forms one field and reserves four spaces

     When these formats are not followed by a number sign, they reserve one space and form a separate print field.
   - When a blank-if-zero (<%>) format follows a dollar sign or asterisk-fill format (**), it modifies the dollar sign ($$) or asterisk fill (**) format string. The blank-if-zero reserves one space, and with the dollar signs or asterisks forms one print field. For example:

     $$<%>### | Forms one field and reserves six spaces
     **<%>## | Forms one field and reserves five spaces

     When the blank-if-zero precedes the dollar signs or asterisks, it reserves one space and forms a separate print field.
7. The comma (digit separator), dollar sign (currency symbol), and decimal point (radix point) are the defaults for U.S. currency. On VMS systems, you can change the digit separator, currency symbol and radix point by assigning the logical names SYS$DIGIT_SEP, SYS$CURRENCY and SYS$RADIX_POINT. Once you make each assignment, the PRINT USING statement accesses these logical names for these symbols.
8. For E-format notation, PRINT USING left-justifies the number in the format field and adjusts the exponent to compensate, except when printing zero. When printing zero in E-format notation, BASIC prints leading spaces, leading zeros, a decimal point, and zeros in the fractional portion if the PRINT USING string contains these formatting characters, and then the string "E+00".
9. Zero cannot be negative. If a small negative number rounds to zero, it is represented as a positive zero.
10. If there are reserved positions to the left of the decimal point, and the printed number is less than 1, BASIC prints one zero to the left of the decimal point and pads with spaces to the left of the zero.
11. If there are more reserved positions to the right of the decimal point than fractional digits, BASIC prints trailing zeros in those positions.
12. If there are fewer reserved positions to the right of the decimal point than fractional digits, BASIC rounds the number to fit the reserved positions.
13. If a number does not fit in the specified format field, BASIC prints a percent sign warning symbol (%), followed by the number in PRINT format.
14. Formatting String Output
    - Format string characters control string output and can be entered as either uppercase or lowercase characters. All format characters except the backslash and exclamation point must start with a single quotation mark ('). A single quote by itself reserves one character position. A single quote followed by any format characters marks the beginning of a character format field and reserves one character position.
    - L reserves one character position. The number of Ls plus the leading single quote determines the field's size. BASIC left-justifies the print expression and pads with spaces if the print expression is less than or equal to the field's width. If the print expression is larger than the field, BASIC left-justifies the expression and truncates its right side to fit the field.
    - R reserves one character position. The number of Rs plus the leading single quote determines the field's size. BASIC right-justifies the print expression and pads with spaces if the print expression is less than or equal to the field's width. If the print expression is larger than the field, BASIC truncates the right side to fit the field.
    - C reserves one character position. The number of Cs plus the leading single quote determines the field's size. If the string does not fit in the field, BASIC truncates its right side; otherwise, BASIC centers the print expression in this field. If the string cannot be centered exactly, it is offset one character to the left.
    - E reserves one character position. The number of Es plus the leading single quote determines the field's size. BASIC left-justifies the print expression if it is less than or equal to the field's width and pads with spaces; otherwise, BASIC expands the field to hold the entire print expression.
    - Two backslashes (\ \) when separated by n spaces reserve n+2 character positions. PRINT USING left-justifies the string in this field. BASIC does not allow a leading quotation mark with this format.
    - An exclamation point (!) creates a 1-character field. The exclamation point both starts and ends the field. BASIC does not allow a leading quotation mark with this format.
15. BASIC interprets any other characters in the format string as string literals and prints them exactly as they appear.
16. If a comma or semicolon follows the last item in output-list:
    - When printing to a terminal, BASIC does not generate a line terminator after printing the last item. The next item printed with a PRINT statement is printed at the position specified by the separator character following the last item in the first PRINT statement.
    - When printing to a terminal-format file, BASIC does not write out the record until a PRINT statement without trailing punctuation executes.
17. If no punctuation follows the last item in output-list:
    - When printing to a terminal, BASIC generates a line terminator after printing the last item.
    - When printing to a terminal-format file, BASIC writes out the record after printing the last item.

## Examples

Example 1

    PRINT USING "###.###",-12.345
    PRINT USING "##.###",12.345

Output

    -12.345
    12.345

Example 2

    INPUT "Your Name";Winner$
           Jackpot = 10000.0
    PRINT USING "CONGRATULATIONS, 'EEEEEEEEE, YOU WON $$#####.##", Winner$, Jackpot
    END

Output

    Your Name? Hortense Corabelle
    CONGRATULATIONS, Hortense Corabelle, YOU WON $10000.00

# PROD$

> The PROD$ function returns a numeric string that is the product of two numeric strings. The precision of the returned numeric string depends on the value of an integer argument.

## Format

## Syntax Rules

1. Str-exp1 and str-exp2 specify the numeric strings you want to multiply. A numeric string can contain an optional minus sign (-), ASCII digits, and an optional decimal point (.).
2. If str-exp consists of more than 60 characters, BASIC signals the error "Illegal number" (ERR=52).
3. Int-exp specifies the numeric precision of str-exp. Table 4-4 shows examples of rounding and truncation and the values of int-exp that produce them.

## Remarks

1. The PROD$ function does not support E-format notation.
2. Str-exp is rounded or truncated, or both, according to the value of int-exp.
3. If int-exp is from -60 to 60, rounding and truncation occur as follows:
   - For positive integer expressions, rounding occurs to the right of the decimal place. For example, if int-exp is 1, rounding occurs one digit to the right of the decimal place (the number is rounded to the nearest tenth). If int-exp is 2, rounding occurs two digits to the right of the decimal place (the number is rounded to the nearest hundredth), and so on.
   - If int-exp is zero, BASIC rounds to the nearest unit.
   - For negative integer expressions, rounding occurs to the left of the decimal point. If int-exp is -1, for example, BASIC moves the decimal point one place to the left, then rounds to units. If int-exp is -2, rounding occurs two places to the left of the decimal point; BASIC moves the decimal point two places to the left, then rounds to tens.
4. If int-exp is from 9940 to 10,060, truncation occurs as follows:
   - If int-exp is 10,000, BASIC truncates the number at the decimal point.
   - If int-exp is greater than 10,000 (10000 plus n), BASIC truncates the numeric string n places to the right of the decimal point. For example, if int-exp is 10,001 (10,000 plus 1), BASIC truncates the number starting one place to the right of the decimal point. If int-exp is 10,002 (10,000 plus 2), BASIC truncates the number starting two places to the right of the decimal point, and so on.
   - If int-exp is less than 10,000 (10,000 minus n), BASIC truncates the numeric string n places to the left of the decimal point. For example, if int-exp is 9999 (10,000 minus 1), BASIC truncates the number starting one place to the left of the decimal point. If int-exp is 9998 (10,000 minus 2), BASIC truncates starting two places to the left of the decimal point, and so on.
5. If int-exp is not from -60 to 60 or 9940 to 10,060, BASIC returns a value of zero.
6. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.

## Example

    DECLARE STRING num_exp1, &
                   num_exp2, &
                   product
    num_exp1 = "34.555"
    num_exp2 = "297.676"
    product = PROD$(num_exp1, num_exp2, 1)
    PRINT product

Output

    10286.2

# PROGRAM

> The PROGRAM statement allows you to identify a main program with a name other than the file name.

## Format

## Syntax Rules

1. Prog-name specifies the module name of the compiled source and cannot be the same as any SUB, FUNCTION, or PICTURE name.
2. Prog-name also defines the global entry point name for the main program.
3. The first character of a prog-name must be an alphabetic character (A to Z). The remaining characters, if any, can be any combination of alphabetic characters, digits (0 to 9), dollar signs ($), periods (.), and underscores (_).
4. Prog-name cannot be a quoted name.

## Remarks

1. The PROGRAM statement must be the first statement in a main program and can be preceded only by comment fields and lexical directives.
2. If you insert the program into a text or object library or examine it using the OpenVMS Debugger, the program name you specify will be the module name used.
3. A PROGRAM statement does not require a matching END PROGRAM statement.
4. The PROGRAM statement is optional; BASIC allows you to specify an END PROGRAM statement and an EXIT PROGRAM statement without a matching PROGRAM statement.

## Example

    PROGRAM first_test
       .
       .
       .
    END PROGRAM

# PUT

> The PUT statement transfers data from the record buffer to a file. PUT statements are valid on RMS sequential, relative, and indexed files. You cannot use PUT statements on terminal-format files or virtual array files.

## Format

## Syntax Rules

1. Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
2. The RECORD clause allows you to randomly write records to a relative or sequential fixed file by specifying the record number. Num-exp must be between 1 and the maximum record number allowed for the file. BASIC does not allow you to use the RECORD clause on sequential variable, sequential stream, or indexed files.
3. Int-exp in the COUNT clause specifies the record's size. If there is no COUNT clause, the record's size is that defined by the MAP or RECORDSIZE clause in the OPEN statement. The RECORDSIZE clause overrides the MAP clause.
   - If you write a record to a file with variable-length records, int-exp must be between zero and the maximum record size specified in the OPEN statement.
   - If you write a record to a file with fixed-length records, the COUNT clause serves no purpose. If used, int-exp must equal the record size specified in the OPEN statement.

## Remarks

1. For sequential access, the file associated with chnl-exp must be open with ACCESS WRITE, MODIFY, SCRATCH, or APPEND.
2. To add records to an existing sequential file, open it with ACCESS APPEND. If you are not at the end of the file when attempting a PUT to a sequential file, BASIC signals "Not at end of file" (ERR=149).
3. After a PUT statement executes, there is no current record pointer. The next record pointer is set as follows:
   - For sequential files, variable and stream PUT operations set the next record pointer to the end of the file.
   - For relative files, a sequential PUT operation sets the next record pointer to the next record plus 1.
   - For relative and sequential fixed files, a random PUT operation leaves the next record pointer unchanged.
   - For indexed files, a PUT operation leaves the next record pointer unchanged.
4. When you specify a RECORD clause, BASIC evaluates num-exp and uses this value as the relative record number of the target cell.
   - If the target cell is empty or occupied by a deleted record, BASIC places the record in that cell.
   - If there is a record in the target cell and the file has not been opened as a VIRTUAL file, the PUT statement fails, and BASIC signals the error "Record already exists" (ERR=153).
5. A PUT statement with no RECORD clause writes records to the file as follows:
   - For sequential variable and stream files, a PUT operation adds a record at the end of the file.
   - For relative and sequential fixed files, a PUT operation places the record in the empty cell pointed to by the next record pointer. If the file is empty, the first PUT operation places a record in cell number 1, the second in cell number 2, and so on.
   - For indexed files, RMS stores records in order of ascending primary key value and updates all indexes so that they point to the record.
6. When you open a file as ORGANIZATION VIRTUAL, the file you open is a sequential fixed file with a record size that is a multiple of 512 bytes. You can then access the file with the FIND, GET, PUT, or UPDATE statements or through one or more virtual arrays. BASIC allows you to overwrite existing records in a file not containing virtual arrays and opened as ORGANIZATION VIRTUAL by using the PUT statement with a RECORD clause. All other organizations require the UPDATE statement to change an existing record. It is recommended that you also use the UPDATE statement to change existing records in VIRTUAL files that do not contain virtual arrays.
7. If an existing record in an indexed file has a record with the same key value as the one you want to put in the file, BASIC signals the error "Duplicate key detected" (ERR=134) if you did not specify DUPLICATES for the key in the OPEN statement. If you specified DUPLICATES, RMS stores the duplicate records in a first-in/first-out sequence.
8. The number specified in the COUNT clause determines how many bytes are transferred from the buffer to a file:
   - If you have not completely filled the record buffer before executing a PUT statement, BASIC pads the record with nulls to equal the specified value.
   - If the specified COUNT value is less than the buffer size, the record is truncated to equal the specified value.
   - The number in the COUNT clause must not exceed the size specified in the MAP or RECORDSIZE clause in the OPEN statement or BASIC signals "Size of record invalid" (ERR=156).
   - For files with fixed length records, the number in the COUNT clause must match the record size.

## Examples

Example 1

    !Sequential, Relative, Indexed, and Virtual Files
    PUT #3, COUNT 55%

Example 2

    !Relative and Virtual Files Only
    PUT #5, RECORD 133, COUNT 16%

Previous | Next | Contents | Index