HP 3000 Manuals HP 3000 Manuals
Writing ANYPARM External Procedures
Writing an ANYPARM external procedure requires a thorough understanding
of the method that HP Business BASIC/XL uses to implement ANYPARM calls.
This section is divided into two subsections. The first subsection
describes the requirements for formal parameters to be included in the
procedure header and the actual parameter table passed to the ANYPARM
external procedure. The second subsection describes the internal data
structures that HP Business BASIC/XL uses to store the values of
variables in memory.
Requirements for the External Procedure
The external procedure must have two formal parameters. The first is a
value parameter to which is passed the number of parameters in the call's
actual parameter list. The second is a value parameter to which is
passed the address of the actual parameter table. In the MPE XL
operating system environment, the first parameter type must be a 4 byte
integer, and the second parameter type must be a 4 byte pointer.
The first formal parameter (the number of actual parameters) must be
checked prior to using the address of the formal parameter table. If the
number of actual parameters is zero, the address is set the value of
Pascal's NIL pointer constant. On the MPE XL based HP 3000, this value
is the four byte integer, 0.
The Actual Parameter Table
HP Business BASIC/XL prepares for the call to the external by building
the actual parameter table. First, it must be determined whether the
actual parameter is an HP Business BASIC/XL variable, an expression, or a
literal. Expressions are evaluated and the result is assigned to a
temporary variable. Literals are assigned to temporary variables of the
appropriate type. If the value is a temporary variable, the address of
the temporary variable is entered into the actual parameter table.
Otherwise, the actual parameter is an HP Business BASIC/XL variable, the
address of which is entered into the actual parameter table. The second
entry to the actual parameter table is the type of value present. The
third entry is the dimensionality of the value at the specified address.
If the value is a scalar, then the dimensionality is zero. Otherwise,
the dimensionality is the number of dimensions of the HP Business
BASIC/XL array. The data type and dimensionality information are
contained in the flag word that immediately follows the address of the
actual parameter. The structure of the resulting actual parameter table
in memory is:
+---------------------------------------+
| address of parameter 1 |
|---------------------------------------|
| flag word 1 |
|---------------------------------------|
| address of parameter 2 |
|---------------------------------------|
| flag word 2 |
|---------------------------------------|
| . |
| . |
| . |
|---------------------------------------|
| address of parameter n |
|---------------------------------------|
| flag word n |
+---------------------------------------+
Flag Words - Data Type and Dimensionality Information
In the MPE XL operating system environment, each of the 4 byte flag words
is divided into a left, high-order 2 bytes and a right, low-order 2
bytes. The left 2 bytes contains the data type of the associated actual
parameter. The values that HP Business BASIC/XL uses to designate the
corresponding HP Business BASIC/XL data types are the same as those
returned by HP Business BASIC/XL's TYP and BUFTYP functions:
1 DECIMAL
2 STRING
5 SHORT INTEGER
6 SHORT DECIMAL
11 INTEGER
12 SHORT REAL
13 REAL
The right (low-order) 2 bytes will contain zero if the actual parameter
is a scalar. A string is considered to be a scalar. If the actual
parameter is either a string or numeric array, the right 2 bytes will
contain the number of dimensions of the array.
HP Business BASIC/XL's Internal Data Structures
The address of the HP Business BASIC/XL variable entered into the actual
parameter table is that of either the data value itself or the HP
Business BASIC/XL data structure information that is stored together with
values of that type.
Scalar Numeric Values
For numeric expressions that are evaluated and stored in a temporary
variable, scalar numeric variables and individual elements of a numeric
array, the address is that of the actual value stored in memory. The
amount of memory used by each of these values is dependent on the data
type as illustrated in the following table:
DECIMAL 8 bytes
SHORT INTEGER 2 bytes
SHORT DECIMAL 4 bytes
INTEGER 4 bytes
SHORT REAL 4 bytes
REAL 8 bytes
The Pascal data types used to declare HP Business BASIC/XL's DECIMAL and
SHORT DECIMAL data types are explained in the section, "Pascal Data
Structures for ANYPARM Calls," later in this appendix.
Scalar Strings
The data structure that HP Business BASIC/XL uses to store strings
consists of two parts:
1. A dope vector that (in the MPE XL environment) consists of one 4
byte word to indicate the maximum number of characters allowed in
the string (the declared length) and one 4 byte word to indicate
the actual number of characters currently in the string.
2. The characters in the string.
The address that is passed to an ANYPARM EXTERNAL is the address of the
dope vector, not the address of the first character. The structure of
the string in memory is:
Address in the
actual parameter table
references
| +---------------------------------------+
-----> | maximum length |
|---------------------------------------|
| actual length |
|---------------------------------------|
char- | first| second | third | fourth |
acters: |---------------------------------------|
| fifth | sixth | seventh| eighth |
|---------------------------------------|
| . |
| . |
| . |
+---------------------------------------+
NOTE HP Business BASIC/XL always reserves an extra byte at the end of
all strings, including each element of string arrays. When
computing the size of an element, this extra byte must be taken
into account. For example, in a string array dimensioned with
eight characters per string, each element will take up 20 bytes.
The actual number of bytes used to store a string can easily be
calculated by the following formula:
bytes_required = 8 + maximum_length +( 4 - ((maximum_length + 4) MOD 4))
Arrays
All arrays are preceded by a dope vector that describes pertinent
information concerning the number of elements in the array and the number
of dimensions. The address of the array in the actual parameter table
passed to the external procedure is that of the first word in the array's
dope vector.
Array dope vectors contain the following information:
1. The address of the first word of the data portion of the array.
2. The total number of elements (not words or bytes) in the array.
3. For each dimension:
a. The total number of elements in the dimension.
b. The lower bound for the dimension.
There can be up to six dimensions in an array.
The array dope vector has the following structure:
Address in the
actual parameter table
references
|
| +---------------------------------------+
-----> | address of beginning of data area |-----
|---------------------------------------| |
| total number of elements | |
|---------------------------------------| |
| number of elements in dim 1 | |
|---------------------------------------| |
| lower bound of dim 1 | |
|---------------------------------------| |
| . | |
| . | |
| . | |
|---------------------------------------| |
| number of elements in dim n | |
|---------------------------------------| |
| lower bound of dim n | |
|---------------------------------------| |
| start of data |<---
| . |
| . |
| . |
+---------------------------------------+
String Arrays
A string array is just an array of scalar strings. The address for the
string array in the actual parameter table is actually that of the first
word of information in the string array's array dope vector. The
structure of a string array is on the next page.
![[]](../../pic3k/M010189/ADDRESS3c50.gif)
Figure G-1. String Array Structure