HP 3000 Manuals HP 3000 Manuals
Subunits
A program can be divided into program units consisting of one main
program unit followed by one or more subunits. In this section, the main
program unit is called the main program.
A subunit is a series of program lines that can be called with
parameters, by another program unit. The calling program unit transfers
control to the subunit; the subunit executes and returns control to the
calling program unit. The calling program unit can be the main program
or another subunit.
A subunit can contain any program lines that are valid in a main program,
including variable declaration statements. Except for common variables,
the variables that are defined in a subunit, including formal parameters,
are local to that subunit. All variable names in the subunit represent
variables that are distinct from variables with the same names in other
program units. HP Business BASIC/XL allocates space for local variables
when it enters a subunit, and releases that space to memory when it
returns to the calling program.
When HP Business BASIC/XL enters a subunit, it suspends the ON ERROR, ON
END, and ON HALT specifications form the last program unit until control
returns to that program unit. Exceptions to this rule are those "ON"
conditions that specify subunit calls, for example, ON ERROR CALL
Error_Routine.
A subunit is either a subprogram or a user-defined multi-line function.
A subprogram performs a task, but does not return a value to the calling
program unit. A multi-line function returns a value to the calling
program unit unless it is called as a subprogram, in which case the
result is discarded.
Table 3-28 summarizes the differences between subprograms and multi-line
functions.
Table 3-28. Subprograms vs Multi-line Functions
-----------------------------------------------------------------------------------------------
| | | |
| Subunit Type | Subprogram | Multi-line Function |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Begins with | SUBPROGRAM or SUB statement. | DEF FN statement. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Ends with | SUBEND statement. | FNEND statement. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Returns to | Line following subprogram call. | Line containing function |
| | | call. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Returns via | SUBEXIT or SUBEND statement. | RETURN statement. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Returns with | No. | Yes. |
| value | | |
| | | |
-----------------------------------------------------------------------------------------------
Subprograms
A subprogram is a subunit that performs a task and returns control to the
program unit that called it. It does not return a value to the calling
program unit.
Syntax
SUB_stmt [stmt]...SUBEND_stmt
Parameters
SUB_stmt SUBPROGRAM or SUB statement. Not executable. Indicates
that the lines that follow are a subprogram.
stmt Can be a SUBEXIT statement that returns control to the
calling program unit before the SUBEND statement is
executed, or can be any executable statement. These
statements constitute the body of the subprogram.
SUBEND_stmt SUBEND statement. Indicates the end of the subprogram.
A subprogram follows the editing procedure described in chapter 2.
A program unit calls a subprogram with a CALL statement. The subprogram
returns control to the statement following the CALL statement.
Example
10 READ A,B !Main program begins
15 DATA 48,50
20 CALL Sub1(A,B) !Main program calls Sub1; go to line 100
30 PRINT A
40 PRINT B
99 END !Main program ends
100 SUB Sub1 (X,Y) !Subprogram Sub1 begins
105 DIM String$[1]
110 IF X<0 THEN SUBEXIT !If X<0, Sub1 ends early; go to line 30
115 String$=CHR$(X+Y) !If X=>0, Sub1 continues
120 PRINT String$
999 SUBEND !Subprogram Sub1 ends; go to line 30
User-Defined Multi-Line Functions
A user-defined multi-line function is a subunit that returns a value to
the calling program unit. The value returned by a function has a
specific type. A function that returns a numeric value is called a
numeric function; A function that returns a string value is called a
string function.
Syntax
DEFFN_stmt stmt [stmt] . . . FNEND_stmnt
Parameters
DEFFN_stmnt DEF FN statement. Not executable. Indicates that the
lines that follow are a multi-line function.
stmt Executable statements that make up the body of the
function. At least one stmt must be a RETURN statement
that returns a value and control to the calling program
unit.
FNEND_stmt FNEND statement. Indicates the end of the function.
A function is edited using the procedures described in chapter 2.
A program unit calls a multi-line function the same way it calls a
predefined or single-line function: by its name, followed by an actual
parameter list if it has one. The list of actual parameters is enclosed
in parentheses, and the individual parameters are separated by commas.
Example
10 READ A,B !Main program begins
15 DATA 48, 50
20 C$=FNFunc$(A,B) !Main program calls FNFunc$; go to line 100
30 PRINT C$
99 END !Main program ends
100 DEF FNFunc$(X,Y) !Function FNFunc$ begins
105 DIM String$[1]
115 String$=CHR$(X+Y)
120 RETURN String$ !FNFunc$ returns value to line 20
999 FNEND !Function FNFunc$ ends
A multi-line function can also be called as a subprogram with the CALL
statement. In this case, the value returned by the function is
discarded.
If a program has more than one subunit with the same name, the name
references the first subunit that it finds. The following is the search
order:
1. Single-line function.
2. Local external or intrinsic subunit.
3. Internal multi-line function (one defined by the program).
4. Global external or intrinsic subunit.
Parameter Passing
An actual parameter can be passed to a subprogram by reference or by
value. Actual parameters are passed by reference unless the individual
actual parameter is enclosed in parentheses or is an expression or
substring. Enclosing the actual parameter in parentheses specifies that
the actual parameter is to be passed by value.
Table 3-29 compares the two methods. String or numeric literals are
always passed by value. Arrays are always passed by reference.
Table 3-29. Parameter Passing Methods
-----------------------------------------------------------------------------------------------
| | | |
| | Actual Parameter | Actual Parameter |
| | Passed by Reference | Passed by Value |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Formal parameter | The actual parameter itself. | Assigned the value of the actual |
| is | | parameter. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Subprogram can | If it changes corresponding formal | No. |
| change actual | parameter. | |
| parameter | | |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Variables Passed | File designators*. | All not mentioned to the left. |
| This Way | | |
| | Arrays. | Scalar variables enclosed in |
| | | parentheses. |
| | Array elements. | |
| | | String literals. |
| | Scalar numeric variables. | |
| | | Numeric literals. |
| | Unsubscripted scalar string | |
| | variables. | Expressions |
| | | |
| | | Substrings |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Corresponding | Exactly the same type and both | Compatible types.** |
| parameters must | scalar or both array. | |
| be | | |
| | | |
-----------------------------------------------------------------------------------------------
Table 3-29 Notes
* An actual parameter that corresponds to a formal file designator
parameter must have a value that can be converted to a short integer
in the range [1, 32767].
** An actual and formal parameter are compatible if the parameters are
both string or both numeric (they must also be scalar, because whole
arrays cannot be passed by value). If the parameters are of
different numeric types, HP Business BASIC/XL converts the value of
the actual parameter to the numeric type of the formal parameter
before assigning it to the formal parameter.
Example
10 A,B=0
20 CALL Sub(A,(B)) !A is passed by reference
25 REM !B is passed by value
30 PRINT A !Prints 1 (Sub changed A)
40 PRINT B !Prints 0 (Sub did not change B)
99 END
100 SUB Sub (X,Y) !A corresponds to X; B corresponds to Y
110 X=X+1
120 Y=Y+2
130 PRINT X !Prints 1
140 PRINT Y !Prints 2
150 SUBEND
The number of actual parameters in a subprogram call must be the same as
the number of formal parameters in the SUBPROGRAM or DEF FN statement
that defines the beginning of the subprogram or function. The actual
parameters are evaluated and assigned to the corresponding formal
parameters from left to right.
Initial Subprogram Environment
Every program unit has its own operating environment. When HP Business
BASIC/XL enters a subprogram, it initializes the environment. When
control returns to the calling program unit, HP Business BASIC/XL
reinstates the environment of the calling program unit.
Table 3-30 lists the characteristics that define the operating
environment of a program unit and explains how each characteristic is
initialized.
Table 3-30. Program Unit Operating Environment
---------------------------------------------------------------------------------------------
| | |
| Operating Environment | Initial Value |
| Characteristic | of Characteristic Upon |
| | Program Unit Entry |
| | |
---------------------------------------------------------------------------------------------
| | |
| Data pointer position. | First datum in first DATA statement in |
| | program unit. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Accessible files. | Files passed as parameters and common files |
| | that program unit declares. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Trigonometric unit. | Radians. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Print format for numeric data. | Standard. |
| | |
---------------------------------------------------------------------------------------------
| | |
| Default lower bound for arrays. | Depends on OPTION BASE. |
| | |
---------------------------------------------------------------------------------------------
| | |
| ON ERROR specifications. | ON ERROR GOTO and ON ERROR GOSUB |
| | specifications that were active in the |
| | calling program unit are inactive; ON ERROR |
| | CALL specifications that were active in the |
| | calling program unit are active. |
| | |
---------------------------------------------------------------------------------------------
| | |
| ON END specifications. | ON END specifications that were active in |
| | the calling program unit are inactive. |
| | |
---------------------------------------------------------------------------------------------
Using Common Variables in Subunits
A subunit can declare an entire common area or an initial subset of a
common area that is declared in the main program. It can only access the
common variables that it declares.
A program unit declares common areas with COM statements. A subprogram
cannot contain common variables with the same names as its formal
parameters or local variables.
Example
10 COM A(4,4), B, INTEGER C, D(3,3), E$[28], F$(2,4)[56]
.
.
.
99 END
100 SUB Payroll
110 COM X(*,*), Y, INTEGER Z,Q()
.
.
.
199 SUBEND
200 DEF FNAccounts (X,Y,Z)
210 COM I()
.
.
.
299 FNEND
The following table shows the correspondence between common variable
names in the above program.
Table 3-31. Common Variable Names Correspondence
----------------------------------------------------------------------------------------------
| | | |
| Name of Common Variable | Name of Common Variable | Name of Common Variable |
| in Main Program | in Payroll | in FNAccounts |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| A | X | I |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| B | Y | None |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| C | Z | None |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| D | Q | None |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| E$ | None | None |
| | | |
----------------------------------------------------------------------------------------------
| | | |
| F$ | None | None |
| | | |
----------------------------------------------------------------------------------------------
VERIFY Command
The VERIFY command verifies specified program units; that is, it checks
that they are well-formed and prints messages if it finds errors. The
VERIFY command is a command-only statement, and it cannot be executed
when the program is running.
A program unit is well-formed if it has the following characteristics:
* Properly matched constructs.
* Consistent array references.
* No incorrectly placed statements (for example, SUBEXIT in a
function).
* No undeclared variables under OPTION DECLARE.
Syntax
[ALL ]
VERIFY [ [{,} ] ]
[progunit [{;} progunit]...]
Parameters
ALL Specifies all program units in the program, including
the main program unit. ALL is the default.
progunit One of the following:
[SUB]subunit_name.
[SUB]function_name.
[SUB]MAIN.
A program unit cannot execute unless it is well-formed. For this reason,
HP Business BASIC/XL verifies a program unit at the following times:
* At run time, if it was modified since its last call.
* Before saving it in a BASIC Save file.
Therefore, you do not need to issue the VERIFY command to check a program
before you run it, because HP Business BASIC/XL will issue it
automatically. The purpose of the VERIFY command is to allow you to
VERIFY a program as you develop it, without having to RUN or SAVE it.
Example
The following example shows what happens when a program is not
well-formed. The example below shows the results of the VERIFY command.
HP Business BASIC/XL has issued the VERIFY command when the programmer
typed RUN.
>10 OPTION DECLARE !This specifies that all variables must be declared
>20 WHILE A !A is not declared, and the WHILE statement
>25 !is not closed
>30 PRINT A
>RUN
Error 179
Structured constant on line 20 not properly closed.
Error 1403
Undeclared variable A found in subunit MAIN.
Error 157
VERIFY error(s) in program.
Calling External Subunits
External routines fall into the following categories:
* Procedures (routines that do not return values).
* Functions (routines that return values).
An external routine is called with the CALL statement. An external
function can be called with either the CALL statement or the FNCALL
function; the method depends on the function name and whether its result
can be discarded. Table 3-32 tells how to call each type of external
subunit.
Table 3-32. External Subunit Calls
-----------------------------------------------------------------------------------------------
| | | |
| External Routine | Dependency | How to Call |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Subprogram | None. | Use CALL statement. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Function | Return value can be thrown away. | Use CALL statement. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Function | Internal name is a legal HP | Call as a user-defined function is |
| | Business BASIC/XL function name. | called. |
| | | |
-----------------------------------------------------------------------------------------------
| | | |
| Function | Internal name is not a legal HP | Call FNCALL function. |
| | Business BASIC/XL function name. | |
| | | |
-----------------------------------------------------------------------------------------------
FNCALL is a predefined function that takes a function call as its
parameter. Executing an FNCALL call is equivalent to executing the
parameter (a function call). An internal function (a predefined function
or function defined by the program) cannot be called with FNCALL. An
external function with an illegal HP Business BASIC/XL function name must
be called with FNCALL. An FNCALL call can appear wherever a user-defined
function call can appear.
Examples
10 INTRINSIC ("Isubs") Sub1 !Declares intrinsic subprogram
15 CALL Sub1 !Calls intrinsic Sub1
20 EXTERNAL Sub2 !Declares external subprogram
25 CALL Sub2 !Calls external Sub2
30 INTRINSIC Irr_result1 !Function with irrelevant result
35 CALL Irr_result1
40 EXTERNAL REAL Irr_result2 !Function with irrelevant result
45 CALL Irr_result2
50 INTRINSIC FNRead !Function with legal name
55 C$=FNRead
60 EXTERNAL REAL FNWrite ALIAS "Write" !Function with legal name
65 Real1=FNWrite
70 EXTERNAL INTEGER Store (REAL X) !Function with illegal name
71 !to show use of FNCALL
75 Int1=FNCALL(Store(Real1))
80 INTRINSIC Getfile ALIAS "Get_file" !Function with illegal name
81 !aliased to legal name
85 IF FNCALL(Getfile("File2")) THEN CALL Sub1
99 END