Preparing CSUBs for Use by BASIC

At this time you should have already created and debugged, to the extent possible, a Pascal module for your CSUB. The next step is to execute BUILDC.

Executing BUILDC

After you have compiled the Pascal or assembly language routine and a code file is created, you must execute the program called BUILDC to generate the header and jump files. BUILDC prompts for information about the calling sequence of the CSUB. Remember, BUILDC is asking what the routines and parameters will look like to BASIC. This may be different from the way they are defined in Pascal. Determine how the CSUB statement should look to BASIC, and answer the same way. If the subprogram was initially written and debugged in BASIC, a program listing can provide this information. Also at this time, access to BASIC COM space can be declared as discussed in the "Globals" section of the chapter "Writing CSUBs".

NOTE
On all the yes/no prompts, a response other than [Y] is treated as a negative response.

From the main command level of Pascal, type:


x BUILDC [ENTER]

BUILDC begins by prompting:



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

If you give a name for the stream file, all your responses will be recorded for future use. Next time you need only stream the file you create this time. See the main-level Stream command in the Pascal Workstation System manual for more information on streaming files. The next prompts are:


Enter name for the Header File:
Enter name for the Jump File:

These are two files that are generated by the BUILDC program. When the program is complete, the first one will contain the BASIC subroutine definition for the CSUB. The second one will contain information about where to find the beginning of the routines in the subroutine library. The names of both of these files will be asked for when the stream file GENC.TEXT, that links all the pieces together, is streamed. For convenience, you may name these temporary files HEADER and JUMP respectively. The suffix .CODE will be added automatically to these file names. This overwrites any existing files of the same name.

The next prompt is:


Enter the name of the linked code file containing the subs:
?

Enter the name of the code file that you have generated. Again, .CODE is added automatically. This code file should contain only one module. If you have more, the following warning is displayed.


*** WARNING: Code file contains more than one module ***

Only the first module found in a code file is examined to determine the amount of global space required. This warning is not a fatal BUILDC error; it implies that BUILDC cannot examine more than the first module to determine total global requirements. BUILDC constructs a COM statement (in the header file) to allocate the global space required by the first module. It is strongly recommended that the user pre-link all modules together before running BUILDC. For information on linking modules see "Linking Object Files Together" in Pascal Workstation System manual. Otherwise, the COM statement generated may not truly reflect the required global size.

If global space is required, you will be asked:


Enter COM label for global variable space (default is given)
? Csub_globals

To get unlabelled (blank) COM interactively hit [CLR LN] then [ENTER]. If you create your own stream file by hand and do not put in a label [ENTER] returns a blank COM. The default is also valid when BUILDC is making the streamfile.

If there is no global space required by the first user module, this prompt will not appear. Global/ COM information is presented in the "Globals" section of the "Writing CSUBs" chapter and "Advanced Topics" chapter.

The next prompt will be:


Enter module name:

This refers to the name given to the Pascal module. If the CSUB is written in assembly language, there will not necessarily be a module name. In this case, just press [ENTER] in response to the prompt.

The next section asks for information about the procedures. It will be repeated until a null procedure name is entered by pressing [ENTER] in response to the prompt.


Enter procedure name:

The procedure name is the same name as the procedure in the Pascal module or if written in assembly the name defined by the DEF statement.

BUILDC then checks to see if the entry point is defined by the first module of the code file. This entry point is constructed according to the rule defined in the Pascal Workstation System manual, "The Assembler" chapter.

The entry point is:


<module name><underscore character><procedure name>

If the entry point is not found in the first module of the code file, a warning of the following form is printed:


*** WARNING:  nnnnnn is not defined in this module ***

where nnnnn is the entry point; BUILDC continues to run. If you link everything ahead of time, you should not get this error. However, the <module name>_<procedure name> constructed from the responses is used to look for entry points. Linking does not change the names of entry points. Therefore, even though all modules have been linked into one big module before running BUILDC, you must answer the questions about the modules in terms of the original unlinked modules.

The next questions prompt for information about the parameters:


Parameter name:
Parameter type (I/R/C/S/P for Integer/Real/Complex/String/ioPath):
Is this an array? (y/n):
Is this an optional parameter? (y/n):

Remember, list parameters as they will look to the calling BASIC program; not as they look in Pascal.

The legal types are INTEGER, REAL, COMPLEX, STRING and I/O path. If the parameter name ends in a dollar sign ($) then the type is automatically assumed to be STRING. If the parameter name begins with an @, then the type is automatically assumed to be an I/O path. Otherwise, answer with [I], [R] or [C]. If the parameter name does not end in a dollar sign and the type entered is STRING, it is treated as an error and you will be prompted again. If the parameter name does not begin with an @ and the type entered is I/O path, it is treated as an error and you will be prompted again. If the parameter is an array, it is assumed to have dimension (*) which designates it is defined in the calling program.

If a parameter is declared optional and is not included in the BASIC CALL statement, a NIL pointer is passed to the CSUB at run time. The CSUB should be written to detect this. Once a parameter is specified as optional, all the following parameters default to optional and the prompt does not reappear. These prompts are repeated until a null parameter name is entered.

The next question about a procedure is:


Is there COM in this procedure? (y/n):

This is referring to accessing a BASIC COM from the Pascal module; not the Pascal global space mentioned previously. These prompts are made for every module.

As soon as a null procedure name is entered, the following prompt appears:


Are there any more modules? (y/n):

If you respond positively to this prompt, the sequence of prompts start over with:


Enter module name:

When BUILDC has been given all the required responses, it constructs the header and jump files. To facilitate the BASIC coding process, BUILDC prints out the COM declarations required by all the CSUBs. This includes explicit module globals and COM variables defined for access within modules.

In addition, these statements are printed to an ASCII file in BASIC source form. The name of the file is listed by BUILDC, and it resides on the current default volume. The name of the file is the first six characters of the name of the first procedure with _COM appended.

Linking the CSUB Elements

Once the header file and jump file have been created using the BUILDC program, the user will combine (link) all the elements and create the BASIC compiled subprogram by streaming the GENC.TEXT file. Stream files are a way of batching up workstation commands to be done in sequence. See the main-level Stream command in the Pascal Workstation System manual for more information on streaming files.

In this case the GENC stream file has commands to link the user routine with appropriate CSUB library routines, execute the program (RELDATA) that extracts relocation information, link the jump file and header file with the user routines and then execute a program (BUILDLIF) that writes the completed routine to an SRM, HFS, or LIF formatted disk.

These programs should be on the disk to execute the stream file. For example, in order to run the CSUB generating programs, only one disk drive need be available on the machine. However, you may find it necessary to have two mass storage devices if the CSUB being generated is large. In some cases, you can use one device (the default volume) to hold all the CSUB code files, libraries, and stream file, and another to hold your code file, the header and jump files and the final CSUB. These are files whose volume name can be specified interactively, without having to modify the stream file. Remember that the System Volume must be on-line to stream a file. In this case, making the second volume the System Volume is the preferred alternative. To specify the system volume name for the temporary files, use "*".

In more extreme cases, it is necessary to modify the GENC stream file so that CSUB_TEMP includes a volume specifier, too. There are five occurrences in the stream file where CSUB_TEMP must be modified. Just change "CSUB_TEMP" to "*CSUB_TEMP" using the Editor. Of course, the system volume specifier "*" can be changed to any legal volume specifier which is on-line.

Generating a CSUB

Once again, these are the detailed steps to generate the CSUB after the Pascal module is written.

  1. Use the Librarian to manually pre-link all compiled/assembled code into one module. Remember, you must link in IODECLARATIONS and GENERAL_0 if doing device I/O.

  2. Use the Filer's Prefix command to set the default volume prefix to the unit that contains the CSUB Utility files (BUILDC, CSUBLIB, CSUBDECL, RELDATA, and BUILDLIF).

  3. Execute BUILDC putting the files it generates (header and jump) on either the default volume or another volume.

  4. Stream the file GENC.TEXT by pressing [S] from the Main Command Level and entering the name "GENC.TEXT". GENC asks for these items:

    
    Input file name
    Header file name
    Jump file name
    Enter 'P' for linkmap.
    

    Type the file names (and volume/path names, if needed). The suffix .CODE will be added automatically. If you enter P for linkmap the local system printer (volume #6:) must be on-line. The linkmap will then be listed to the printer. Alternately, you can send the linkmap to a file (type P filename) or not have one made (type [ENTER]).

    After entering this, the system will begin the stream. If there are errors in the stream, all processing will stop and the error displayed. Linking produces a file called CSUB_TEMP containing the fully linked CSUB. CSUB_TEMP will be written to the default volume (unless you've added a volume prefix).

    The GENC stream file then executes the program that writes the CSUB as a BASIC PROG file. When it is ready to output the CSUB, it prompts:

    
    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.
    

    If you want the CSUB on the default volume, just press [ENTER]. Alternatively, specify any volume you prefer.

    If something should go wrong trying to create the BASIC PROG file, BUILDLIF does not purge the input file after it gets done using it. This allows you to re-execute BUILDLIF rather than re-streaming the entire GENC file. If you do this, you must provide the name of the input file, CSUB_TEMP.

    When finished, you have a BASIC PROG file with the name of the first procedure in the Pascal library, truncated to 10 characters. All procedure names in the library are truncated to 15 characters.

  5. Re-boot the BASIC system and LOAD the program that calls the CSUB. This CSUB library can then be loaded into your BASIC program using LOADSUB.

  6. [RUN] the BASIC program.

Standard GENC.TEXT File

The minimal stream file that links all the CSUB user components together looks like:


=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

Editing GENC.TEXT

If you need INTEGER and STRING I/O routines, you must add the following line to the first section of the stream file after M CSUBENTRY and before TM CSUBSYM. Within these limits order is not significant.


TM FS

If you need REAL number math, add this line also.


TM ALLREALS

If you need REAL number I/O, add this line.


TM MFS

In order to link any of the modules in CSUBLIB listed in the first section, you must add the line:


TM <module name>

In general you can link all your code in either of two ways:

Any module that contains global variables must be pre-linked before running BUILDC so that BUILDC can allocate space for these variables. In particular, IODECLARATIONS and GENERAL_0 are in this category.

Remember, the CSUBENTRY module in CSUBLIB must be linked as the first module of the GENC stream file. Other modules of the CSUB can be linked in any order.

If you need a module that is not contained in CSUBLIB, the GENC stream file must be modified differently. Rather than adding a TM MODULE line, you must break up and add lines to the last line of the first linking section of the stream file (reprinted here):


LO CSUB_TEMP
L @P
I CSUBLIB
M CSUBENTRY
TM CSUBSYM
TI @I
ALKQ

The last line is replaced with these three lines:


AI FILENAME
M MODULE1NAME
TLKQ

If you needed more than one module, the last line is replaced with these lines:


AI FILENAME
M MODULE1NAME
TM MODULE2NAME
TM MODULE3NAME
TLKQ

FILENAME is the name of the file containing the needed modules. MODULExNAME are the names of the needed modules. None of these modules should contain Pascal globals or CSUB entry points. (If they do, you must link them in before running BUILDC.) For more information see the Stream command and the Librarian in the Pascal Workstation System manual.

The second linking section (reprinted here) should be left as is; especially Header which must be the first item in the final code file.


LO CSUB_TEMP
L @P
I @H
AI CSUB_TEMP
AI CSUBRDATA
AI @J
ALKQ

Calling CSUBs from BASIC

Before you can call a CSUB, you must load it into memory.


LOADSUB ALL FROM "file_name" 

This statement causes the entire CSUB library to be loaded into BASIC memory.

It is possible to have a PROG file consisting of several CSUB libraries generated at different times and merged together by doing LOADSUB and STORE. Assume that we have the following PROG file:


Main
Suba (library A)
(begin library B)
Subb
Subc
Subd
(end library B)
(begin library E)
Sube
Subf
Subg
(end library E)
Subh

For example, if Suba and Subc are referenced in a program LOADSUB FROM "file_name" will cause library A and library B, from Subc to end, to be brought in. The other libraries are not brought in unless the contained procedures are referenced.


10 LOADSUB "sub_name" FROM "file_name"

This statement causes all the code in the library containing sub_name to be loaded from file_name but only procedures from sub_name to the end of the library are listed in the BASIC program.

For example, if Subc is loaded, Subd is also loaded.


10 LOADSUB ALL FROM "file_name" 

This statement causes all subprograms in file_name to be loaded.

Editing CSUBs

CSUB libraries are generated by a single execution of the BUILDC program. All CSUBs belonging to the same library are contiguous and must remain in the order in which they were generated. The BASIC system will not let you add BASIC program lines between CSUB statements, as this would modify the CSUB above the new entry. For CSUBs to execute properly, they may not be modified in any way. Once a CSUB has been modified, you must reload to execute it.

Any number of CSUB entry points may be deleted from the beginning of the library, but not from the end or the middle.

For example. the above PROG file contains CSUB library B with entrypoints Subb, Subc, and Subd. You may delete the first two entrypoints Subb and Subc and still be able to call Subd. You may not delete Subc, leaving Subb and Subd, because entrypoints may be deleted only from the beginning of the library, not from the middle or the end.