External modules

[samiam95124]

Published 2020-09-14

The alpha (as in really early) version of external linkages is here. There are only a few calls working, but I expect this to get better rapidly.

What it is:

The external links package allows you to make calls to C routines outside of the interpreter. Thus the interpreter can make calls to (for example) standard C packages and get results.

Why is that a good idea?

Using the interpreter is a pretty dry excersize without being able to call libraries. You can perform advanced file management calls via the extend interface (named files, etc.). Obviously with a compiled code version you can hook up to external libraries, but with the superior debug capabilities in the Pascal-P interpreter, I always though it was a good idea to import a standard set of calls to the interpreter as well. Using a program written with standard Pascaline library calls, you can take a Pascaline program and run that on the interpreter, and get good debugging (and profiling and fault mapping, etc.) capabilities without changing the program.

How to do it:

At this writing, only the services.c module is hooked up. You wil find it as Appendex G in the Pascaline standard. In case you are not up to speed on that, all (ok, most) of the Pascaline packages were translated to C and placed online:

https://sourceforge.net/projects/petitami/

The petit-ami project exists because:

1. It made more sense to write these support libraries in C. All of the interfaces that the libraries use (operating systems, graphics packages, etc) are designed in C, and I can post questions/problems to the authors of those packages using C, and even reference them to the original petit-ami code[2].
2. Petit-ami is not particularly Pascal oriented. It is not designed specifically for C, either, but that dependency is avoided by simply not using some of the bad habits of C. It's pretty general purpose code, and thus can be interfaced to several languages.

Anyways, interfacing to the serivices module is simple, for example:

program test(output);

uses services;

var fp: filptr;

begin

   list('*.pas', fp);
   while fp <> nil do begin

      writeln('File: ', fp^.name^);
      fp := fp^.next

   end

end.

This is a simple file lister using the pa_list() call. It is not "pa_xxx" because this is Pascal. We don't need prefixes here.

I prefer the uses version of it, but joins works as well:

program test(output);

joins services;

var fp: services.filptr;

begin

   serivces.list('*.pas', fp);
   while fp <> nil do begin

         writeln('File: ', fp^.name^);
        fp := fp^.next

   end

end.

How it works:

Modules in P6 are run by compiling them to intermediate code, and then concatenating the intermediate files into one big one, and running it. The program module appears last in the stacking order.

The references, which I have called "far" references (yes, I know that name has other uses), have qualident notation of:

module.name

Which actually even occurs in a uses context, but is hidden from you. The far label linker step in pint recognizes the "services" module reference, and passes the call off to the external handler in externals.inc.
Its actually a bit more complex than that, the externals.inc file establishes a vector table in low memory, one vector per external call, then cup (call user procedure) calls reference the vector table, which executes a special instruction to call the external handler.

externals.inc has code that reformats the data going to the call (parameters) and calls it. On return, it does the reverse, formats data for P6, and inserts that on the stack.The reason for this is Pascal-P machine code only knows about its internal memory, and external programs only know about external memory. Even if they could be arranged to be the same, the formats used in P6 are different from the "outside world" so data reformatting is required.

This process of "hijacking" a module call happens whether or not you actually load the target module. For services.c, this module actually exists as services.pas, but it is a dummy module. The calls in it are empty. You can load the module, but it will be bypassed, and just take up space. Better is just to drop it. It is a header or definition module only.

That's it.I plan to fill out the services.c module "thunks"[1], and after I may think of other modules to include.

Will there be other, non-pascaline packages included?

Well, making a thunk layer for P6 is difficult, so the answer is simple. There will be such a package if you do it :-) Seriously, it's a lot of work, and I don't have a lot of incentive to do that.

Regards,

Scott Franco

[1] "thunk" is a Microsoft originated term for "short piece of adaption code" used to adapt one calling convention to another. I see by googling it that it has come to mean other things, but I am old, and I remember stuff, so there you are.

[2] Without having to put up with the standard comment "Wow, you are using Pascal? You must be a dinosaur...". Its gets old.