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

12.4 Using String Virtual Arrays

Virtual arrays are stored on disk. You create a virtual array by opening a disk file and then using the DIM # statement to dimension the array on the open channel. This section describes only string virtual arrays. See Chapter 14 for more information about virtual arrays.

Elements of string virtual arrays behave much like dynamic strings, with the following exceptions:

When you assign a value to a string virtual array element, BASIC pads the value with nulls, if necessary, to fit the length of the virtual array element; however, when you retrieve the virtual array element, BASIC strips all trailing nulls from the string. Therefore, when you access an element in a string virtual array, the string never has trailing nulls.

In the following example, the first two lines dimension a string virtual array and open a file on channel #1. The third line assigns a 10-character string to the first element of this string array, and to the variable A$. This 10-character string consists of "ABCDE" plus five null characters. The PRINT statements show that the length of A$ is 10, while the length of test(1) is only 5 because BASIC strips trailing nulls from string array elements. 


DIM #1%, STRING test(5) 
OPEN "TEST" AS FILE #1%, ORGANIZATION VIRTUAL 
A$, test(1%) = "ABCDE" + STRING$(5%, 0%) 
PRINT "LENGTH OF A$ IS: "; LEN(A$) 
PRINT "LENGTH OF TEST(1) IS: "; LEN(test(1%)) 
END

Output 


LENGTH OF A$ IS: 10 
LENGTH OF TEST(1) IS: 5

Although the storage for string virtual array elements is fixed, the length of a string array element can change because BASIC strips the trailing nulls whenever it retrieves a value from the array.

12.5 Assigning String Data

To assign string data, you use the LET, LSET, RSET, and MID$ statements. The following sections describe how to use these statements.

12.5.1 LET Statement

The LET statement assigns string data to a string variable. The keyword LET is optional. Again, LSET is more efficient than LET when changing a dynamic string variable. In the following example, B is a string variable and "ret_status" is a quoted string expression: 


LET B = "ret_status"

The LET statement changes the length of dynamic strings but does not change the length of fixed-length strings. The following example first creates a fixed-length string named ABC by declaring the string in a MAP statement. The program then creates a dynamic string named XYZ by declaring it in a DECLARE statement. The third line assigns a 3-character value to both variable ABC and XYZ, then prints the value and the length of the string variables. Variable ABC continues to have a length of 10: the three characters assigned, plus seven spaces for padding. The length of the dynamic variable changes with the values assigned to it. 


MAP (TEST) STRING ABC = 10 
DECLARE STRING XYZ 
ABC = "ABC" 
XYZ = "XYZ" 
PRINT ABC, LEN(ABC) 
PRINT XYZ, LEN(XYZ) 
ABC = "A" 
XYZ = "X" 
PRINT ABC, LEN(ABC) 
PRINT XYZ, LEN(XYZ)

Output 


ABC           10 
XYZ           3 
A             10 
X             1

12.5.2 LSET Statement

The LSET statement left-justifies data and assigns it to a string variable, without changing the variable's length. In the following example, ABC is a string variable and "ABC" is a string constant: 


LSET ABC = "ABC"

If the string expression's value is shorter than the string variable's current length, LSET left-justifies the expression and pads the string variable with spaces. In the following example, the LET statement creates the 5-character string variable test$. The LSET statement in the second line assigns the string XYZ to the variable test$ but does not change the length of test$. Because test$ has a length of 5, the LSET statement pads the string XYZ with two spaces when assigning the value. The PRINT statement shows that test$ includes these two spaces. 


LET test$ = "ABCDE" 
LSET test$ = "XYZ" 
PRINT "'"; test$; "'" 
END

Output 


'XYZ  '

LSET left-justifies a string expression longer than the string variable and truncates it on the right as shown in the following example: 


LET test$ = "ABCDE" 
LSET test$ = "12345678" 
PRINT test$ 
END

Output 


12345

The LET statement creates the 5-character string variable test$. The LSET statement in the second line assigns the characters "12345" to test$. Because LSET does not change the string variable's length, it truncates the last three characters (678).

12.5.3 RSET Statement

The RSET statement right-justifies data and assigns it to a string variable without changing the variable's length. In the following example, C_R is a string variable and "cust_rec" is a string constant: 


RSET C_R = "cust_rec"

RSET right-justifies a string expression shorter than the string variable and pads it with spaces on the left. In the following example, the LET statement creates the 5-character string variable test$. The RSET statement in the second line assigns the string XYZ to test$ but does not change the length of test$. Because test$ is five characters long, the RSET statement pads XYZ with two spaces when assigning the value. The PRINT statement shows that test$ includes these two spaces. 


LET test$ = "ABCDE" 
RSET test$ = "XYZ" 
PRINT "'" ;  test$; "'" 
END

Output 


'  XYZ'

If the string expression's value is longer than the string variable, RSET right-justifies the string expression and truncates characters on the left to fit the string variable as shown in the following example: 


LET test$ = "ABCDE" 
RSET test$ = "987654321" 
PRINT test$ 
END

Output 


54321

The LET statement creates a 5-character string variable, test$. The RSET statement assigns "54321" to test$. RSET, which does not change the variable's length, truncates "9876" from the left side of the string expression.

Note that, when using LSET and RSET, padding can become part of the data. 


LET A$ = '12345' 
LSET A$ = 'ABC' 
LET B$ = '12345678' 
RSET B$ = A$ 
PRINT "'";B$;"'"

Output 


'   ABC  '

12.5.4 MID$ Assignment Statement

You can replace a portion of a string with another string using the MID$ assignment statement. You specify a starting character position that indicates where to begin the substitution. If you specify a starting character position that is less than 1, BASIC assumes a starting character position of 1. In addition, you can optionally specify the number of characters to substitute from the source string expression. If you do not specify the number of characters to substitute, BASIC attempts to insert the entire source expression. However, the MID$ statement never changes the length of the target string variable; therefore, the entire source expression might not fit into the available space.

The following example shows the use of MID$ as an assignment statement. In this example, "ABCD" is the input string, the starting character position is 1, and the length of the segment to be replaced is 3 characters. Note that when you use MID$ as an assignment statement, the length of the input string does not change; therefore, the length of the result ("123D") is equal to the length of the input string. 


DECLARE STRING old_string, replace_string 
old_string = "ABCD" 
replace_string = "123" 
PRINT old_string 
MID$(old_string,1,3) = replace_string 
PRINT old_string

Output 


ABCD 
123D

Keep these considerations in mind when you use the MID$ assignment statement:

12.6 Manipulating String Data with String Functions

When used with the LET statement, BASIC string functions let you manipulate and modify strings. These functions let you:

These functions are discussed in the following sections. See the Compaq BASIC for OpenVMS Alpha and VAX Systems Reference Manual for more information about each string's function.

12.6.1 LEN Function

The LEN function returns the number of characters in a string as an integer value. For example: 


LEN(spec)

Spec is a string expression. The length of the string expression includes leading and trailing blanks. In the following example, the variable Z$ is set equal to "ABC XYZ", which has a length of eight: 


alpha$ = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
PRINT LEN(alpha$) 
Z$ = "ABC" + "  " + ""XYZ" 
PRINT LEN(Z$) 
END

Output 


 26 
 8

12.6.2 POS Function

The POS function searches a string for a group of characters (a substring). In the following example, spec is the string to be searched, test is the substring for which you are searching and 15 is the character position where BASIC starts the search: 


POS(spec,test,15)

The position returned by POS is relative to the beginning of the string, not the starting position of the search. For example, if you search the string "ABCDE" for the substring "E", it does not matter whether you specify a starting position of 1, 2, 3, 4, or 5, BASIC still returns the value 5 as the position where the substring was found.

If the function finds the substring, it returns the position of the substring's first character. Otherwise, it returns zero as in the following example: 


alpha$ = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
Z$ = "DEFG" 
X% = POS(ALPHA$,Z$,1%) 
PRINT X% 
Q$ = "TEST" 
Y% = POS(ALPHA$, Q$, 1%) 
PRINT Y% 
END

Output 


 4 
 0

If you specify a starting position other than 1, BASIC still returns the position of the substring relative to the beginning of the string as shown in the following example: 


alpha$ = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
Z$ = "HIJ" 
PRINT POS(ALPHA$, Z$, 7%) 
END

Output 


 8

If you know that the substring is not near the string's beginning, specifying a starting position greater than one speeds program execution by reducing the number of characters BASIC must search.

You can use the POS function to associate a character string with an integer that you can then use in calculations. This technique is called a table look-up. The following example prompts for a 3-character string, changes the string to uppercase letters, and searches the table string to find a match. The WHILE loop executes indefinitely until a carriage return is typed in response to the prompt. 


DECLARE STRING CONSTANT table =    & 
 "JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC"
DECLARE STRING month, UPPER_CASE_MONTH, message 
DECLARE INTEGER month_length 
DECLARE REAL month_pos 
PRINT "Please type the first three letters of a month"
PRINT "To end the program, type only Return"; 
Loop_1: 
   WHILE 1% = 1% 
      INPUT month 
      UPPER_CASE_MONTH = EDIT$(month, 32%) 
      month_length = LEN(UPPER_CASE_MONTH) 
      EXIT Loop_1 IF month_length = 0% 
      IF month_length = 3% 
        THEN month_pos = (POS(table, UPPER_CASE_MONTH, 1) + 2) / 3 
          IF (month_pos = 0%) OR (month_pos <> FIX(month_pos)) 
               THEN MESSAGE = " Invalid abbreviation, try again"
               ELSE MESSAGE = " is month number" + NUM$(MONTH_POS) 
          END IF 
        ELSE MESSAGE = " Abbreviation not three characters, try again"
      END IF 
      PRINT month; message 
   NEXT 
END

Output 


Please type the first three letters of a month 
To end the program, type only Return? Nov 
Nov is month number 11

Keep these considerations in mind when you use POS:

Note that searching for a null string is not the same as searching for the null character. A null string has a length of zero, while the null character has a length of one. The null character is an ASCII character whose value is zero.

12.6.3 SEG$ Function

The SEG$ function extracts a segment (substring) from a string. The original string remains unchanged. In the following example, time is the input string, 13 is the position of the first character extracted, and 16 is the position of the last character extracted: 


SEG$(time,13,16)

SEG$ extracts from the input string the substring that starts at the first character position, up to and including the last character position. It returns the extracted segment. 


PRINT SEG$("ABCDEFG", 3%, 5%) 
END

Output 


CDE

If you specify character positions that exist in the string, the length of the returned substring always equals (int-exp2 -- int-exp1 + 1).

Keep these considerations in mind when you use SEG$:

You can replace part of a string by using the SEG$ function with the string concatenation operator (+). In the following example, when BASIC creates C$, it concatenates the first two characters of A$, the 3-letter string XYZ, and the last two characters of A$. The original contents of A$ do not change. 


A$ = "ABCDEFG" 
C$ = SEG$(A$, 1%, 2%) + "XYZ" + SEG$(A$, 6%, 7%) 
PRINT C$ 
PRINT A$ 
END

Output 


ABXYZFG 
 
ABCDEFG

You can use similar string expressions to replace characters in any string. If you do not change the length of the target string, use the MID$ assignment statement to perform string replacement. A general formula to replace characters in positions n through m of string A$ with characters in B$ is as follows:

C$ = SEG$(A$,1%,n-1) + B$ + SEG$(A$,m+1,LEN(A$))

The following example replaces the sixth to ninth characters of the string "ABCDEFGHIJK" with "123456": 


A$ = "ABCDEFGHIJK" 
B$ = "123456" 
C$ = SEG$(A$,1%,5%) + B$ + SEG$(A$,10%,LEN(A$)) 
PRINT C$ 
PRINT A$ 
PRINT B$ 
END

Output 


ABCDE123456JK 
ABCDEFGHIJK 
123456

The following formulas are more specific applications of the general formula:

12.6.4 MID$ Function

The MID$ function extracts a specified substring, beginning at a specified character position and ending at a specified length. If you specify a starting character position that is less than 1, BASIC automatically assumes a starting character position of 1.

In the following example, the MID$ function uses the input string "ABCD", and extracts a segment consisting of 3 characters. Because BASIC automatically assumes a starting character position of 1 when the specified starting character position is less than 1, the string that is extracted begins with the first character of the input string. 


DECLARE STRING old_string, new_string 
old_string = "ABCD" 
new_string = MID$(old_string, 0, 3) 
PRINT new_string

Output 


ABC

Keep these considerations in mind when you use MID$:

Previous Next Contents Index