Compaq BASIC for OpenVMS
Alpha and VAX Systems
Reference Manual
Previous Contents Index

BUFSIZ

The BUFSIZ function returns the record buffer size, in bytes, of a specified channel.

Format

Syntax Rules

  1. Chnl-exp is a numeric expression that specifies a channel number.
  2. The value assigned to int-var is a LONG integer.

Remarks

  1. If the specified channel is closed, BUFSIZ returns a value of zero.
  2. BUFSIZ of channel #0 always returns the value 132.

Example


DECLARE LONG buffer_size 
buffer_size = BUFSIZ(0) 
PRINT "Buffer size equals";buffer_size

Output 


Buffer size equals 132

CALL

The CALL statement transfers control to a subprogram, external function, or other callable routine. You can pass arguments to the routine and can optionally specify passing mechanisms. When the called routine finishes executing, control returns to the calling program.

Format

Syntax Rules

  1. Routine is the name of a SUB subprogram or any other callable procedure, such as a system service or an RTL routine you want to call. It cannot be a variable name. See the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual for more information about using system services, RTL routines, and other procedures.
  2. You should use parameter-passing mechanisms only when calling non BASIC routines or when a subprogram expects to receive a string or entire array by reference.
    For more information about parameter-passing mechanisms, see the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual.
  3. When pass-mech appears before the parameter list, it applies to all arguments passed to the called routine. You can override this passing mechanism by specifying a pass-mech for individual arguments in the actual-param list.
  4. Actual-param lists the arguments to be passed to the called routine.
  5. You can pass expressions or entire arrays. Optional commas in parentheses after the array name specify the dimensions of the array. The number of commas is equal to the number of dimensions -1. Thus, no comma specifies a one-dimensional array, one comma specifies a two-dimensional array, two commas specify a three-dimensional array, and so on.
  6. You cannot pass entire virtual arrays.
  7. The name of the routine can be from 1 to 31 characters and must conform to the following rules:
  8. BASIC allows you to pass up to 255 parameters.

Remarks

  1. You can specify a null argument as an actual-param for non BASIC routines by omitting the argument and the pass-mech, but not the commas or parentheses. This forces BASIC to pass a null argument and allows you to access system routines from BASIC.
  2. Arguments in the actual-param list must agree in data type and number with the formal parameters specified in the subprogram.
  3. An argument is modifiable when changes to it are evident in the calling program. Changing a modifiable parameter in a subprogram means the parameter is changed for the calling program as well. Variables and entire arrays passed by descriptor or by reference are modifiable.
  4. An argument is nonmodifiable when changes to it are not evident in the calling program. Changing a nonmodifiable argument in a subprogram does not affect the value of that argument in the calling program. Arguments passed by value, constants, and expressions are nonmodifiable. Passing an argument as an expression (by placing it in parentheses) changes it from a modifiable to a nonmodifiable argument. Virtual array elements passed as parameters are nonmodifiable.

  5. BASIC will automatically convert numeric actual parameters to match the declared data type. If the actual parameter is a variable, BASIC signals the informational message "Mode for parameter <n> of routine <name> changed to match declaration" and passes the argument by local copy. This prevents the called routine from modifying the contents of the variable.
  6. For expressions and virtual array elements passed by reference, BASIC makes a local copy of the value, and passes the address of this local copy. For dynamic string arrays, BASIC passes a descriptor of the array of string descriptors. The compiler passes the address of the argument's actual value for all other arguments passed by reference.
  7. In VAX BASIC, only BYTE, WORD, LONG, and SINGLE values can be passed by value. BYTE and WORD values passed by value are converted to LONG values.
  8. In Alpha BASIC, you can pass BYTE, WORD, LONG, QUAD, DOUBLE, GFLOAT, SINGLE, SFLOAT, and TFLOAT values by value.
  9. If you attempt to call an external function, BASIC treats the function as if it were invoked normally and validates all parameters. Note that you cannot call a STRING, HFLOAT, or RFA function. See the EXTERNAL statement for more information about how to invoke functions.

Example


EXTERNAL SUB LIB$PUT_OUTPUT (string) 
DECLARE STRING msg_str 
msg_str = "Successful call to LIB$PUT_OUTPUT!" 
CALL LIB$PUT_OUTPUT (msg_str)

Output 


Successful call to LIB$PUT_OUTPUT!

CAUSE ERROR

The CAUSE ERROR statement allows you to artificially generate a BASIC run-time error and transfer program control to a BASIC error handler.

Format

Syntax Rules

Err-num should be a valid BASIC run-time error number.

Remarks

All error numbers are listed in the Compaq BASIC for OpenVMS Alpha and VAX Systems User Manual. Any error outside the valid range of BASIC Run-Time Library errors results in the following error message: "NOTBASIC, Not a BASIC error" (ERR=194).

Example


WHEN ERROR IN 
   .
   .
   .
CAUSE ERROR 11% 
   .
   .
   .
USE 
    SELECT ERR 
        CASE = 11 
             PRINT "End of file" 
             CONTINUE 
        CASE ELSE 
             EXIT HANDLER 
    END SELECT 
END WHEN

CCPOS

The CCPOS function returns the current character or cursor position of the output record on a specified channel.

Format

Syntax Rules

Chnl-exp must specify an open file or terminal.

Remarks

  1. If chnl-exp is zero, CCPOS returns the current character position of the controlling terminal.
  2. The int-var returned by the CCPOS function is of the default integer size.
  3. The CCPOS function counts only characters. If you use cursor addressing sequences such as escape sequences, the value returned will not be the cursor position.
  4. The first character position on a line is zero.

Example


DECLARE LONG curs_pos 
PRINT "Hello"; 
curs_pos = CCPOS (0) 
PRINT curs_pos

Output 


Hello 5

CHAIN

The CHAIN statement transfers control from the current program to another executable image. CHAIN closes all files, then requests that the new program begin execution. Control does not return to the original program when the new image finishes executing.

Note
The CHAIN statement is not recommended for new program development. It is recommended that you use subprograms and external functions for program segmentation.

Format

Syntax Rules

Str-exp represents the file specification of the program to which control is passed.

Remarks

  1. Str-exp must refer to an executable image or BASIC signals an error.
  2. If you do not specify a file type, BASIC searches for an .EXE file type.
  3. You cannot chain to a program on another node.
  4. Execution starts at the beginning of the specified program.
  5. Before chaining takes place, all active output buffers are written, all open files are closed, and all storage is released.

  6. Because a CHAIN statement passes control from the executing image, the values of any program variables are lost. This means that you can pass parameters to a chained program only by using files or a system-specific feature such as LIB$GET_COMMON and LIB$PUT_COMMON.

Example


DECLARE STRING time_out 
time_out = "Friday" 
PRINT ASCII(time_out) 
CHAIN "CCPOS"

Output 


 70 
The current cursor position is 0

In this example, the executing image ASCII.EXE passes control to the chained program, CCPOS.EXE. The value that results from ASCII.EXE is 70. The second line of output reflects the value that results from CCPOS.EXE.

CHANGE

The CHANGE statement either converts a string of characters to their ASCII integer values or converts a list of numbers to a string of ASCII characters.

Format

Syntax Rules

  1. Str-exp is a string expression.
  2. Num-array-name should be a one-dimensional array. If you specify a two-dimensional array, BASIC converts only the first row of that array. BASIC does not support conversion to or from arrays of more than two dimensions.
  3. str-var is a string variable.

Remarks

  1. BASIC does not support RECORD elements as a destination string or as a source or destination array for the CHANGE statement.
  2. String Variable to Array
  3. Array to String Variable

Example


DECLARE STRING ABCD, A 
DIM INTEGER array_changes(6) 
ABCD = "ABCD" 
CHANGE ABCD TO array_changes 
FOR I% = 0 TO 4 
PRINT array_changes(I%) 
NEXT I% 
CHANGE array_changes TO A 
PRINT A

Output 


 4 
 65 
 66 
 67 
 68 
ABCD

CHR$

The CHR$ function returns a 1-character string that corresponds to the ASCII value you specify.

Format

Syntax Rules

None

Remarks

  1. CHR$ returns the character whose ASCII value equals int-exp. If int-exp is greater than 255, BASIC treats it as modulo 256. For example, CHR$(325) is the same as CHR$(69).
  2. If you specify a floating-point expression for int-exp, BASIC truncates it to an integer of the default size.

Example


DECLARE INTEGER num_exp 
INPUT "Enter the ASCII value you wish to be converted";num_exp 
PRINT "The equivalent character is ";CHR$(num_exp)

Output 


Enter the ASCII value you wish to be converted? 89 
The equivalent character is Y

CLOSE

The CLOSE statement ends I/O processing to a device or file on the specified channel.

Format

Syntax Rules

Chnl-exp is a numeric expression that specifies a channel number associated with a file. It can be preceded by an optional number sign (#).

Remarks

  1. BASIC writes the contents of any active output buffers to the file or device before it closes that file or device.
  2. Channel #0 (the controlling terminal) cannot be closed. An attempt to do so has no effect.
  3. If you close a magnetic tape file that is open for output, BASIC writes an end-of-file on the magnetic tape.
  4. If you try to close a channel that is not currently open, BASIC does not signal an error and the CLOSE statement has no effect.

Example


OPEN "COURSE_REC.DAT" FOR INPUT AS #2 
INPUT #2, course_nam, course_num, course_desc, course_instr 
   .
   .
   .
CLOSE #2

In this example, COURSE_REC.DAT is opened for input. After you have retrieved all of the required information, the file is closed.

COMMON

The COMMON statement defines a named, shared storage area called a COMMON block or program section (PSECT). BASIC program modules can access the values stored in the COMMON block by specifying a COMMON block with the same name.

Format

Syntax Rules

  1. A COMMON block can have the same name as a program variable.
  2. A COMMON block and a map in the same program module cannot have the same name.
  3. All COMMON elements must be separated with commas.
  4. Com-name is optional. If you specify a com-name, it must be in parentheses. If you do not specify a com-name, the default is $BLANK.
  5. Com-name can be from 1 through 31 characters. The first character of the name must be an alphabetic character (A to Z). The remaining characters, if present, can be any combination of letters, digits (0 to 9), dollar signs ($), periods (.), or underscores (_).
  6. Data-type can be any BASIC data type keyword or a data type defined in the RECORD statement. Data type keywords, size, range, and precision are listed in Table 1-2.
  7. When you specify a data type, all following com-items, including FILL items, are of that data type until you specify a new data type.
  8. If you do not specify any data type, com-items take the current default data type and size.
  9. Com-item declares the name and format of the data to be stored.

Remarks

  1. Variables in a COMMON area are not initialized by BASIC.
  2. A COMMON area and a MAP area with the same name, in different program modules, specify the same storage area.
  3. BASIC does not execute COMMON statements. The COMMON statement allocates and defines the data storage area at compilation time.
  4. When you link your program, the size of the COMMON area is the size of the largest COMMON area with that name. BASIC concatenates COMMON statements with the same com-name within a single program module into a single PSECT. The total space allocated is the sum of the space allocated in the concatenated COMMON statements.
    If you specify the same com-name in several program modules, the size of the PSECT will be determined by the program module that has the greatest amount of space allocated in the concatenated COMMON statements.
  5. The COMMON statement must lexically precede any reference to variables declared in it.
  6. A COMMON area can be accessed by more than one program module, as long as you define the com-name in each module that references the COMMON area.
  7. Variable names in a COMMON statement in one program module need not match those in another program module.
  8. Variables and arrays declared in a COMMON statement cannot be declared elsewhere in the program by any other declarative statements.
  9. The data type specified for com-items or the default data type and size determines the amount of storage reserved in a COMMON block. For example:

Example


COMMON (sales_rec) DECIMAL net_sales (1965 TO 1975),            & 
                   STRING row = 2,                              & 
                          report_name = 24,                     & 
                   DOUBLE FILL,                                 & 
                   LONG part_bins

Previous Next Contents Index