HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

This chapter defines dynamic and fixed-length strings and string virtual arrays, explains which you should choose for your application, and shows you how to use them.

11.1 Overview of Strings

A string is a sequence of ASCII characters. BASIC allows you to use the following types of strings:

• Dynamic strings
• Fixed-length strings
• String virtual arrays

Dynamic strings are strings whose length can change during program execution. The length of a dynamic string variable can change or not, depending on the statement used to modify it.

Fixed-length strings are strings whose length never changes. In other words, their length remains static. String constants are always fixed-length. String variables can be either fixed-length or dynamic. A string variable is fixed-length if it is named in a COMMON, MAP, or RECORD statement. If a string variable is not part of a map or common block, RECORD, or virtual array, it is a dynamic string. When a string variable is fixed-length, its length does not change, regardless of the statement you use to modify it. Table 11-1 provides more information about string modification.

Strings in virtual arrays have both fixed-length and dynamic attributes. String virtual arrays have a specified maximum length from 0 to 512 characters. During program execution, the length of an element in a string virtual array can change; however, the length is always from 0 to the maximum string size specified when the array was created. See Section 11.4 and Chapter 13 for more information about virtual arrays.

Although dynamic strings are less efficient than fixed-length strings, they are often more flexible. For example, to concatenate strings, you can use the LET statement to assign the concatenated value to a dynamic string variable, without having to be concerned about HP BASIC truncating the string or adding trailing spaces to it. However, if the destination variable is fixed-length, you must make sure that it is long enough to receive the concatenated string, or HP BASIC truncates the new value to fit the destination string. Similarly, if you use LSET or RSET to concatenate strings, you must ensure that the destination variable is long enough to receive the data.

The LET, LSET, and RSET statements all operate on dynamic strings as well as fixed-length strings. The LET statement can change the length of a dynamic string; LSET and RSET do not. LSET and RSET are more efficient than LET when changing the value of a dynamic string. For more information about LSET and RSET, see Section 11.5.2 and Section 11.5.3.

In the following example, the first line assigns the value "ABC" to A$, the second line assigns "XYZ" to B$, and the third line assigns six spaces to C$. These variables are dynamic strings. In the fourth line, LSET assigns A$ the value of A$ concatenated with B$. Because the LSET statement does not change the length of the destination string variable, only the first three characters of the expression A$ + B$ are assigned to A$. The fifth line uses LSET to assign C$ the value of A$ concatenated with B$. Because C$ already has a length of 6, this statement assigns the value "ABCXYZ" to it.

LET A$ = "ABC"
LET B$ = "XYZ"
LET C$ = "      "
LSET A$ = A$ + B$
LSET C$ = A$ + B$
PRINT A$
PRINT C$
END

Output

ABC
ABCXYZ

Like the LET statement, the INPUT, INPUT LINE, and LINPUT statements can change the length of a dynamic string, but they cannot change the length of a fixed-length string.

In this example, the first line assigns the null string to variable A$. The second line uses the LEN function to show that the null string has a length of zero. The third line uses the INPUT statement to assign a new value to A$, and the fourth and fifth lines print the new value and its length.

!Declare a dynamic string
LET A$ = ""
PRINT LEN(A$)
INPUT A$
PRINT A$
PRINT LEN(A$)
END

Output

 0
? THIS IS A TEST
THIS IS A TEST
 14

You should not confuse the null string with a null character. A null character is one whose ASCII numeric code is zero. The null string is a string whose length is zero.

11.3 Using Fixed-Length Strings

It is generally more efficient to manipulate a fixed-length string than a dynamic string. Creating or modifying a dynamic string often causes HP BASIC to create new storage, and this increases processor overhead.

If a string variable is part of a map or common block, or virtual array, a LET, INPUT, LINPUT, or INPUT LINE statement changes its value, but not its length. In the following example, the MAP statement in the first line explicitly assigns a length to each string variable. Because the LINPUT statements cannot change this length, HP BASIC truncates values to fit the address and city_state variables. Because the zip variable is longer than the assigned value, HP BASIC left-justifies the assigned value and pads it with spaces. The sixth line uses the compile-time constant HT (horizontal tab) to separate fields in the employee record.

MAP (FIELDS) STRING full_name = 10,                            &
            address = 10,                                      &
            city_state = 10,                                   &
            zip = 10
LINPUT "NAME"; full_name
LINPUT "ADDRESS"; address
LINPUT "CITY AND STATE"; city_state
LINPUT "ZIP CODE"; zip
EMPLOYEE_RECORD$ = full_name + HT + address + HT &
                   + city_state + HT + zip
PRINT EMPLOYEE_RECORD$
END

Output

NAME? JOE SMITH
ADDRESS? 66 GRANT AVENUE
CITY AND STATE? NEW YORK NY
ZIP? 01001

JOE SMITH           66 GRANT A   NEW YORK N 01001

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 13 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, HP 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, HP 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 HP 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 HP BASIC strips the trailing nulls whenever it retrieves a value from the array.

11.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.

11.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

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).

11.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  '

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, HP 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, HP 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, HP 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.

When used with the LET statement, HP 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 HP BASIC for OpenVMS Reference Manual for more information about each string's function.

11.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

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 HP 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, HP 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, HP 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 HP 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.