HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

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

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

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, HP 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 HP 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, HP 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, HP BASIC truncates it to a long integer.

The STRING$ function creates a character string containing multiple occurrences of a single character. In the following example, 23 is the length of the returned string, and 30 is the ASCII value of the character that makes up the string. This value is treated modulo 256.

STRING$(23,30)

The following example creates a 10-character string containing uppercase As, which have ASCII value 65:

out$ = STRING$(10%, 65%)
PRINT out$
END

Output

AAAAAAAAAA

Keep these considerations in mind when you use STRING$:

• If the length of the returned string is less than or equal to zero, STRING$ returns a null string.
• If the length of the returned string is greater than 65535, HP BASIC signals an error.

The SPACE$ function creates a character string containing spaces. In this example, 5 is the number of spaces in the string:

SPACE$(5)

The following example creates a 9-character string which contains 3 spaces:

A$ = "ABC"
B$ = "XYZ"
PRINT A$ + SPACE$(3%) + B$
END

Output

ABC   XYZ

The TRM$ function removes trailing blanks and tabs from a string. The input string remains unchanged. In the following example, all trailing blanks that appear in the string expression "ABCDE " are removed once the TRM$ function is invoked:

A$ = "ABCDE   "
B$ = "XYZ"
first$ = A$ + B$
second$ = TRM$(A$) + B$
PRINT first$
PRINT second$
END

Output

ABCDE   XYZ
ABCDEXYZ

The TRM$ function is especially useful for extracting the nonblank characters from a fixed-length string (for example, a COMMON or MAP, or a parameter passed from a program written in another language).

11.6.8 EDIT$ Function

The EDIT$ function performs one or more string editing functions, depending on the value of an argument you supply. The input string remains unchanged. In the following example, stu_rec is a string expression and 32 determines the editing function performed:

EDIT$(stu_rec,32)

Table 11-2 shows the action HP BASIC takes for a given value of the integer expression.

All values are additive; for example, by specifying 168, you can perform the following:

• Discard leading spaces and tabs (value 8)
• Convert lowercase letters to uppercase (value 32)
• Discard trailing spaces and tabs (value 128)

The following example requests an input string, discards all spaces and tabs, converts lowercase letters to uppercase, and converts brackets to parentheses:

LINPUT "PLEASE TYPE A STRING";input_string$
new_string$ = EDIT$(input_string$, 2% + 32% + 64%)
PRINT new_string$
END

Output

PLEASE TYPE A STRING? 88  abc[TAB][5,5]
88ABC(5,5)

Mapping a string storage area in more than one way lets you extract a substring from a string or concatenate strings. In the following example, the three MAP statements reference the same 108 bytes of data:

MAP (emprec) first_name$ = 10,                 &
             last_name$ = 20,                  &
             street_number$ = 6,               &
             street$ = 15,                     &
             city$ = 20,                       &
             state$ = 2,                       &
             zip$ = 5,                         &
             wage_class$ = 2,                  &
             date_of_review$ = 8,              &
             salary_ytd$ = 10,                 &
             tax_ytd$ = 10
MAP (emprec) full_name$ = 30,                  &
             address$ = 48,                    &
             salary_info$ = 30
MAP (emprec) employee_record$ = 108

You can move data into a map in different ways. For instance, you can use terminal input, arrays, and files. In the following example, the READ and DATA statements are used to move data into a map:

READ EMPLOYEE_RECORD$
DATA "WILLIAM   DAVIDSON            2241  MADISON BLVD   " &
"SCRANTON            PA14225A912/10/78$13,325.77$925.31"

Because all the MAP statements in the previous example reference the same storage area (emprec), you can access parts of this area through the mapped variables as shown in the following examples:

Example 1

PRINT full_name$
PRINT wage_class$
PRINT salary_ytd$

Output 1

WILLIAM   DAVIDSON
A9
$13,325.77

Example 2

PRINT last_name$
PRINT tax_ytd$

Output 2

DAVIDSON
$925.31

You can assign a new value to any of the mapped variables. The following example prompts the user for changed information by displaying a menu of topics. The user can then choose which topics need to be changed and then separately assign new values to each variable.

Loop_1:
WHILE 1% = 1%
      INPUT "Changes? (please type YES or NO)"; CH$
      EXIT Loop_1 IF CH$ = "NO"
      PRINT "1. FIRST NAME"
      PRINT "2. LAST NAME"
      PRINT "3. STREET NUMBER"
      PRINT "4. STREET"
      PRINT "5. CITY"
      PRINT "6. STATE"
      PRINT "7. ZIP"
      PRINT "8. WAGE CLASS"
      PRINT "9. DATE OF REVIEW"
      PRINT "10. SALARY YTD"
      PRINT "11. TAX YTD"
      INPUT "CHANGE NUMBER"; NUMBER%
      SELECT NUMBER%
      CASE 1%
           INPUT "FIRST NAME"; first_name$
      CASE 2%
           INPUT "LAST NAME"; last_name$
      CASE 3%
           INPUT "STREET NUMBER"; street_number$
      CASE 4%
           INPUT "STREET"; street$
      CASE 5%
           INPUT "CITY"; city$
      CASE 6%
          INPUT "STATE"; state$
      CASE 7%
           INPUT "ZIP CODE"; zip$
      CASE 8%
           INPUT "WAGE CLASS"; wage_class$
      CASE 9%
           INPUT "DATE OF REVIEW"; date_of_review$
      CASE 10%
           INPUT "SALARY YTD"; salary_ytd$
      CASE 11%
           INPUT "TAX YTD"; tax_ytd$
      CASE ELSE
           PRINT "Invalid choice"
      END SELECT
NEXT
END

Output

Changes? (please type YES or NO)? YES
1.  FIRST NAME
2.  LAST NAME
3.  STREET NUMBER
4.  STREET
5.  CITY
6.  STATE
7.  ZIP
8.  WAGE CLASS
9.  DATE OF REVIEW
10.  SALARY YTD
11.  TAX YTD

CHANGE NUMBER? 10
SALARY YTD? 14,277.08
Changes? (please type YES or NO)? YES
CHANGE NUMBER? 11
TAX YTD? 998.32
Changes? (please type YES or NO)? NO

See Chapter 7 and the HP BASIC for OpenVMS Reference Manual for more information about the MAP statement.

This chapter describes how to:

• Declare HP BASIC subprograms
• Write HP BASIC subprograms

Program segmentation is the process of dividing a program into small, manageable routines and modules. In a segmented or modular program, each routine or module usually performs only one logical function. You can, therefore, design and implement a modular program faster than a nonsegmented program. Program modularity also simplifies debugging and testing, as well as program maintenance and transportability.

Subprograms processed by the HP BASIC compiler conform to the OpenVMS Procedure Calling Standard. This standard prescribes how arguments are passed, how values are returned, and how procedures receive and return control. Because HP BASIC conforms to the OpenVMS Procedure Calling Standard, an HP BASIC subprogram or main program can call or be called by any procedure written in a language that also conforms to this standard. For information about calling non-BASIC procedures, see Chapter 19.

12.1 HP BASIC Subprograms

HP BASIC has SUB and FUNCTION subprograms. Each of these subprograms receives parameters and can modify parameters passed by reference or by descriptor. The differences between SUB and FUNCTION subprograms are as follows:

• FUNCTION subprograms must be declared with an EXTERNAL statement in the calling program. Declaring SUB subprograms is optional.
• FUNCTION subprograms return a value; SUB subprograms do not return a value.

All subprograms invoked by an HP BASIC program must have unique names. A HP BASIC program cannot have different subprograms with the same identifiers.

Subprograms can return a value to the calling program with parameters. You can use subprograms to separate routines that you commonly use. For example, you can use subprograms to perform file I/O operations, to sort data, or for table lookups.

You can also use subprograms to separate large programs into smaller, more manageable routines, or you can separate modules that are modified often. If all references to system-specific features are isolated, it is easier to transport the program to a different system. OpenVMS System Services and OpenVMS Run-Time Library routines are specific to OpenVMS systems; therefore, you should consider isolating references to them in subprograms. Chapter 19 describes how to access Run-Time Library routines and system services from HP BASIC.

You should also consider isolating complex processing algorithms that are used commonly. If complex processing routines are isolated, they can be shared by many programs while the complexity remains hidden from the main program logic. However, they can share data only if the following is true:

• Data is passed as a parameter from the CALL statement or function invocation to the subprogram---see Section 12.2 for more information.
• Data is part of a MAP or COMMON block---see Chapter 6 for information about using MAP and COMMON statements.
• Data is in a file---see Chapter 13 for more information about accessing data from a file.

All DATA statements are local to a subprogram. Each time you call a subprogram, HP BASIC positions the data pointer at the beginning of the subprogram's data.

The data pointer in the main program is not affected by READ or RESTORE statements in the subprogram (in contrast with the RESTORE # statement, which resets record pointers to the first record in the file no matter where it is executed). Chapter 5 contains more information about the READ and RESTORE statements. For more information about the RESTORE # statement, see Chapter 13.

12.1.1 SUB Subprograms

A SUB subprogram is a program module that can be separately compiled and that cannot return a value. A SUB subprogram is delimited by the SUB and END SUB statements. You may use the EXTERNAL statement to explicitly declare the SUB subprogram.

The END SUB statement does the following:

• Marks the end of the SUB subprogram
• Does not affect I/O operations or files
• Releases the storage allocated to local variables
• Returns control to the calling program

The EXIT SUB statement transfers control to the statement lexically following the statement that invoked the subprogram. It is equivalent to an unconditional branch to an END SUB statement.

The following SUB subprogram sorts two integers. If this SUB statement is invoked with actual parameter values that are already in sorted order, the EXIT SUB statement is executed and control returns to the calling program.

SUB sort_out (INTEGER X, INTEGER Y)
DECLARE INTEGER temp
  IF X > Y
   THEN
      temp = X
      X = Y
      Y = temp
   ELSE
      EXIT SUB
   END IF
END SUB

A FUNCTION subprogram is a program module that returns a value and can be separately compiled. It must be delimited by the FUNCTION and END FUNCTION statements. You use the EXTERNAL statement to name and explicitly declare the data type of an external function.

The END FUNCTION statement does the following:

• Marks the end of a function subprogram
• Does not affect I/O operations or files
• Releases the storage allocated to local variables
• Optionally specifies a return value for the function
• Returns control to the calling program

The EXIT FUNCTION statement immediately returns program control to the statement that invoked the function and optionally returns the function's return value. It is equivalent to an unconditional transfer to the END FUNCTION statement.

You can specify an expression with both the END FUNCTION and EXIT FUNCTION statements, which is another way of returning a function value. This expression must match the function data type, and it supersedes any function assignment. For more information, see the HP BASIC for OpenVMS Reference Manual.

The following function returns the volume of a sphere of radius R. If this function is invoked with an actual parameter value less than or equal to zero, the function returns zero.

FUNCTION REAL Sphere_volume (REAL R)
     IF R <= 0
       THEN
           Sphere_volume = 0.0
       ELSE
           Sphere_volume = 4/3 * PI * R ** 3
      END IF
END FUNCTION

The following example declares the FUNCTION subprogram and invokes it:

PROGRAM call_sphere
  EXTERNAL REAL FUNCTION SPHERE_VOLUME(REAL)
  PRINT  SPHERE_VOLUME(5.925)
END PROGRAM

Note that this module is compiled separately from the FUNCTION subprogram. You can link these modules together to run the program from DCL level.