To change the value of a variable, use the DEPOSIT command as follows:

DBG> DEPOSIT variable_name = value

The DEPOSIT command is like an assignment statement in BASIC.

In the following examples, the DEPOSIT command assigns new values to different variables. The debugger checks that the value assigned, which may be a language expression, is consistent with the data type and dimensional constraints of the variable.

Deposit a string value (it must be enclosed in quotation marks or apostrophes):

DBG> DEPOSIT PARTNUMBER = "WG-7619.3-84"

Deposit an integer expression:

DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10

Deposit element 12 of an array of characters (you cannot deposit an entire array aggregate with a single DEPOSIT command, only an element):

DBG> DEPOSIT C_ARRAY(12) = 'K'

You can specify any kind of address expression, not just a variable name, with the DEPOSIT command (as with the EXAMINE command). You can override the defaults for typed and untyped locations if you want the data to be interpreted in some other data format.

4.5.3 Evaluating Expressions

To evaluate a language expression, use the EVALUATE command as follows:

DBG> EVALUATE lang_exp

The debugger recognizes the operators and expression syntax of the currently set language. In the following example, the value 45 is assigned to the integer variable WIDTH; the EVALUATE command then obtains the sum of the current value of WIDTH plus 7:

DBG> DEPOSIT WIDTH = 45 DBG> EVALUATE WIDTH + 7 52 DBG>

Following is an example of how the EVALUATE and the EXAMINE commands are similar. When the expression following the command is a variable name, the value reported by the debugger is the same for either command.

DBG> DEPOSIT WIDTH = 45 DBG> EVALUATE WIDTH 45 DBG> EXAMINE WIDTH SIZE\WIDTH: 45

Following is an example of how the EVALUATE and EXAMINE commands are different:

DBG> EVALUATE WIDTH + 7 52 DBG> EXAMINE WIDTH + 7 SIZE\WIDTH: 131584

With the EVALUATE command, WIDTH + 7 is interpreted as a language expression, which evaluates to 45 + 7, or 52. With the EXAMINE command, WIDTH + 7 is interpreted as an address expression: 7 bytes are added to the address of WIDTH, and whatever value is in the resulting address is reported (in this example, 131584).

4.6 Stepping Into BASIC Routines

This section provides details of the STEP/INTO command that are specific to BASIC.

In the following example, the debugger is waiting to proceed at source line 63. If you enter a STEP command at this point, the debugger will proceed to source line 64 without stopping during the execution of the function call. To step through the source code in the DEF function deffun, you must use the STEP/INTO command. A STEP/INTO command entered while the debugger has stopped at source line 63 causes the debugger to display the source code for deffun and stop execution at source code line 3.

1 DECLARE LONG FUNCTION deffun (LONG) 2 DECLARE LONG A 3 DEF LONG deffun (LONG x) 4 deffun = x 5 END DEF . . . ->63 A = deffun (6%) 64 Print "The value of A is: "; A

The STEP/INTO command is useful for stepping into external functions and DEF functions in Alpha BASIC and DEF functions in VAX BASIC. In Alpha BASIC and VAX BASIC, if you use this command to step into GOSUB blocks, the debugger steps into Run-Time Library (RTL) routines, providing you with no useful information. In VAX BASIC, if you use this command to step into external functions, the debugger steps into RTL routines, providing you with no useful information.

In the following program, the debugger has suspended execution at source line 8. If you now enter a STEP/INTO command, the debugger steps into the relevant RTL code and informs you that no source lines are available.

1 10 RANDOMIZE . . . ->8 GOSUB Print_routine 9 STOP . . . 20 Print_routine: 21 IF Competition = Done 22 THEN PRINT "The winning ticket is #";Winning_ticket 23 ELSE PRINT "The game goes on." 24 END IF 25 RETURN

As in the previous example, a STEP command alone will cause the debugger to proceed directly to source line 9. In VAX BASIC, to step through the source code of GOSUB blocks or external functions, use the SET BREAK command. The SET BREAK command is described in Section 4.4.3. In this case, a breakpoint set at the label Print_routine allows you step through the subroutine beginning at source line 20.

Table 4-1 summarizes the resultant behavior of the STEP/INTO command when used to step into external functions, DEF functions, and GOSUB blocks in Alpha BASIC and VAX BASIC.

Table 4-1 Resultant Behavior of the STEP/INTO Command

Action	Alpha BASIC Results	VAX BASIC Results
STEP/INTO DEF function	Steps into function	Steps into function
STEP/INTO DEF* function	Steps into RTL	Steps into function
STEP/INTO external function or SUB routine 1	Steps into function	Steps into RTL
STEP/INTO GOSUB block	Steps into RTL	Steps into RTL

When using the OpenVMS Debugger, all BASIC variable and label names within a single program unit must be unique; otherwise, the debugger will be unable to determine the symbol to which you are referring.

4.7 A Sample Debugging Session

This section shows a sample debugging session using a BASIC program that contains a logic error.

The following program compiles and links without diagnostic messages from either the compiler or the linker. However, after printing the headers, the program is caught in a loop printing the same figures indefinitely.

1 10 !SAMPLE program for DEBUG illustration 2 DECLARE INTEGER Number 3 Print_headers: 4 PRINT "NUMBER", "SQUARE", "SQUARE ROOT" 5 PRINT 6 Print_loop: 7 FOR Number = 10 TO 1 STEP -1 8 PRINT Number, Number^2, SQR(Number) 9 Number = Number + 1 10 NEXT Number 11 PRINT 12 END

The following text shows the terminal dialogue for a debugging session, which helps locate the error in the program SAMPLE. The callouts are keyed to explanatory notes that follow the dialogue.

$ BASIC/LIST/DEBUG SAMPLE (1) $ LINK/DEBUG SAMPLE (2) $ RUN SAMPLE VAX DEBUG Version n.n %DEBUG-I-INITIAL, language is BASIC module set to 'SAMPLE$MAIN' (3) DBG>STEP 2 (4) NUMBER SQUARE SQUARE ROOT stepped to SAMPLE$MAIN\%line 7 7: FOR Number = 10 TO 1 STEP -1 (5) DBG> STEP 4 (6) 10 100 3.16228 stepped to SAMPLE$MAIN\%LINE 7 7: FOR Number = 10 TO 1 STEP -1 DBG> EXAMINE Number (7) SAMPLE$MAIN\NUMBER: 10 (8) DBG> STEP 4 (9) 10 100 3.16228 stepped to SAMPLE$MAIN\%LINE 7 7: FOR Number = 10 TO 1 STEP -1 DBG> EXAMINE Number (10) SAMPLE$MAIN\NUMBER: 10 (11) DBG> DEPOSIT Number = 9 (12) DBG> STEP 4 (13) 9 81 3 stepped to SAMPLE$MAIN\%LINE 7 7: FOR Number = 10 TO 1 STEP -1 DBG> EXAMINE Number (14) SAMPLE$MAIN\NUMBER: 9 (15) DBG> STEP (16) 9 81 3 stepped to SAMPLE$MAIN\%LINE 8 8: PRINT Number, Number^2, SQR(Number) (17) DBG> STEP (18) stepped to SAMPLE$MAIN\%LINE 9 9: Number = Number + 1 (19) DBG> EXIT (20)

The following explains the terminal dialogue in the above example:

1. Compile SAMPLE.BAS with the /LIST and /DEBUG qualifiers. The listing file can be useful while you are in the debugging session.
2. Link SAMPLE.BAS with the /DEBUG qualifier.
3. The debugger identifies itself and displays the debugger prompt after you invoke the debugger with the RUN command.
4. Step through 2 executable statements to the FOR statement.
5. The headers print successfully and the program reaches the FOR statement.
6. Step through one iteration of the loop.
7. Request the contents of the variable Number.
8. The debugger shows the contents of the loop index to be 10.
9. Step through another iteration of the loop.
10. Examine the value of the loop index again.
11. The debugger shows that the loop index is still 10. The loop index has not changed from its initial setting in the FOR statement.
12. Deposit the correct value into Number.
13. Step through another iteration of the loop.
14. Examine the contents of Number again.
15. Observe that the number has not been changed yet.
16. Step through just one statement to discover what is interfering with the value of Number during execution of the loop.
17. Observe that this statement does not affect the value of Number.
18. Step through another statement in the loop.
19. Observe that this statement counteracts the change in the loop index.
20. Exit from the debugger. You can now edit the program to delete line 9 and reprocess the program. Alternatively, you could use the EDIT command while in the debugger environment.

This debugging session shows that the FOR...NEXT loop index (Number) is not being changed correctly. An examination of the statements in the loop shows that the variable Number is being decreased by one during each execution of the FOR statement, but incremented by one with each execution of the loop statements. From this you can determine that the loop index will not change at all and the program will loop indefinitely. To correct the problem, you must delete the incorrect statement and recompile the source program.

4.8 Hints for Using the OpenVMS Debugger with Alpha BASIC

When the debugger STEP command is used in source code containing an error, differences occur in the debugger behavior between OpenVMS VAX and OpenVMS Alpha. These differences are due to architectural differences in the hardware and software of the two systems.

In Alpha BASIC, a STEP at a statement that causes an exception might never return control to the debugger. The debugger cannot determine what statement in the BASIC source code will execute after the exception occurs. Therefore, set explicit breaks if STEP is used on statements that cause exceptions.

The following hints should help when you use the STEP command to debug programs that handle errors:

• When you STEP at a statement that takes an error, the debugger will not regain control unless the program reaches an explicit breakpoint or the next statement that would have executed if no error had occurred. Set explicit breaks if you want the program to stop in any other place.
• Use of the STEP command at a statement that takes an error does not return control to the debugger when the program reaches the error handler code. If you want the program to break when program execution enters an error handler, explicitly set a breakpoint at the error handler. This applies to both ON ERROR handlers and WHEN handlers.
• If you are within a WHEN handler, a STEP at a statement that terminates execution within the WHEN handler (CONTINUE, RETRY, END WHEN, END HANDLER, EXIT HANDLER) will not stop unless program flow reaches a point where an explicit breakpoint is set.
• STEP at a RESUME statement in an ON ERROR handler results in the program execution stopping at the first line of non-error-handler code.
• Use SET BREAK/EXCEPTION at the beginning of the debugging session to prevent unexpected errors from occurring. This breakpoint is not necessary if you have set explicit breakpoints at all error handlers. However, use of this command will break at all exceptions, allowing you to check that you have the proper breakpoints to stop program execution following the exception.

Part 2 explains Compaq BASIC programming concepts including input and output, arrays, data definition, program control, and functions.

A BASIC program is a series of instructions for the compiler. These instructions are built using the fundamental elements of BASIC. This chapter describes these elements or building blocks.

5.1 Line Numbers

BASIC gives you the option of developing programs with line numbers or without line numbers.

5.1.1 Programs with Line Numbers

If you use line numbers in your program, you must follow these rules:

• A line number must be a unique integer from 1 to 32767. In VAX BASIC, if a program contains duplicate line numbers, the last line with that number replaces the previous one. Alpha BASIC does not allow programs to have duplicate line numbers.
• A line number can contain leading zeros; however, embedded spaces, tabs, and commas are invalid in line numbers.
• There must be a line number on the first line of the program.
• If a source file contains subprograms, then each subprogram must begin on a numbered line.

In a multiple-unit program with line numbers, any comments following an END, END SUB, or END FUNCTION statement become a part of the previous subprogram during compilation unless they begin on a numbered line. This is not the case in multiple-unit programs without line numbers.

Although line numbers are not required, you might want to use them on every line that can cause a run-time error, depending on the type of error handling you use. See Chapter 16 for more information about handling run-time errors.

5.1.2 Programs Without Line Numbers

If you do not use line numbers in your program, follow these rules:

• Use a text editor to enter and edit the program; you cannot enter programs without line numbers directly in the environment.
• No line numbers are allowed anywhere in the program module.
• The ERL function is not allowed.
• REM statements are not allowed.
• In VAX BASIC, other files cannot be appended, because appended files must contain at least one line number.

In a multiple-unit program without line numbers, any comments following an END, END SUB, or END FUNCTION statement become a part of the next subprogram during compilation (unless there is no next subprogram). This is not the case in multiple-unit programs with line numbers.

You can avoid all of these restrictions by placing a line number on the first line of your program; no additional line numbers are required. The line number on the first program line causes the compiler to compile your program as a program with line numbers.

When you enter a program with or without line numbers, you can begin your program statements in the first character position on a line. While these statements would be considered immediate mode statements if entered in the VAX BASIC Environment, they are valid in a program that is created with a text editor.

For example, you can enter the following program directly into the environment:

10 !This is a short program that you can enter !and run in the VAX BASIC Environment ! PRINT "This program will convert pound weight to kilograms" INPUT "How many pounds";A !Here is the conversion step B = A * 2.2 PRINT "For ";A;" pounds, the kilogram weight is ";B END

Output

This program will convert pound weight to kilograms How many pounds? 10 For 10 pounds, the kilogram weight is 22

To develop the following program, you have to use a text editor, and you must observe the restrictions previously listed:

!This is a short program that does not contain any !BASIC line numbers. !This program must be entered using a text editor; !it cannot be entered directly into the environment. ! PRINT "This program converts kilogram weight to pounds" INPUT "How many kilograms";A !This is the conversion factor B = A / 2.2 PRINT "For ";A;" kilograms, the pound weight is ";B END

Output

This program converts kilogram weight to pounds How many kilograms? 11 For 11 kilograms, the pound weight is 5

You can use exclamation comment fields instead of REM statements to insert comments into programs without line numbers. An exclamation point in column 1 in the environment causes the BASIC compiler to ignore the rest of the line. You can also identify program statements in programs without line numbers by using labels.

5.1.3 Labels

A label is a 1- to 31-character identifier that you use to identify a block of statements. All label names must begin with a letter; the remaining characters, if any, can be any combination of letters, digits, dollar signs ($), underscores (_), or periods (.), but the final character cannot be a dollar sign.

Labels have the following advantages over line numbers:

• Meaningful label names provide documentation.
• You can use labels in programs with or without line numbers.

When you use a label to mark a program location, you must end the label with a colon (:). The colon is used to show that the label name is being defined instead of referenced. When you reference the label, do not include the colon.

In the following example, the label names end with colons when they mark a location, but the colons are not present when the labels are referenced:

OPTION TYPE = EXPLICIT ! Require declarations DECLARE INTEGER A . . . Outer_loop: IF A <> B THEN Inner_loop: IF B = C THEN A = A + 1 GOTO Outer_loop ELSE B = B + 1 GOTO Inner_loop END IF END IF

Labels have no effect on the order in which program lines are executed; they are used to identify a statement or block of statements.

5.1.4 Continuation of Long Program Statements

If a program line is too long for one line of text, you can continue the program line by typing an ampersand (&) and pressing Return at the end of the line. Note that only spaces and tabs are valid between the ampersand and the carriage return.

A single statement that spans several text lines requires an ampersand at the end of each continued line. For example:

OPEN "SAMPLE.DAT" AS FILE #2%, & SEQUENTIAL VARIABLE, & RECORDSIZE 80%

In an IF...THEN...ELSE construction, ampersands (&) are not necessary. If a continuation line begins with THEN or ELSE, then no ampersand is necessary. Similarly, in a line following a THEN or an ELSE, there is no ampersand.

IF (A$ = B$) THEN PRINT "The two values are equal" ELSE PRINT "The two values are different" END IF

Several statements can be associated with a single program line. If there are several statements on one line, they must be separated by backslashes (\). For example:

PRINT A \ PRINT V \ PRINT G

Because all statements are on the same program line, any reference to this program line refers to all three statements.

5.2 Identifying Program Units

You can delimit a main program compilation unit with the PROGRAM and END PROGRAM statements. This allows you to identify a program with a name other than the file name. The program name must not duplicate the name of a SUB, FUNCTION, or PICTURE subprogram. For example:

PROGRAM Sort_out . . . END PROGRAM

If you include the PROGRAM statement in your program, the name you specify becomes the module name of the compiled source. This feature is useful when you use object libraries because the librarian stores modules by their module name rather than the file name. Similarly, module names are used by the OpenVMS Debugger and the OpenVMS Linker.

For more information about PROGRAM units, see Chapter 13.