A compiled subprogram (CSUB) is a routine that is written in either Pascal or assembly language on a Pascal workstation and transformed into a routine that is callable as a subprogram from BASIC. Either a single CSUB or a library of CSUBs may be generated using this technique. Then, after leaving the Pascal workstation and entering the BASIC system, the CSUB is loaded into memory using the LOAD or LOADSUB command and called like any other BASIC subprogram.
NOTE |
---|
CSUBs written for BASIC 2.0/2.1 must be created on a Pascal 2.0 workstation. CSUBs written for BASIC 3.0 or later must be created on a Pascal 3.0 or later workstation, using the CSUB utilities whose revision corresponds to the revision of BASIC. This manual documents the CSUB Utility for BASIC 6.0. Though BASIC 6.0 is globalized, Pascal is not. This affects how you use the CRT I/O command, DISP_AT_XY. For information about globalized BASIC 6.0, see HP BASIC Programming Techniques, Volume 2: Porting and Globalization. |
This manual assumes you are familar with the BASIC language, editor, data types, and subprograms.
Before creating CSUBs, you must also know how to use the Pascal workstation to write and compile programs. To generate CSUBs, a good working knowledge of the Editor, the Compiler (or Assembler), and the Librarian is necessary.
You should also understand the Pascal language IMPORT/EXPORT features which will be used heavily to incorporate information from libraries. For information, see the "Pascal Compiler" chapter in the Pascal Workstation System manual.
The principles of linking in Pascal must be understood before attempting to link additional modules and libraries into a CSUB. For information, see the "The Librarian" chapter in the Pascal Workstation System manual.
Learn these things before proceeding with this manual. All this information can be obtained from the Pascal Workstation System Manual.
CSUBs are used to fill a number of needs:
For example, when a set of benchmark programs were run, performance using CSUBs was far superior to BASIC. In these benchmarks, REAL and INTEGER loops, transcendental and non-transcendental math, quick and shell sorts, and matrix multiplication were compared. For the quick sort, the CSUB ran many times faster than a similar BASIC routine. For transcendental math, the CSUB was found to be marginally faster.
The price paid for this speed is the size of the routines. CSUB code will always be larger than comparable BASIC code. Two reasons for this size increase are:
There are some limitations in using CSUBs. Only BASIC INTEGER, REAL, COMPLEX, string, and I/O path type parameters can be passed to a CSUB as opposed to Pascal data structures. Routines must have all external references fully resolved before they can be used as CSUBs. This may lead to problems if calls to Pascal system routines generate unresolved external references or other errors. The "Linking the CSUB Elements"section in the "Preparing CSUBs for Use by BASIC" chapter and "Unresolved External References" section in the "Errors" chapter contain more information about this problem.
The Pascal Procedure Library is now supported for HP-IB and GPIO cards. Limited support is available for RS-232C interfaces. Refer to the "I/O From CSUBs" chapter under the "Device I/O" section for details.
However, no transfer capability is supported. Also, limited file access is now allowed; refer to the "I/O From CSUBs" chapter under the "File Access Library" section.
The CSUB utility consists of several different system components, two libraries and three programs.
The two libraries that are included are CSUBDECL and CSUBLIB. CSUBDECL's declarations may be imported into your CSUB routines using the Pascal IMPORT command (e.g., IMPORT CSUBDECL;). CSUBDECL is a library file that contains the export text/declarations for the modules CSUBDECL, CSFA, KBDCRT, HEAP, COMSTUFF, and CSUBENTRY. The CSUBDECL module contains no code. The CSUBDECL file is only for use during compilation. Refer to the appendix "Useful TYPE Declarations" for a listing of export text in the CSUBDECL file.
Module | Contents |
---|---|
COMSTUFF | export text for routines for accessing COM |
miscellaneous BASIC file I/O declarations | |
type declarations for passing BASIC parameters | |
export text needed to facilitate entry and exit from CSUB | |
export text for routines that support heap management (requires COMSTUFF) | |
miscellaneous BASIC keyboard and crt I/O declarations |
CSUBLIB is the other library file and contains run-time support for CSUBs (used when linking). There are no declarations (i.e., export text) in CSUBLIB to be imported. It holds the following modules:
Module | Contents
|
---|---|
ALLREALS | REAL number arithmetic support
|
contains routines for accessing COM (export text in CSUBDECL)
| |
miscellaneous BASIC file I/O routines
| |
contains code to facilitate entry and exit from CSUB (must always
be present; export text in CSUBDECL)
| |
defines some entrypoints into BASIC and bootrom routines. It
contains no code. (must always be present)
| |
support for string and INTEGER read and write
| |
read and write firmware interface registers
| |
character I/O routines plus timeout and I/O system setup
| |
implements string and real number I/O
| |
translates Pascal I/O errors into text messages
| |
contains routines to support heap management (requires COMSTUFF; export
text in CSUBDECL)
| |
provide low-level access to the HP-IB controller and bus
| |
low-level bus control commands for HP-IB
| |
HP-IB message commands
| |
high-level bus status and control commands for HP-IB
| |
additional heap routines necessary when HEAP_DISPOSE compiler
option is turned on (requires COMSTUFF and HEAP)
| |
tests and manipulates bits in a 32-bit INTEGER
| |
must be present to use GENERAL and HPIB modules | |
miscellaneous BASIC keyboard and crt I/O routines
| |
support for REAL read and write (requires ALLREALS and FS)
| |
miscellaneous Pascal support routines
| |
support routines for Pascal sets (3.0 only)
| |
Pascal string support routines |
The first program is called BUILDC. BUILDC is an interactive program run by you to gather information about the subprogram (CSUB) being generated and how it will look to BASIC.
The other two programs, RELDATA and BUILDLIF, are used by the stream file, GENC.TEXT. The GENC stream file is a sequenced batch file containing commands to link the user routine with library routines, execute the program that extracts relocation information, link the jump and header file with the user routines and then execute a program that writes completed routines to a formatted disk.
The first program to be executed in the GENC stream file is RELDATA, which generates relocation information for BASIC. RELDATA reports all unsatisfied external references. The second program, BUILDLIF, takes the fully linked routine and reformats it to a BASIC PROG file.
The following steps are an overview of the process needed to create a CSUB and the results of those steps. The CSUB dependent steps are described in detail in later chapters.
This section goes through each step of creating a CSUB with an example. This example is written for a system that has more that one volume on-line. All files used in the Pascal environment are read from and written to the current volume to which the default prefix is set. In the BASIC environment, the CSUB is loaded from the MSI device.
This simple program fills an array of string variables and then calls a Pascal CSUB which determines if a particular string is found in the array. The BASIC program keeps track of how many valid strings are contained in the array and passes that information to the Pascal CSUB. If the INTEGER variable Yes comes back with a value other than zero, it comes back pointing to the array element containing the matching string.
Enter the BASIC system, edit and store this program in FSTR.
10 LOADSUB ALL FROM "FIND_STRIN"
20 DIM File$(1:10)[20]
30 DIM Str$[20]
40 INTEGER Num_strs,Yes
50 File$(1)="HELLO - HOW ARE YOU?"
60 File$(2)="I AM GREAT"
70 File$(3)="WHAT IS YOUR NAME?"
80 File$(4)="WHERE ARE YOU GOING?"
90 File$(5)="FAVORITE COLOR?"
100 File$(6)="I LIKE YOU"
110 Num_strs=6
120 Str$="WHERE ARE YOU GOING?"
130 Find_string(File$(*),Str$,Num_strs,Yes)
140 IF Yes<>0 THEN PRINT "The string was found in number";Yes
150 IF Yes=0 THEN PRINT "The string was not found"
160 DELSUB Find_string
170 END
Enter the Pascal system, edit, store in STRING.TEXT, compile and debug this module, TEST.
MODULE TEST;
$SEARCH 'CSUBDECL'$ {Add volume id if not in default volume}
IMPORT CSUBDECL;
EXPORT
TYPE string_type = RECORD
len : shortint;
chars : PACKED ARRAY [1..20] of CHAR;
END;
str_array = ARRAY [1..10] of string_type;
PROCEDURE Find_string (file_dim : DIMENTRYPTR;
VAR FileX : str_array;
str_dim : DIMENTRYPTR;
VAR StrX : string_type;
VAR Num_strs : BINTVALTYPE;
VAR Yes : BINTVALTYPE);
IMPLEMENT
PROCEDURE Find_string ;
VAR i, j : integer;
BEGIN
yes := 0;
i:= 1;
while (i <= Num_strs) and (yes = 0) do
begin
if FileX[i].len = StrX.len then
if StrX.len = 0 then yes := i
else
begin
j := 1;
while (j < FileX[i].len) and
(FileX[i].chars[j] = StrX.chars[j])
do j := j = 1;
if (FileX[i].chars[j] = StrX.chars[j])
then yes := i;
end;
if yes = 0 then i := i = 1;
end;
END;
END.
In this case, you do not need to execute the Librarian and link the code files since there is only one Pascal module and no device I/O. Now, use the Filer's Prefix command to set the default volume to the where the CSUB Utility resides.
Execute BUILDC. Give these responses to the BUILDC program. Notice that a stream file is generated by the response to the first question. Next time, you can just Stream the file named TEST1STR which itself executes BUILDC and answers all the questions as they are answered when the stream file is created. This example assumes that all files are located on the default volume. If this were not the case, the Stream file and the answers would have to be modified as in "Example One" in the "Complete Examples" chapter.
Compiled Subprogram Header and Jump File Generator (Version 6.0)
Enter the name for a Stream File for BUILDC:
(or just press <ENTER> for no stream file) :TEST1STR
Enter name for the Header File: HEADER
Enter name for the Jump File: JUMP
Enter the name of the linked code file containing the subs:STRING
Enter module name:TEST
Enter procedure name:FIND_STRING
Parameter name:FILEX$
Parameter type is string
Is this an array? (y/n):Y
Is this an optional parameter? (y/n):N
Parameter name:STRX$
Parameter type is string
Is this an array? (y/n):N
Is this an optional parameter? (y/n):N
Parameter name:NUM_STRS
Parameter type (I/R/C/S/P for Integer/Real/Complex/String/ioPath):I
Is this an array? (y/n):N
Is this an optional parameter? (y/n):N
Parameter name:YES
Parameter type (I/R/C/S/P for Integer/Real/Complex/String/ioPath):I
Is this an array? (y/n):N
Is this an optional parameter? (y/n):N
Parameter name:
Is there COM in this procedure?(y/n):N
Enter procedure name:
Are there any more modules ? (y/n):N
Stream the GENC.TEXT file. No modifications were necessary for this stream file. At the prompts, answer:
Input file name?
STRING.CODE
Header file name?
HEADER
Jump file name?
JUMP
Enter 'P' for linkmap.
[ENTER]
At the prompt for 'P', typing [ENTER] (as shown) leaves the printer off. Typing 'P' sends the linkmap to the connected printer and typing 'Pfilename' places the linkmap in filename. After answering the prompts, the system continues through the stream file shown here:
=IInput file name?
=HHeader file name?
=JJump file name?
=PEnter 'P' for linkmap.
LO CSUB_TEMP
L @P
I CSUBLIB
M CSUBENTRY
TM CSUBSYM
TI @I
ALKQ
X RELDATA
CSUB_TEMP
CSUBRDATA
LO CSUB_TEMP
L @P
I @H
AI CSUB_TEMP
AI CSUBRDATA
AI @J
ALKQ
FR CSUBRDATA.CODE
Q
X BUILDLIF
CSUB_TEMP
At this time, the system requests a second volume or directory:
Input file: CSUB_TEMP
Enter the unit number or volume name of the
initialized media that is to contain the CSUB.
Just press <enter> for the default volume.
If needed you can swap media so that the BASIC
program file (the CSUB) goes on a different media.
After you answer the question, the system finishes streaming GENC and returns:
File to be created - FIND_STRIN
Size of text is 1252
In this example, FIND_STRING is loaded from the BASIC program. So, all that is left to do is re-enter the BASIC system, LOAD "FSTR" and [RUN] the program. The results will be:
The string was found in number 4