# 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 create the virtual string array, you specify a maximum length for the array's elements. The length of an array element can never exceed this maximum. If you do not supply a length, the default is 16 characters.
- A string virtual array element cannot contain trailing nulls.

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:

- The length argument is optional. If not specified, the number of characters replaced will be the minimum of the length of the replacement string and the length of the input string minus the starting position value.
- If the length of the segment is less than or equal to zero, BASIC assumes a length of zero.
- The length of the input string does not change regardless of the value of the length of the segment.

# 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:

- Determine the length of a string (LEN)
- Search for the position of a set of characters in a string (POS)
- Extract segments from a string (SEG$, MID$)
- Create a string of any length, made up of any single character (STRING$)
- Create a string of spaces (SPACE$)
- Remove trailing spaces and tabs from a string (TRM$)
- Edit a string (EDIT$)

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:

- If you specify a starting position less than 1, POS assumes a starting position of one.
- If you specify a starting position greater than the searched string's length, POS returns a zero (unless the substring is null).
- When searching for a null string:
  - If you specify a starting position greater than the string's length, POS returns the string's length plus one.
  - If the string to be searched is also null, POS returns a value of one.
  - If the specified starting position is less than or equal to 1, POS returns a value of one.
  - If the specified starting position is greater than one and less than or equal to the string's length plus 1, POS returns the specified starting position.

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$:

- If the starting character position is less than 1, BASIC assumes a value of 1.
- If the starting character position is greater than the ending character position, or the length of the string, SEG$ returns a null string.
- If the ending character position is greater than the length of the string, SEG$ returns all characters from the starting character position to the end of the string.
- If the starting character position is equal to the ending character position, SEG$ returns the character at the starting position.

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:

- To replace the first n characters of A$ with B$ use:

  `C$ = B$ + SEG$(A$,n+1,LEN(A$))`

- To replace all but the first n characters of A$ with B$ use:

  `C$ = SEG$(A$,1,n) + B$`

- To replace all but the last n characters of A$ with B$ use:

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

- To replace the last n characters of A$ with B$ use:

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

- To insert B$ in A$ after the nth character in A$ use:

  `C$ = SEG$(A$,1,n) + B$ + SEG$(A$,n+1,LEN(A$))`

## 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$:

- If the position of the segment's first character is greater than the input string, MID$ returns a null string.
- If the length of the segment is greater than the length of the input string, BASIC returns the string that begins at the specified starting character position and includes all characters remaining in the string.
- If the length of the segment is less than or equal to zero, MID$ returns a null string.
- If you specify a floating-point expression for the position of the segment's first character or for the length of the segment, BASIC truncates it to a long integer.

Previous | Next | Contents | Index