# Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

Previous | Contents | Index

# UPDATE

> The UPDATE statement replaces a record in a file with a record in the record buffer. The UPDATE statement is valid on sequential, relative, and indexed 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. Int-exp specifies the size of the new record.

## Remarks

1. The file associated with chnl-exp must be a disk file opened with ACCESS MODIFY.
2. Each UPDATE statement must be preceded by a successful GET or FIND operation or BASIC signals "No current record" (ERR=131). FIND locates but does not retrieve records. Therefore, you must specify a COUNT clause when retrieving variable-length records when the preceding operation was a FIND. Int-exp must exactly match the size of the old record.
3. If you are updating a variable-length record, and the record that you want to write out is not the same size as the record you retrieved, you must use a COUNT clause.
4. After an UPDATE statement executes, there is no current record pointer. The next record pointer is unchanged.
5. The length of the new record must be the same as that of the existing record for all files with fixed-length records and for all sequential files. If you specify a COUNT clause, the int-exp must match the size of the existing record.
6. For relative files with variable-length records, the new record can be larger or smaller than the record it replaces.
   - The new record must be smaller than or equal to the maximum record size set with the MAP or RECORDSIZE clause when the file was opened.
   - You must use the COUNT clause to specify the size of the new record if it is different from that of the record last accessed by a GET operation on that channel.
7. For indexed files with variable-length records, the new record can be larger or smaller than the record it replaces. When the program does not permit duplicate primary keys, the new record can be no longer than the size specified by the MAP or RECORDSIZE clause when the file was opened. The record must include at least the primary key field.
8. An indexed file alternate key for the new record can differ from that of the existing record only if the OPEN statement for that file specified CHANGES for the alternate key.

## Example

    UPDATE #4%, COUNT 32

# VAL

> The VAL function converts a numeric string to a floating-point value.

Note It is recommended that you use the DECIMAL, REAL, and INTEGER functions to convert numeric strings to numeric data types.

## Format

## Syntax Rules

Str-exp can contain the ASCII digits 0 to 9, uppercase E, a plus sign (+), a minus sign (-), and a period (.).

## Remarks

1. The VAL function ignores spaces and tabs.
2. If str-exp is null, or contains only spaces and tabs, VAL returns a value of zero.
3. The value returned by the VAL function is of the default floating-point size.

## Example

    DECLARE REAL real_num
    real_num = VAL("990.32")
    PRINT real_num

Output

     990.32

# VAL%

> The VAL% function converts a numeric string to an integer.

Note It is recommended that you use the DECIMAL, REAL, and INTEGER functions to convert numeric strings to numeric data types.

## Format

## Syntax Rules

Str-exp can contain the ASCII digits 0 to 9, a plus sign (+), or a minus sign (-).

## Remarks

1. The VAL% function ignores spaces and tabs.
2. If str-exp is null or contains only spaces and tabs, VAL% returns a value of zero.
3. The value returned by the VAL% function is an integer of the default size.

## Example

    DECLARE INTEGER ret_int
    ret_int = VAL%("789")
    PRINT ret_int

Output

     789

# VMSSTATUS

> VMSSTATUS returns the underlying OpenVMS condition code when control is transferred to a BASIC error handler.

## Format

## Syntax Rules

None

## Remarks

1. If ERR contains the value 194, you can specify VMSSTATUS to examine the actual error that was signaled to BASIC.
2. If an error is raised by an underlying system component such as the Run-Time Library, you can specify VMSSTATUS to determine the underlying error.
3. If you are writing a utility routine that may be called from languages other than BASIC, you can specify VMSSTATUS in a call to LIB$SIGNAL to signal the underlying error to the caller of the utility routine.
4. When there is no error pending, VMSSTATUS remains undefined.
5. VMSSTATUS always returns a LONG integer.

## Example

    PROGRAM
    WHEN ERROR USE global_handler
       .
       .
       .
    END WHEN
       .
       .
       .
    HANDLER global_handler
    final_status% = VMSSTATUS
    END HANDLER
    END PROGRAM final_status%

# WAIT

> The WAIT statement specifies the number of seconds the program waits for terminal input before signaling an error.

## Format

## Syntax Rules

Int-exp must be from 0 to 255; if it is greater than 255, BASIC assumes a value of 255.

## Remarks

1. The WAIT statement must precede a GET operation to a terminal or an INPUT, INPUT LINE, LINPUT, MAT INPUT, or MAT LINPUT statement. Otherwise, it has no effect.
2. Int-exp is the number of seconds BASIC waits for input before signaling the error, "Keyboard wait exhausted" (ERR=15).
3. After BASIC executes a WAIT statement, all input statements wait the specified amount of time before BASIC signals an error.
4. WAIT 0 disables the WAIT statement.

## Example

    10  DECLARE STRING your_name
        WAIT 60
        INPUT "You have sixty seconds to type your name";your_name
        WAIT 0

Output

    You have sixty seconds to type your name?
    %BAS-F-KEYWAIEXH, Keyboard wait exhausted
    -BAS-I-ON_CHAFIL, on channel 0 for file SYS$INPUT:.; at user PC 00000644
    -RMS-W-TMO, timeout period expired
    -BAS-I-FROLINMOD, from line 10 in module WAIT
    %TRACE-F-TRACEBACK, symbolic stack dump follows
    module name     routine name                    line       rel PC   abs PC

                                                              00007334 00007334
    ----- above condition handler called with exception 001A807C:
    %BAS-F-KEYWAIEXH, keyboard wait exhausted
    -BAS-I-ON_CHAFIL, on channel 0 for file SYS$INPUT:.; at user PC 00000644
    -RMS-W-TMO, timeout period expired
    ----- end of exception message
                                                               00011618  00011618
                                                               0000F02F  0000F02F
                                                               0000E3F6  0000E3F6
                                                               0001387A  0001387A
    WAIT$MAIN      WAIT$MAIN                            3      00000044  00000644

# WHEN ERROR

> The WHEN ERROR statement marks the beginning of a WHEN ERROR construct. The WHEN ERROR construct contains a protected region and can include an attached handler or identify a detached handler.

## Format

## Syntax Rules

1. Protected-statement specifies a statement that appears within a protected region. A protected region is a special block of code that is monitored by BASIC for the occurrence of a run-time error.
2. Handler-statement specifies the statement that appears inside an error handler.
3. With an Attached Handler
   - The keyword USE marks the start of handler statements.
   - An attached handler must be delimited by a USE and END WHEN statement.
4. With a Detached Handler
   - The keyword USE names the associated handler for the protected region.
   - Handler-name must be a valid BASIC identifier and cannot be the same as any label, DEF, DEF*, SUB, FUNCTION, or PICTURE name within the same program unit.
   - A detached handler must be delimited by a HANDLER and END HANDLER statement.
   - You can specify the same detached handler with more than one WHEN ERROR USE statement.

## Remarks

1. The WHEN ERROR statement designates the start of a block of protected statements.
2. If an error occurs inside a protected region, BASIC transfers control to the error handler associated with the WHEN ERROR statement.
3. BASIC does not allow you to branch into a WHEN block.
4. When BASIC encounters an END WHEN statement for an attached handler or an END HANDLER statement for a detached handler, BASIC clears the exception and transfers control to the following statement.
5. BASIC allows you to nest WHEN blocks. If an exception occurs within a nested protected region, BASIC transfers control to the handler associated with the innermost protected region in which the error occurred.
6. WHEN blocks cannot exist inside a handler.
7. WHEN blocks cannot cross other block structures.
8. You cannot specify a RESUME statement within a WHEN ERROR construct.
9. You cannot specify an ON ERROR statement within a protected region.
10. An attached handler must immediately follow the protected region of a WHEN ERROR IN block.
11. Exit from a handler must occur through a RETRY, CONTINUE, or EXIT HANDLER statement, or by reaching the end of the handler delimited by END WHEN or END HANDLER.
12. For more information about detached handlers, see the HANDLER statement.

## Examples

Example 1

    !With an attached handler
    PROGRAM salary
    DECLARE REAL hourly_rate, no_of_hours, weekly_pay
    WHEN ERROR IN
         INPUT "Enter your hourly rate";hourly_rate
         INPUT "Enter the number of hours you worked this week";no_of_hours
         weekly_pay = no_of_hours * hourly_rate
         PRINT "Your pay for this week is";weekly_pay

    USE
         SELECT ERR
             CASE = 50
                   PRINT "Invalid data"
                   RETRY
             CASE ELSE
                  EXIT HANDLER
         END SELECT
    END WHEN
    END PROGRAM

Output

    Enter your hourly rate? 35.00
    Enter the number of hours you worked this week? 45
    Your pay for this week is 1575

Example 2

    !With a detached handler
    PROGRAM salary
    DECLARE REAL hourly_rate, no_of_hours, weekly_pay
    WHEN ERROR USE patch_work
         INPUT "Enter your hourly rate";hourly_rate
         INPUT "Enter the number of hours you worked this week";no_of_hours
         weekly_pay = no_of_hours * hourly_rate
         PRINT "Your pay for this week is";weekly_pay
    END WHEN

    HANDLER patch_work
         SELECT ERR
             CASE = 50
                   PRINT "Invalid data"
                   RETRY
             CASE ELSE
                  EXIT HANDLER
         END SELECT
    END HANDLER
    END PROGRAM

Output

    Enter your hourly rate?  Nineteen dollars and fifty cents
    Invalid data
    Enter your hourly rate? 19.50
    Enter the number of hours you worked this week? 40
    Your pay for this week is 780

# WHILE

> The WHILE statement marks the beginning of a WHILE loop or modifies the execution of another statement.

## Format

## Syntax Rules

A NEXT statement must end the WHILE loop.

## Remarks

1. Conditional
   BASIC evaluates cond-exp before each loop iteration. If the expression is true (value nonzero), BASIC executes the loop. If the expression is false (value zero), control passes to the first executable statement after the NEXT statement.
2. Statement Modifier
   BASIC executes the statement repeatedly as long as cond-exp is true.

## Examples

Example 1

    !Conditional
    WHILE X < 100
        X = X + SQR(X)
    NEXT

Example 2

    !Statement Modifier
    X% = X% + 1% WHILE X% < 100%

# XLATE$

> The XLATE$ function translates one string to another by referencing a table string you supply.

## Format

## Syntax Rules

1. Str-exp1 is the input string.
2. Str-exp2 is the table string.

## Remarks

1. Str-exp2 can contain up to 256 ASCII characters, numbered from 0 to 255; the position of each character in the string corresponds to an ASCII value. Because 0 is a valid ASCII value (null), the first position in the table string is position zero.
2. XLATE$ scans str-exp1 character by character, from left to right. It finds the ASCII value n of the first character in str-exp1 and extracts the character it finds at position n in str-exp2. XLATE$ then appends the character from str-exp2 to str-var. XLATE$ continues this process, character by character, until the end of str-exp1 is reached.
3. The output string may be smaller than the input string for the following reasons:
   - XLATE$ does not translate nulls. If the character at position n in str-exp2 is a null, XLATE$ does not append that character to str-var.
   - If the ASCII value of the input character is outside the range of positions in str-exp2, XLATE$ does not append any character to str-var.

## Example

    DECLARE STRING A, table, source
    A = "abcdefghijklmnopqrstuvwxyz"
    table = STRING$(65, 0) + A
    LINPUT " Type a string of uppercase letters"; source
    PRINT XLATE$(source, table)

Output

    Type a string of uppercase letters? ABCDEFG
    abcdefg

# Appendix A
ASCII Character Codes

ASCII is a 7-bit character code with an optional parity bit (8) added for many devices. Programs normally use seven bits internally with the eighth bit being zero; the extra bit is either stripped (on input) or added by a device driver (on output) so the program will operate with either parity- or nonparity-generating devices. The eighth bit is reserved for future standardization.

The International Reference Version (IRV) of ISO Standard 646 is identical to the IRV in CCITT Recommendation V.3 (International alphabet No. 5). The character sets are the same as ASCII except that the ASCII dollar sign (hexadecimal 24) is the international currency sign (###).

ISO Standard 646 and CCITT V.3 also specify the structure for national character sets, of which ASCII is the U.S. national set. Certain specific characters are reserved for national use. Table A-1 contains the values and symbols.

Table A-1 ASCII Characters Reserved for National Use
Hexadecimal Value | IRV | ASCII
--- | --- | ---
23 | # | #
24 | ### | $ (General currency symbol vs. dollar sign)
40 | @ | @
5B | [ | [
5C | \ | \
5D | ] | ]
5E | ^ | ^
60 | ` | `
7B | { | {
7C | | | |
7D | } | }
7E | ~ | Tilde

ISO Standard 646 and CCITT Recommendation V.3 (International Alphabet No. 5) are identical to ASCII except that the number sign (23) is represented as ## instead of #, and certain characters are reserved for national use. Table A-2 list the ASCII codes.

Table A-2 ASCII Codes
Decimal Code | 8-Bit Hexadecimal Code | Character | Remarks
--- | --- | --- | ---
0 | 00 | NUL | Null (tape feed)
1 | 01 | SOH | Start of heading (^A)
2 | 02 | STX | Start of text (end of address, ^B)
3 | 03 | ETX | End of text (^C)
4 | 04 | EOT | End of transmission (shuts off the TWX machine ^D)
5 | 05 | ENQ | Enquiry (WRU, ^E)
6 | 06 | ACK | Acknowledge (RU, ^F)
7 | 07 | BEL | Bell (^G)
8 | 08 | BS | Backspace (^H)
9 | 09 | HT | Horizontal tabulation (^I)
10 | 0A | LF | Line feed (^J)
11 | 0B | VT | Vertical tabulation (^K)
12 | 0C | FF | Form feed (page, ^L)
13 | 0D | CR | Carriage return (^M)
14 | 0E | SO | Shift out (^N)
15 | 0F | SI | Shift in (^O)
16 | 10 | DLE | Data link escape (^P)
17 | 11 | DC1 | Device control 1 (^Q)
18 | 12 | DC2 | Device control 2 (^R)
19 | 13 | DC3 | Device control 3 (^S)
20 | 14 | DC4 | Device control 4 (^T)
21 | 15 | NAK | Negative acknowledge (ERR, ^U)
22 | 16 | SYN | Synchronous idle (^V)
23 | 17 | ETB | End-of-transmission block (^W)
24 | 18 | CAN | Cancel (^X)
25 | 19 | EM | End of medium (^Y)
26 | 1A | SUB | Substitute (^Z)
27 | 1B | ESC | Escape (prefix of escape sequence)
28 | 1C | FS | File separator
29 | 1D | GS | Group separator
30 | 1E | RS | Record separator
31 | 1F | US | Unit separator
32 | 20 | SP | Space
33 | 21 | ! | Exclamation point
34 | 22 | " | Double quotation mark
35 | 23 | # | Number sign
36 | 24 | $ | Dollar sign
37 | 25 | % | Percent sign
38 | 26 | & | Ampersand
39 | 27 | ' | Apostrophe
40 | 28 | ( | Left (open) parenthesis
41 | 29 | ) | Right (close) parenthesis
42 | 2A | * | Asterisk
43 | 2B | + | Plus sign
44 | 2C | , | Comma
45 | 2D | -- | Minus sign, hyphen
46 | 2E | . | Period (decimal point)
47 | 2F | / | Slash (slant)
48 | 30 | 0 | Zero
49 | 31 | 1 | One
50 | 32 | 2 | Two
51 | 33 | 3 | Three
52 | 34 | 4 | Four
53 | 35 | 5 | Five
54 | 36 | 6 | Six
55 | 37 | 7 | Seven
56 | 38 | 8 | Eight
57 | 39 | 9 | Nine
58 | 3A | : | Colon
59 | 3B | ; | Semicolon
60 | 3C | < | Less than (left angle bracket)
61 | 3D | = | Equal sign
62 | 3E | > | Greater than (right angle bracket)
63 | 3F | ? | Question mark
64 | 40 | @ | Commercial at
65 | 41 | A | Uppercase A
66 | 42 | B | Uppercase B
67 | 43 | C | Uppercase C
68 | 44 | D | Uppercase D
69 | 45 | E | Uppercase E
70 | 46 | F | Uppercase F
71 | 47 | G | Uppercase G
72 | 48 | H | Uppercase H
73 | 49 | I | Uppercase I
74 | 4A | J | Uppercase J
75 | 4B | K | Uppercase K
76 | 4C | L | Uppercase L
77 | 4D | M | Uppercase M
78 | 4E | N | Uppercase N
79 | 4F | O | Uppercase O
80 | 50 | P | Uppercase P
81 | 51 | Q | Uppercase Q
82 | 52 | R | Uppercase R
83 | 53 | S | Uppercase S
84 | 54 | T | Uppercase T
85 | 55 | U | Uppercase U
86 | 56 | V | Uppercase V
87 | 57 | W | Uppercase W
88 | 58 | X | Uppercase X
89 | 59 | Y | Uppercase Y
90 | 5A | Z | Uppercase Z
91 | 5B | [ | Left square bracket
92 | 5C | \ | Backslash (reverse slant)
93 | 5D | ] | Right square bracket
94 | 5E | ^ | Circumflex (caret)
95 | 5F | _ | Underscore (underline)
96 | 60 | ` | Grave accent
97 | 61 | a | Lowercase a
98 | 62 | b | Lowercase b
99 | 63 | c | Lowercase c
100 | 64 | d | Lowercase d
101 | 65 | e | Lowercase e
102 | 66 | f | Lowercase f
103 | 67 | g | Lowercase g
104 | 68 | h | Lowercase h
105 | 69 | i | Lowercase i
106 | 6A | j | Lowercase j
107 | 6B | k | Lowercase k
108 | 6C | l | Lowercase l
109 | 6D | m | Lowercase m
110 | 6E | n | Lowercase n
111 | 6F | o | Lowercase o
112 | 70 | p | Lowercase p
113 | 71 | q | Lowercase q
114 | 72 | r | Lowercase r
115 | 73 | s | Lowercase s
116 | 74 | t | Lowercase t
117 | 75 | u | Lowercase u
118 | 76 | v | Lowercase v
119 | 77 | w | Lowercase w
120 | 78 | x | Lowercase x
121 | 79 | y | Lowercase y
122 | 7A | z | Lowercase z
123 | 7B | { | Left brace
124 | 7C | | | Vertical line
125 | 7D | } | Right brace
126 | 7E | ~ | Tilde
127 | 7F | DEL | Delete (rubout)

Previous | Next | Contents | Index