HP OpenVMS Systems

The LSET statement assigns left-justified data to a string variable. LSET does not change the length of the destination string variable.

Format

Syntax Rules

1. Str-var is the destination string. Str-exp is the string value assigned to str-var.
2. Str-var cannot be a DEF function or function name unless the LSET statement is inside the multiline DEF or function that defines the function.

Remarks

1. The LSET statement treats all strings as fixed length. LSET neither changes the length of the destination string nor creates new storage. Rather, it overwrites the current storage of str-var.
2. If the destination string is longer than str-exp, LSET left-justifies str-exp and pads it with spaces on the right. If smaller, LSET truncates characters from the right of str-exp to match the length of str-var.

Example

DECLARE STRING alpha
alpha = "ABCDE"
LSET alpha = "FGHIJKLMN"
PRINT alpha

Output

FGHIJ

The MAG function returns the absolute value of a specified expression. The returned value has the same data type as the expression.

Format

Syntax Rules

None

Remarks

1. The returned value is always greater than or equal to zero. The absolute value of 0 is zero. The absolute value of a positive number equals that number. The absolute value of a negative number equals that number multiplied by -1.
2. The MAG function is similar to the ABS function in that it returns the absolute value of a number. The ABS function, however, takes a floating-point argument and returns a floating-point value. The MAG function takes an argument of any numeric data type and returns a value of the same data type as the argument. The use of the MAG function rather than the ABS and ABS% functions is recommended, because the MAG function returns a value using the data type of the argument.

Example

DECLARE SINGLE A
A = -34.6
PRINT MAG(A)

Output

 34.6

The MAGTAPE function permits your program to control unformatted magnetic tape files.

Format

Syntax Rules

1. Func-code specifies the code for the MAGTAPE function you want to perform. BASIC supports only function code 3, rewind tape. Table 4-3 explains how to perform other MAGTAPE functions with BASIC.
2. Int-var is an integer parameter for function codes 4, 5, and 6. However, because BASIC supports only function code 3, int-var is not used and always equals zero.
3. Chnl-exp is a numeric expression that specifies a channel number associated with the magnetic tape file.

Example

I = MAGTAPE (3%,0%,2%)

The MAP statement defines a named area of statically allocated storage called a PSECT, declares data fields in the record, and associates them with program variables.

Format

Syntax Rules

1. Map-name is global to the program and image. It cannot appear elsewhere in the program unit as a variable name.
2. Map-name can be from 1 to 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 (_).
3. Data-type can be any BASIC data type keyword or a data type defined by a RECORD statement. Data type keywords, size, range, and precision are listed in Table 1-2.
4. When you specify a data type, all following map-items, including FILL items, are of that data type until you specify a new data type.
5. If you specify a dollar sign ($) or percent sign (%) suffix character, the variable must be a string or integer data type.
6. If you do not specify a data type, a map-item without a suffix character (% or $) takes the current default data type and size.
7. Map-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.
   • 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.
   • In the applicable formats of FILL, (int-const) represents a repeat count, not an array subscript. FILL (n), for example, represents n elements, not n + 1.
8. Variable names, array names and FILL items following a data type other than STRING cannot end with a dollar sign. Variable names, array names and FILL items following a data type other than BYTE, WORD, LONG, QUAD, or INTEGER cannot end with a percent sign.
9. Variables and arrays declared in a MAP statement cannot be declared elsewhere in the program by any other declarative statements.
10. When you declare an array, BASIC allows you to specify both lower and upper bounds. Upper bounds are required; lower bounds are optional.
    • 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 any combination of negative and positive values.

Remarks

1. BASIC does not execute MAP statements. The MAP statement allocates static storage and defines data at compilation time.
2. A program can have multiple maps with the same name. The allocation for each map overlays the others. Thus, data is accessible in many ways. The actual size of the data area is the size of the largest map. When you link your program, the size of the map area is the size of the largest map with that name.
3. Map-items with the same name can appear in different MAP statements with the same map name only if they match exactly in attributes such as data type, position, and so forth. If the attributes are not the same, BASIC signals an error. For example:

   MAP (ABC) LONG A, B MAP (ABC) LONG A, C ! This MAP statement is valid MAP (ABC) LONG B, A ! This MAP statement produces an error MAP (ABC) WORD A, B ! This MAP statement produces an error

   
   The third MAP statement causes BASIC to signal the error "variable <name> not aligned in multiple references in MAP <name>," while the fourth MAP statement generates the error "attributes of overlaid variable <name> don't match."
4. The MAP statement should precede any reference to variables declared in it.
5. Storage space for map-items is allocated in order of occurrence in the MAP statement.
6. A MAP area can be accessed by more than one program module, as long as you define the map-name in each module that references the MAP.
7. A COMMON area and a MAP area with the same name specify the same storage area and are not allowed in the same program module. However, a COMMON in one module can reference the storage declared by a MAP or COMMON in another module.
8. Variables in a MAP statement are not initialized by BASIC.
9. A map named in an OPEN statement's MAP clause is associated with that file. The file's records and record fields are defined by that map. The size of the map determines the record size for file I/O, unless the OPEN statement includes a RECORDSIZE clause.

Example

MAP (BUF1) BYTE AGE, STRING emp_name = 20            &
    SINGLE emp_num

MAP (BUF1) BYTE FILL, STRING last_name (11) = 12,    &
    FILL = 8, SINGLE FILL

The MAP DYNAMIC statement names the variables and arrays whose size and position in a storage area can change at run time. The MAP DYNAMIC statement is used in conjunction with the REMAP statement. The REMAP statement defines or redefines the position in the storage area of variables named in the MAP DYNAMIC statement.

Format

Syntax Rules

1. Map-dyn-name can either be 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.
   • Static-str-var must specify a static string variable or a string parameter variable.

   • 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.
     • Static-str-var cannot be a subscripted variable.
     • Static-str-var cannot be a record component.
     • Static-str-var cannot be a parameter declared in a DEF or DEF* function.
2. Map-item declares the name and data type of the items to be stored in the storage area. All variable pointers point to the beginning of the storage area until the program executes a REMAP statement.
   • 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 string variable or array. You cannot specify the number of bytes to be reserved for the variable in the MAP DYNAMIC statement. All string items have a fixed length of zero until the program executes a REMAP statement.
3. When you specify an array name, BASIC allows you to specify 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.
4. Data-type can be any BASIC data type keyword or a data type defined with a RECORD statement. Data type keywords, size, range, and precision are listed in Table 1-2 in this manual.
5. When you specify a data type, all following map-items are of that data type until you specify a new data type.
6. If you do not specify any data type, map-items take the current default data type and size.
7. Map-items must be separated with commas.
8. If you specify a dollar sign suffix, the variable must be a STRING data type.
9. If you specify a percent sign suffix, the variable must be a BYTE, WORD, LONG, or QUAD integer data type.

Remarks

1. All variables and arrays declared in a MAP DYNAMIC statement cannot be declared elsewhere in the program by any other declarative statements.
2. The MAP DYNAMIC statement does not affect the amount of storage allocated to the map buffer declared in a previous MAP statement or the storage allocated to a static string. Until your program executes a REMAP statement, all variable and array element pointers point to the beginning of the MAP buffer or static string.
3. BASIC does not execute MAP DYNAMIC statements. The MAP DYNAMIC statement names the variables whose size and position in the MAP or static string buffer can change and defines their data type.
4. Before you can specify a map name in a MAP DYNAMIC statement, there must be a MAP statement in the program unit with the same map name. Otherwise, BASIC signals the error "Insufficient space for MAP DYNAMIC variables in MAP <name>." Similarly, before you can specify a static string variable in the MAP DYNAMIC statement, the string variable must be declared. Otherwise, BASIC signals the same error message.
5. A static string variable must be either a variable declared in a MAP or COMMON statement or a parameter declared in a SUB, FUNCTION, or PICTURE. It cannot be a parameter declared in a DEF or DEF* function.
6. If a static string variable is the same as a map name, BASIC uses the map name if the name appears in a MAP DYNAMIC statement.
7. The MAP DYNAMIC statement must lexically precede the REMAP statement or BASIC signals the error "MAP variable <name> referenced before declaration."

Example

100     MAP (MY.BUF) STRING DUMMY = 512
        MAP DYNAMIC (MY.BUF) STRING LAST, FIRST, MIDDLE,      &
                             BYTE AGE, STRING EMPLOYER,       &
                             STRING CHARACTERISTICS

The MAR function returns the current margin width of a specified channel.

Format

Syntax Rules

The file associated with chnl-exp must be open.

Remarks

1. If chnl-exp specifies a terminal and you have not set a margin width with the MARGIN statement, the MAR function returns a value of zero. If you have set a margin width, the MAR function returns that number.
2. The value returned by the MAR function is a LONG integer.

Example

DECLARE INTEGER width
MARGIN #0, 80
width = MAR(0)
PRINT width

Output

 80

The MARGIN statement specifies the margin width for a terminal or for records in 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 (#).
2. Int-exp specifies the margin width.

Remarks

1. If you do not specify a channel, BASIC sets the margin on the controlling terminal.
2. The file associated with chnl-exp must be an open terminal-format file or terminal.
3. BASIC signals the error "Illegal operation" (ERR=141) if the file associated with chnl-exp is not a terminal-format file.
4. If chnl-exp does not correspond to a terminal, and if int-exp is zero, BASIC sets the right margin to the size specified by the RECORDSIZE clause in the OPEN statement, if the clause is present. If no RECORDSIZE clause is present, BASIC sets the margin to 72 (or, in the case of channel 0, to the width of SYS$OUTPUT).
5. If chnl-exp is not present or if it corresponds to a terminal, and if int-exp is zero, BASIC sets the right margin to the size specified by the RECORDSIZE clause in the OPEN statement, if the clause is present. If no RECORDSIZE clause is present, BASIC sets the margin to 72.
6. BASIC prints as much of a specified record as the margin setting allows on one line before going to a new line. Numeric fields are never split across lines.
7. If you specify a margin larger than the channel's record size, BASIC signals an error. The default record size for a terminal or terminal format file is 132.
8. The MARGIN statement applies to the specified channel only while the channel is open. If you close the channel and then reopen it, BASIC uses the default margin.

Example

OPEN "EMP.DAT" FOR OUTPUT AS #1
MARGIN #1, 132
   .
   .
   .

The MAT statement lets you implicitly create and manipulate one- and two-dimensional arrays. You can use the MAT statement to assign values to array elements, or to redimension a previously dimensioned array. You can also perform matrix arithmetic operations such as multiplication, addition, and subtraction, and other matrix operations such as transposing and inverting matrices.

Format

Syntax Rules

1. Int-exp1 and int-exp2 define the upper bounds of the array being implicitly created or the new dimensions of an existing array.
2. If you are creating an array, int-exp1 and int-exp2 cannot exceed 10.
3. If you do not specify bounds, BASIC creates the array and dimensions it to (0 TO 10) or (0 TO 10, 0 TO 10).
4. If you specify bounds, BASIC creates the array with the specified bounds. If the bounds exceed (0 TO 10) or (0 TO 10, 0 TO 10), BASIC signals "Redimensioned array" (ERR=105).
5. The lower bounds must be zero.

Remarks

1. To perform MAT operations on arrays larger than (10,10), create the input and output arrays with the DIM statement.
2. When the array exists, the following rules apply:
   • If you specify upper bounds, BASIC redimensions the array to the specified size. However, MAT operations cannot increase the total number of array elements.
   • All arrays specified with the MAT statement must have lower bounds of zero. If you supply a nonzero value, BASIC signals either a compile-time or a run-time error.
   • If you do not specify bounds, BASIC does not redimension the array.
   • An array passed to a subprogram and redimensioned with a MAT statement remains redimensioned when control returns to the calling program, with two exceptions:
     • When the array is within a record and is passed by descriptor
     • When the array is passed by reference
3. You cannot use the MAT statement on arrays of more than two dimensions.
4. You cannot use the MAT statement on arrays of data type DECIMAL or on arrays named in a RECORD statement.
5. Unless the arrays are declared with a DIM or DECLARE statement, the data type will be the default floating-point data type.
6. Initialization
   • CON sets all elements of num-array to 1, except those in row and column zero.
   • IDN creates an identity matrix from num-array. The number of rows and columns in num-array must be identical. IDN sets all elements to zero except those in row and column zero, and those on the diagonal from num-array(1,1) to num-array(n,n), which are set to 1.
   • ZER sets all array elements to zero, except those in row and column zero.
   • NUL$ sets all elements of a string array to the null string, except those in row and column zero.
7. Array Arithmetic
   • The equal sign (=) assigns the results of the specified operation to the elements in num-array1.
   • If num-array3 is not specified, BASIC assigns the values of num-array2's elements to the corresponding elements of num-array1. Num-array1 must have at least as many rows and columns as num-array2. Num-array1 is redimensioned to match num-array2.
   • Use the plus sign (+) to add the elements of two arrays. Num-array2 and num-array3 must have identical bounds.
   • Use the minus sign (-) to subtract the elements of two arrays. Num-array2 and num-array3 must have identical bounds.
   • Use the asterisk (*) to perform matrix multiplication on the elements of num-array2 and num-array3 and to assign the results to num-array1. This operation gives the dot product of num-array2 and num-array3. All three arrays must be two-dimensional, and the number of columns in num-array2 must equal the number of rows in num-array3. BASIC redimensions num-array1 to have the same number of rows as num-array2 and the same number of columns as num-array3. Neither num-array2 nor num-array3 may be the same as num-array1.
   • With matrix multiplication, you can specify more than two numeric arrays; however, each array must be two-dimensional. Moreover, in each dimension, the lower bound of each array must be zero and the upper bound must be 4. You can use the graphics transformation functions, which will automatically create arrays with these dimensions. See the DRAW statement in Programming with VAX BASIC Graphics for more information.
8. Scalar Multiplication
   • BASIC multiplies each element of num-array5 by num-exp and stores the results in the corresponding elements of num-array4.
9. Inversion and Transposition
   • TRN transposes num-array7 and assigns the results to num-array6. If num-array7 has m rows and n columns, num-array6 will have n rows and m columns. Both arrays must be two-dimensional.
   • You cannot transpose a matrix to itself: MAT A = TRN(A) is invalid.
   • INV inverts num-array7 and assigns the results to num-array6. Num-array7 must be a two-dimensional array that can be reduced to the identity matrix with elementary row operations. The row and column dimensions must be identical.
10. You cannot increase the number of array elements or change the number of dimensions in an array when you redimension with the MAT statement. For example, you can redimension an array with dimensions (5,4) to (4,5) or (3,2), but you cannot redimension that array to (5,5) or to (10). The total number of array elements includes those in row and column zero.
11. If an array is named in both a DIM statement and a MAT statement, the DIM statement must lexically precede the MAT statement.
12. MAT statements do not operate on elements in the zero element (one-dimensional arrays) or in the zero row or column (two-dimensional arrays). MAT statements use these elements to store results of intermediate calculations. Therefore, you should not depend on values in row and column zero if your program uses MAT statements.

Examples