HP OpenVMS Systems

BASIC

Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual

REMAP

The REMAP statement defines or redefines the position in the storage area of variables named in the MAP DYNAMIC statement.

Format

Syntax Rules

Map-dyn-name can be either a map name or a static string variable.
- Map-name is the storage area named in a MAP statement.
- If you specify a map name, then a MAP statement with the same name must precede both the MAP DYNAMIC statement and the REMAP statement.
- When you specify a static string variable, the string must be declared before you can specify a MAP DYNAMIC statement or a REMAP statement.
- If you specify a static-str-var, the following restrictions apply:
  - Static-str-var cannot be a string constant.
  - Static-str-var cannot be the same as any previously declared map-item in a MAP DYNAMIC statement.
  - If static-str-var is a parameter to the subprogram containing the REMAP statement, static-str-var cannot be a RECORD component.
  - Static-str-var cannot be a subscripted variable.
  - Static-str-var cannot be a parameter declared in a DEF or DEF* function.
Remap-item names a variable, array, or array element declared in a preceding MAP DYNAMIC statement:
- Num-var specifies a numeric variable or array element. Num-array-name followed by a set of empty parentheses specifies an entire numeric array.
- Str-var specifies a string variable or array element. Str-array-name followed by a set of empty parentheses, specifies an entire fixed-length string array. You can specify the number of bytes to be reserved for string variables and array elements with the =int-exp clause. The default string length is 16.
Remap-item can also be a FILL item. The FILL, FILL%, and FILL$ keywords let you reserve parts of the record buffer. Int-exp specifies the number of FILL items to be reserved. The =int-exp clause allows you to specify the number of bytes to be reserved for string FILL items. Table 4-1 describes FILL item format and storage allocation.

Note
In the FILL clause, (int-exp) represents a repeat count, not an array subscript. FILL (n), for example, represents n elements, not n + 1.
All remap-items, except FILL items, must have been named in a previous MAP DYNAMIC statement, or BASIC signals an error.
Data-type can be any BASIC data type keyword or a data type defined in a RECORD statement. Data type keywords and their size, range, and precision are listed in Table 1-2. You can specify a data type only for FILL items.
- When you specify a data type before a FILL keyword in a REMAP statement, the FILL item is of that data type. The specified data type applies only to that one FILL item.
- If you do not specify any data type for a FILL item, the FILL item takes the current default data type and size.
Remap-items must be separated with commas.

Remarks

The REMAP statement does not affect the amount of storage allocated to the map area.
Each time a REMAP statement executes, BASIC sets record pointers to the named map area for the specified variables from left to right.
The REMAP statement must be preceded by a MAP DYNAMIC statement or BASIC signals the error "No such MAP area <name>." The MAP statement or static string variable creates a named area of static storage, the MAP DYNAMIC statement specifies the variables whose positions can change at run time, and the REMAP statement specifies the new positions for the variables named in the MAP DYNAMIC statement.
Before you can specify a map name in a REMAP statement, there must be a MAP statement in the program unit with the same map name; otherwise, BASIC signals the error "<Name> is not a DYNAMIC MAP variable of MAP <name>." Similarly, before you can specify a static string variable in a REMAP statement, the string variable must be declared; otherwise, BASIC signals the same error message.
If a static string variable is the same as a map name, BASIC overrides the static string name and uses the map name.
Until the REMAP statement executes, all variables named in the MAP DYNAMIC statement point to the first byte of the MAP area and all string variables have a length of zero. When the REMAP statement executes, BASIC sets the internal pointers as specified in the REMAP statement. For example:
100 MAP (DUMMY) STRING map_buffer = 50 MAP DYNAMIC (DUMMY) LONG A, STRING B, SINGLE C(7) REMAP (DUMMY) B=14, A, C()
The REMAP statement sets a pointer to byte 1 of DUMMY for string variable B, a pointer to byte 15 for LONG variable A, and pointers to bytes 19, 23, 27, 31, 35, 39, 43, and 47 for the elements in SINGLE array C.
You can use the REMAP statement to redefine the pointer for an array element or variable more than once in a single REMAP statement. For example:
100 MAP (DUMMY) STRING FILL = 48 MAP DYNAMIC (DUMMY) LONG A, B(10) REMAP (DUMMY) B(), B(0)
This REMAP statement sets a pointer to byte 1 in DUMMY for array B. Because array B uses a total of 44 bytes, the pointer for the first element of array B, B(0) points to byte 45. References to array element B(0) will be to bytes 45 to 48. Pointers for array elements 1 to 10 are set to bytes 5, 9, 13, 17 and so on.
Because the REMAP statement is local to a program module, it affects pointers only in the program module in which it executes.

Examples

Example 1

DECLARE LONG CONSTANT emp_fixed_info = 4 + 9 + 2
MAP (emp_buffer) LONG badge,                     &
                 STRING social_sec_num = 9,      &
                 BYTE name_length,               &
                      address_length,            &
                      FILL (60)

MAP DYNAMIC (emp_buffer) STRING emp_name,        &
                                emp_address

WHILE 1%
        GET #1
        REMAP (emp_buffer) STRING FILL = emp_fixed_info,        &
                                 emp_name = name_length,        &
                                 emp_address = address_length

        PRINT emp_name
        PRINT emp_address
        PRINT

NEXT

END

Example 2

SUB deblock (STRING input_rec, STRING item())
 MAP DYNAMIC (input_rec) STRING A(1 TO 3)
 REMAP (input_rec) &
     A(1) = 5, &
     A(2) = 3, &
     A(3) = 4
 FOR I = LBOUND(A) TO UBOUND(A)
   item(I) = A(I)
 NEXT I
END SUB

RESET

The RESET statement is a synonym for the RESTORE statement. See the RESTORE statement for more information.

Format

RESTORE

The RESTORE statement resets the DATA pointer to the beginning of the DATA sequence, or sets the record pointer to the first record in a file.

Format

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number associated with a file. It must be immediately preceded by a number sign (#).
Int-exp must be between zero and the number of keys in the file minus 1. It must be immediately preceded by a number sign (#).

Remarks

If you do not specify a channel, RESTORE resets the DATA pointer to the beginning of the DATA sequence.
RESTORE affects only the current program unit. Thus, executing a RESTORE statement in a subprogram does not affect the DATA pointer in the main program.
If there is no channel specified, and the program has no DATA statements, RESTORE has no effect.
The file specified by chnl-exp must be open.
If chnl-exp specifies a magnetic tape file, BASIC rewinds the tape to the first record in the file.
The KEY clause applies to indexed files only. It sets a new key of reference equal to int-exp and sets the next record pointer to the first logical record in that key.
For indexed files, the RESTORE statement without a KEY clause sets the next record pointer to the first logical record specified by the current key of reference. If there is no current key of reference, the RESTORE statement sets the next record pointer to the first logical record of the primary key.
If you use the RESTORE statement on any file type other than indexed, BASIC sets the next record pointer to the first record in the file.
The RESTORE statement is not allowed on virtual array files or on files opened on unit record devices.
For information about the RESTORE GRAPHICS statement, see Programming with VAX BASIC Graphics.

Example

RESTORE #7%, KEY #4%

RESUME

The RESUME statement marks an exit point from an ON ERROR error-handling routine. BASIC clears the error condition and returns program control to a specified line number or label or to the program block in which the error occurred.

Note

The RESUME statement is supported for compatibility with other versions of BASIC. For new program development, it is recommended that you use WHEN blocks.

Format

Syntax Rules

Target must be a valid BASIC line number or label and must exist in the same program unit.

Remarks

The following restrictions apply:
- The RESUME statement cannot appear within a protected region, or within an attached or detached handler.
- The target of a RESUME statement cannot exist within a protected region or handler.
- The RESUME statement cannot be used in a multiline DEF unless the target is also in the DEF function definition.
- The execution of a RESUME with no target is illegal if there is no error active.
- A RESUME statement cannot transfer control out of the current program unit. Therefore, a RESUME statement with no target cannot terminate an error handler if the error handler is handling an error that occurred in a subprogram or an external function, and the error was passed to the calling program's error handler by an ON ERROR GO BACK statement or by default.
When no target is specified in a RESUME statement, BASIC transfers control based on where the error occurs. If the error occurs on a numbered line containing a single statement, BASIC always transfers control to that statement. When the error occurs within a multistatement line under the following conditions, BASIC acts as follows:
- After a loop or SELECT block, BASIC transfers control to the statement that follows the NEXT or END SELECT statement.
- If not after a loop or SELECT block, but within a FOR, WHILE, or UNTIL loop, BASIC transfers control to the first statement that follows the FOR, WHILE, or UNTIL statement.
- If not after a loop or SELECT block, but within a SELECT block, BASIC transfers control to the start of the CASE block in which the error occurs.
- If none of the above conditions occurs, BASIC transfers control back to the statement that follows the most recent line number.
A RESUME statement with a specified line number transfers control to the first statement of a multistatement line, regardless of which statement caused the error.
A RESUME statement with a specified label transfers control to the block of code indicated by that label.

Example

Error_routine:
IF ERR = 11
   THEN
      CLOSE #1
      RESUME end_of_prog
ELSE
      RESUME
END IF
end_of_prog: END

RETRY

The RETRY statement clears an error condition and reexecutes the statement that caused the error inside a protected region of a WHEN block.

Format

Syntax Rules

The RETRY statement must appear lexically inside of a handler associated with a WHEN block.

Remarks

The following rules apply to errors that occur during execution of loop control statements (not the statements inside the loop body):

In FOR...NEXT loops, the RETRY statement reexecutes the FOR statement if the error occurs while BASIC is evaluating the limit or increment values.
In FOR...NEXT loops, if the error occurs while BASIC is evaluating the index variable, the RETRY statement reexecutes the NEXT statement.
In a FOR...UNTIL or FOR...WHILE loop, if an error occurs while BASIC is evaluating the relational expression, the RETRY statement reexecutes the NEXT statement.

Example

10 DECLARE LONG YOUR_AGE
   WHEN ERROR IN
        INPUT "Enter your age";your_age
   USE
        IF ERR = 50
           THEN RETRY
           ELSE EXIT HANDLER
        END IF
   END WHEN

RETURN

The RETURN statement transfers control to the statement immediately following the most recently executed GOSUB or ON...GOSUB statement in the current program unit.

Format

Syntax Rules

None

Remarks

Once the RETURN is executed in a subroutine, no other statements in the subroutine are executed, even if they appear after the RETURN statement.
Execution of a RETURN statement before the execution of a GOSUB or ON...GOSUB causes BASIC to signal "RETURN without GOSUB" (ERR=72).

Example

GOSUB subroutine_1
   .
   .
   .
subroutine_1:
   .
   .
   .
RETURN

RIGHT$

The RIGHT$ function extracts a substring from a string's right side, leaving the string unchanged.

Format

Syntax Rules

None

Remarks

The RIGHT$ function extracts a substring from str-exp and stores the substring in str-var. The substring begins with the character in the position specified by int-exp and ends with the rightmost character in the string.
If int-exp is less than or equal to zero, RIGHT$ returns the entire string.
If int-exp is greater than the length of str-exp, RIGHT$ returns a null string.
If you specify a floating-point expression for int-exp, BASIC truncates it to a LONG integer.

Example

DECLARE STRING main_str,   &
               end_result
main_str = "1234567"
end_result = RIGHT$(main_str, 3)
PRINT end_result

Output

RMSSTATUS

The RMSSTATUS function returns the RMS status or the status value of the last I/O operation on a specified open I/O channel.

Format

Syntax Rules

Chnl-exp must be the number of a channel opened from a BASIC routine.
Chnl-exp cannot be zero.

Remarks

If chnl-exp does not represent an open channel, BASIC signals the error "I/O channel not open" (ERR=9).
If you do not specify either STATUS or VALUE, RMSSTATUS returns the STATUS value by default.
If you specify STATUS, RMSSTATUS returns the FAB$L_STS or the RAB$L_STS status value. However, if you specify VALUE, RMSSTATUS returns the FAB$L_STV or the RAB$L_STV status value.
Use the RMSSTATUS function to return the status of the following operations:
- RESTORE
- GET
- PUT
- UPDATE
- UNLOCK
- PRINT and PRINT USING
- INPUT, INPUT LINE, and LINPUT
- SCRATCH
- FREE
- Virtual array references
To determine the reason for the failure of an OPEN, CLOSE, KILL, or NAME...AS statement, use the VMSSTATUS function within an error handler.

Examples

Example 1

%TITLE "RMSSTATUS Example"
%SBTTL "Reference Manual Examples"
%IDENT "V1.0"

PROGRAM Demo_RMSSTATUS_function
    OPTION CONSTANT TYPE = INTEGER

    OPEN "DOES_NOT_EXIST.LIS" FOR OUTPUT AS 1,  &
        SEQUENTIAL VARIABLE,                    &
        RECORDSIZE 80

    WHEN ERROR IN
        GET #1
    USE
        PRINT "GET Operation failed"
        PRINT "RMS Status ="; RMSSTATUS(1,STATUS)
        PRINT "RMS Status Value ="; RMSSTATUS(1,VALUE)
    END WHEN

END PROGRAM

Example 2

    OPTION TYPE=EXPLICIT
    EXTERNAL LONG CONSTANT RMS$_OK_DUP

    MAP (ORDER) LONG ORD_ENTRY, STRING ORD_CUST_NO = 6%,   &
        STRING ORD_REMARK = 50%

    OPEN "ORD_DB" FOR INPUT AS FILE 1%,              &
        ORGANIZATION INDEXED FIXED,                  &
        MAP ORDER,                                   &
        PRIMARY ORD_ENTRY NODUPLICATES,              &
        ALTERNATE ORD_CUST_NO DUPLICATES
    INPUT "Enter order number";ORD_ENTRY
    INPUT "Enter customer number";ORD_CUST_NO
    INPUT "Remark";ORD_REMARK

    !
    ! Enter the order in the order database
    ! Check if the customer has other orders
    !
    PUT #1%
    IF RMSSTATUS( 1%, STATUS ) = RMS$_OK_DUP
    THEN
        !
        ! The customer has other orders; compute the customer's
        ! discount for other orders
        !
    END IF

    CLOSE 1%
    END

RND

The RND function returns a random number greater than or equal to zero and less than 1.

Format

Syntax Rules

None

Remarks

If the RND function is preceded by a RANDOMIZE statement, BASIC generates a different random number or series of numbers each time a program executes.
The RND function returns a pseudorandom number if not preceded by a RANDOMIZE statement; that is, each time a program runs, BASIC generates the same random number or series of random numbers.
The RND function returns a floating-point SINGLE value.
The RND function returns values over a uniform distribution from 0 to 1. For example, a value from 0 to .1 is as likely as a value from .5 to .6. Note the difference between this and a bell-curve distribution where the probability of values in the range .3 to .7 is higher than the outer ranges.

Example

DECLARE REAL random_num
RANDOMIZE
FOR I = 1 TO 3   !FOR loop causes BASIC to print three random numbers

        random_num = RND
        PRINT random_num

NEXT I

Output

 .865243
 .477417
 .734673

Contents

Index

HP OpenVMS Systems

Compaq BASIC for OpenVMS Alpha and VAX SystemsReference Manual

REMAP

Format

Syntax Rules

Remarks

Examples

RESET

Format

RESTORE

Format

Syntax Rules

Remarks

Example

RESUME

Format

Syntax Rules

Remarks

Example

RETRY

Format

Syntax Rules

Remarks

Example

RETURN

Format

Syntax Rules

Remarks

Example

RIGHT$

Format

Syntax Rules

Remarks

Example

RMSSTATUS

Format

Syntax Rules

Remarks

Examples

RND

Format

Syntax Rules

Remarks

Example

Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual