HP OpenVMS Systems

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

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:
   • The first character of an unquoted 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 (_).
   • A quoted name can consist of any combination of printable ASCII characters.
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!

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

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

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.

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.

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
   • This format converts each character in the string to its ASCII value.
   • BASIC assigns the value of the string's length to element zero (0) of the array.
   • BASIC assigns the ASCII value of the first character in the string to element one, (1) or (0,1), of the array, the ASCII value of the second character to element two, (2) or (0,2), and so on.
   • If the string is longer than the bounds of the array, BASIC does not translate the excess characters, and signals the error "Subscript out of range" (ERR=55). The first element of array still contains the length of the string.
3. Array to String Variable
   • This format converts the elements of the array to a string of characters.
   • The length of the string is determined by the value in element zero, (0) or (0,0), of the array. If the value of element zero is greater than the array bounds, BASIC signals the error "Subscript out of range" (ERR=55).
   • BASIC changes element one, (1) or (0,1), of array to its ASCII character equivalent, element two, (2) or (0,2), to its ASCII equivalent, and so on. The length of the returned string is determined by the value in element zero of the array. For example, if the array is dimensioned as (10), but the zero element (0) contains the value 5, BASIC changes only elements (1), (2), (3), (4), and (5) to string characters.
   • BASIC truncates floating-point values to integers before converting them to characters.
   • Values in array elements are treated as modulo 256.

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

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

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.

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.
   • Num-unsubs-var and num-array-name specify a numeric variable or a numeric array.
   • Record-var specifies a record instance.
   • Str-unsubs-var and str-array-name specify a fixed-length string variable or array. You can specify the number of bytes to be reserved for the variable with the =int-const clause. The default string length is 16.
   • When you specify either a numeric or a string array, BASIC allows you to declare both lower and upper bounds. The upper bound is required; the lower bound is optional.
     • Int-const1 specifies the lower bounds of the array.
     • Int-const2 specifies the upper bounds of the array and, when accompanied by int-const1, must be preceded by the keyword TO.
     • Int-const1 must be less than or equal to int-const2.
     • If you do not specify int-const1, BASIC uses zero as the default lower bound.
     • Int-const1 and int-const2 can be either negative or positive values.
   • The FILL, FILL%, and FILL$ keywords allow you to reserve parts of the record buffer within or between data elements and to define the format of the storage. Int-const specifies the number of FILL items to be reserved. The =int-const 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 applicable formats of FILL, (int-const) represents a repeat count, not an array subscript. FILL (n) represents n elements, not n + 1.

     Table 4-1 FILL Item Formats and Storage Allocations

     FILL Format	Storage Allocation
     FILL	Allocates storage for one element of the default data type unless preceded by a data-type. The number of bytes allocated depends on the default or the specified data type.
     FILL(int-const)	Allocates storage for the number of the default data type elements specified by int-const unless preceded by a data type. The number of bytes allocated for each element depends on the default floating-point data size or the specified data type.
     FILL%	Allocates storage for one integer element. The number of bytes allocated depends on the default integer size.
     FILL%(int-const)	Allocates storage for the number of integer elements specified by int-const. The number of bytes allocated for each element depends on the default integer size.
     FILL$	Allocates 16 bytes of storage for a string element.
     FILL$(int-const)	Allocates 16 bytes of storage for the number of string elements specified by int-const.
     FILL$=int-const	Allocates the number of bytes of storage specified by int-const for a string element.
     FILL$(int-const1)=int-const2	Allocates the number of bytes of storage specified by int-const2 for the number of string elements specified by int-const1.

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:
   • BYTE integers reserve 1 byte.
   • WORD integers reserve 2 bytes.
   • LONG integers reserve 4 bytes.
   • QUAD integers reserve 8 bytes.
   • SINGLE floating-point numbers reserve 4 bytes.
   • DOUBLE floating-point numbers reserve 8 bytes.
   • GFLOAT floating-point numbers reserve 8 bytes.
   • HFLOAT floating-point numbers reserve 16 bytes.
   • SFLOAT floating-point numbers reserve 4 bytes.
   • TFLOAT floating-point numbers reserve 8 bytes.
   • XFLOAT floating-point numbers reserve 16 bytes.
   • DECIMAL(d,s) packed decimal numbers reserve (d+1)/2 bytes.
   • STRING reserves 16 bytes (the default) or the number of bytes you specify with =int-const.

Example

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