Pascal Adapter Routines 155
156 Pascal Adapter Routines
INTRODUCTION
Most of the system subroutines described in MTS Volume 3,System Subroutine Descriptions, can be called from both PASCAL/VS and PASCAL/JB. Calling MTS system subroutines from Pascal is, in general, complicated by the fact that Pascal is a strongly typed language, which implies that each external routine (subroutine or function) called by a Pascal program must be declared within that program. Earlier sections in this volume describe how to construct Pascal declarations and calls for MTS system subroutines for both Pascal/VS and Pascal/JB. Even using these methods, the process is often complicated and time consuming. For example, GUINFO is a commonly used system subroutine; a typical invocation of the GUINFO subroutine might look like this:
Program Example;
Type PAC_8 = Packed Array[1..8] of Char;
PAC_256 = Packed Array[1..256] of Char;
PAC_48 = Packed Array[1..48] of Char;
Guinfo_Type = (GU_Fixed, GU_Int1, GU_Int2, GU_Var);
Gresult_type = Record case GUINFO_TYPE of GU_Fixed: (Fixed_Char: PAC_48);
GU_Int1: (Integer_Val : Integer);
GU_Int2: (Integer_Val1, Integer_Val2: Integer);
GU_Var: (Max_Length, Length : Integer;
Chars: PAC_256);
End;
Procedure Guinfo(const item_name : PAC_8;
var guinf_result : gresult_type);FORTRAN;
Var Temp:gresult_type;
This call to the GUINFO subroutine illustrates some of the difficulties involved when declaring and calling from Pascal a routine that returns a mixture of fullword integer, doubleword integer, and character information in a single argument.
As an alternative to the above method, the user may instead call a set of routines that are functionally equivalent to many MTS system subroutines but are designed to be Pascal-callable without constructing complicated declarations and calling sequences. These routines are located in the subroutine libraries *PASCALVSSYSLIB and *PASCALJBSYSLIB and are much easier to use.
The calling sequences for these routines are simpler than the corresponding MTS Volume 3 subroutines.
The program described above could be written much more easily by using the routines PGUINFOI, PGUINFO2, and PGUINFOS which are contained in both subroutine libraries. These routines
Pascal Adapter Routines: Introduction 157
perform the same functions as GUINFO.
Program Test;
%Include PGuinfoI
%Include PGuinfoS Var Res1 : String(18);
Res2, Res3, Res4 :Integer;
Res5 : String(30);
THE ORGANIZATION OF THE %INCLUDE AND SUBROUTINE LIBRARIES
All of the information necessary to call the routines described in this section is contained in the two subroutine library files and their corresponding %INCLUDE library files. The files
*PASCALVSSYSLIB and *PASCALVSINCLUDE are used together with PASCAL/VS. The files
*PASCALJBSYSLIB and *PASCALJBINCLUDE are used together with PASCAL/JB.
Both of the %INCLUDE library files contain Procedure or Function declarations for the routines in the subroutine library files which are equivalent to the MTS system subroutines.
Some of the routines in each subroutine library are called “adapter” routines and perform functions that are similar to the MTS system subroutines. Each of these routines passes one or more parameters to specific system subroutines, returns results back to the calling program, and processes error conditions. Other routines are called “support” routines and either alter how adapter routines behave when they detect an error or retrieve information about an error when an error condition occurs. These libraries also contain an “error monitor” routine which is not called directly by the Pascal program, but is invoked indirectly whenever an error condition occurs.
Also included in the %INCLUDE libraries are declarations for MTS subroutines that, by their nature, can be called directly without using *PASCALVSSYSLIB and *PASCALJBSYSLIB and thus are not included in the libraries. If the subroutine being called is not in these libraries, declarations must be constructed and calls made for them according to the procedures described in the sections on Pascal/VS and Pascal/JB.
HOW TO USE THE %INCLUDE AND SUBROUTINE LIBRARIES
To use a %INCLUDE library in Pascal, the correct %INCLUDE library file must be attached when running the Pascal compiler. With *PASCALVS, one of the units 1 through 8 must be assigned to the file *PASCALVSINCLUDE. With *PASCALJB, one of the units 1 through 8 must be assigned to the file *PASCALJBINCLUDE. In addition, the source program must contain %INCLUDE statements so that the necessary declarations for the routines that are called are retrieved from the %INCLUDE library. %INCLUDE statements can be placed whenever declaratives are legal. In general, at least one %INCLUDE statement will be needed for each subroutine that is used. For example,
Program Test;
{Example of program that calls MTS, QUIT, and SYSTEM}
158 Pascal Adapter Routines: Introduction
%INCLUDE MTS
%INCLUDE QUIT
%INCLUDE SYSTEM
VAR DONE, ERROR, SUSPEND:BOOLEAN;
...
IF DONE THEN SYSTEM;
IF SUSPEND THEN MTS;
IF ERROR THEN QUIT;
...
Extra %INCLUDE statements will be needed if %INCLUDE items that refer to Types that are defined in other %INCLUDE items. Such %INCLUDE statements must be before other %INCLUDE statements. All the %INCLUDE statements must appear in a part of the program where it is legal to have declaratives, i.e., after a Procedure or Function statement, but before the associated Begin statement.
Each subroutine description in the following sections lists all the %INCLUDEs required to use that routine. All of the required %INCLUDES must be placed in the declaration section of the procedure or function. The order of the %INCLUDES is important if a specific subroutine requires more than one
%INCLUDE. Also, if two or more subroutines are being used, the same %INCLUDE statement may not be used more than once. Failure to use the %INCLUDEs correctly will result in Pascal error messages.
For example, suppose we wish to use the PGETFD, PREAD, and PWRITE subroutines. The description of the PGETFD subroutine lists
%INCLUDE PGETFD
%INCLUDE Fdub_Type The description of PWRITE lists
%INCLUDE PWRITE
%INCLUDE Fdub_Type
%INCLUDE IO_Modifiers The description of PREAD lists
%INCLUDE PREAD
%INCLUDE Fdub_Type
%INCLUDE IO_Modifiers
Since duplicates of %INCLUDE Fdub_Type and %INCLUDE IO_Modifiers are not allowed, the program should look like this:
PROGRAM XXX;
Pascal Adapter Routines: Introduction 159
After the source program is compiled, the object program must be run. If one or more routines are needed from the subroutine libraries, concatenate the correct subroutine library file to the file containing the object program. The subroutine library file for *PASCALJB is *PASCALJBSYSLIB and the subroutine library file for *PASCALVS is *PASCALVSSYSLIB. For *PASCALVS, a typical command sequence might look like this:
$RUN *PASCALVS SCARDS=sou 1=*PASCALVSINCLUDE SPUNCH=-obj
$RUN -obj+*PASCALVSSYSLIB SCARDS=data
For *PASCALJB, a typical command sequence might look like this:
$RUN *PASCALJB SCARDS=sou 1=*PASCALJBINCLUDE SPUNCH=-obj
$RUN -obj+*PASCALJBSYSLIB SCARDS=data
Note that it is very important to use the correct file names. Using either *PASCALVSINCLUDE or
*PASCALVSSYSLIB with *PASCALJB or vice-versa may result in obscure run time errors.
USING FILES FROM A SYSTEM SUBROUTINE
Many of the routines described in the following sections use, access, or manipulate MTS files. In most cases, instead of referring to the file by name, the file is referred to by giving either a unit or a Fdub-pointer. A Fdub-pointer can be obtained for a specific file or device by calling the routine PGETFD and placing the resultant Fdub-pointer in a variable of type Fdub_Type. This Fdub-pointer can subsequently be given to the routine in question. Alternately, the name of a logical I/O unit represented as a string can be supplied, i.e., “SCARDS”, “SPUNCH”, “SPRINT”, “SERCOM”,
“GUSER”, or an integer unit between 0 and 99. A unit between 0 and 9 is represented as a one-character string, for example, “0” or “1”. A unit between 10 and 99 is represented as a two-character string, for example, “10” or “15”. Examples of this are given in the individual subroutine descriptions.
160 Pascal Adapter Routines: Introduction