Language Extensions for Gnosis

Introduction
These are some facilities for extending PL/I to support the direct manipulation and invocation of keys. All actions that can be taken by a domain in Gnosis can be done by a PL/I program in a domain with these facilities (including referencing a segment via its key).

These facilities require the following concepts and knowledge on the part of the user:

What it means to invoke and pass keys in general.

What it means to invoke the particular keys that are required to do the job.

How to put and update a program in a segment (such as using an editor)

Access to and knowledge of some command system sufficient to invoke the keys described here.

Knowledge of PL/I sufficient for the job

There are two systems that provide access to these facilities. To compile and load in CMS see (plilink). To develop entirely within Gnosis see the system described at (preamble).

Calling Keys in PL/I

Meanings of Compiler diagnostics (and other retributions).

When the compiler warns that a DUMMY has been created for argument 14 of PLIJMPC, it means that the “sv” of a “Stringto” isn't declared CHARACTER VARYING.

If there is no compilation with an “OPTIONS(MAN)” included or if the compilation of that module was suppressed due to errors, a DDT without symbol tables will pop up trapped about 02c00 in GNOIBM.

If you specify no RCTO in your KALL and a nonzero return code comes along, you will be thrown into DDT {(ddtdoc,)} at an execute of an SVC. “1r;x4;” will provide the order code and “key x,080000000;” will return the alleged type of the thing that returned the code. Here x is bits 8 thru 11 of reg 0 gotten by “0r;x4;”. “plistack;” will display the stack with source code line numbers if you compiled with the GONUMBER option.

Auxiliary functions and suggestions:
The function S is declared “DCL S EXTERNAL ENTRY(FIXED BIN(15), FLOAT BIN(109)) RETURNS(CHAR(14) VARYING)”. It returns a string whose length is the value of the first argument and whose bits are the two's complement representation of the value of the second argument. The condition SIZE is signaled if the value can't be represented within the available bits.
Where this manual might call for “((4,17),(2,45))” as the byte string argument you may write “STRINGFROM(S(4,17)^^S(2,45))”.

Another useful construction here is LOW(n) which is a built-in function that produces a string of n binary zero characters. Similarly HIGH(n) produces a string of n X'FF' characters.

Expressions such as “UNSPEC(SUBSTR(sv,4,11))” can be used to retrieve the binary values that are held in string parameters sv. Use “BINARY(UNSPEC(SUBSTR(sv, 4,11)))” if you are worried about PL/I's secret conversions surprising you. These expressions produce fairly efficient inline code.

If you need to do arithmetic on long binary values in the character string you may use “SI(SUBSTR(sv,4,11))”. SI {S inverse} returns a FLOAT BIN(109) and is declared “DCL SI EXTERNAL ENTRY(CHAR(*)) RETURNS(FLOAT BIN(109))”. The value will not be negative.

The external routine SHEX is a routine that converts a character value to hexadecimal representation suitable for printing. It has nothing to do with Gnosis per se. It should be declared: “DCL SHEX EXT ENTRY(CHAR(*)) RETURNS(CHAR(80) VAR);”

The entry KLEAN is declared EXTERNAL ENTRY KLEAN(FIXED BIN). Its effect is to save the expense of copying a value from the cache to the super-node when the value is not required. The result is that the key value may be replaced by an older value.

For example suppose that the last use has been made of the key in slot X. “CALL KLEAN(X)” at this point may make the program faster and cheaper but will not affect what the program does.

The PL/I Factory Packager (PLIPACKER)

Multitasking is not supported.

The SORT interface is not supported.

Dynamic loading (FETCH/RELEASE) is not supported.

CHECKPOINT/RESTART is not supported.

DELAY doesn't delay.

VSAM files are not yet supported.

Regional 2 and regional 3 datasets must have keys of 252 or fewer characters.

The Checkout Compiler is not currently supported {except under CMS}.

See (p3,osiorestrict) for further hints about file support.

See the PLIXOPT feature of PL/I about setting execution parameters such as “NOSPIE”.

Include “DCL PLIXOPT CHAR(6) VAR INIT('NOSPIE') STATIC EXTERNAL;” to ward off PL/I error handling in favor of DDT's.

Unfortunately this mode breaks support for the DXR ;instruction; that may not be implemented on your machine. OS has arranged to simulate this instruction upon interrupt if the processor does not understand it. PL/I compiles this instruction to divide floating point numbers with more than 56 bits.

The PL/I loader PLILOAD is the same as OSLOAD ((p2,osload)) with the following exceptions.

The PL/I run-time and transient libraries are built in and shared, including the standard versions of IBMBEEF and IBMBEER.

A version of the PL/I binder factory, called PLIBFA, is available without IBMBEEF and IBMBEER, if you want your own.
Also included are the popular external procedures S and SI.

PLILOAD(kt; ==> X'80F0D';)

{spec}Some Unsolved Problems

Recursive key slots
A recursive procedure that uses key slots has an awkward problem: how to reclaim the key slots in key space when it returns. Presumably these key slots are named by variables declared “DCL KEY_SLOT FIXED BIN(15) INIT(-1);”. Such variables are initialized to -1 upon each entry. Non recursive routines can use static variables for this.

A complete solution to this problem seems to require modifying a compiler so as to allocate and free frames for keys as it now allocates and frees stack frames.

This, in turn, would require some concomitant design changes to KJUMP and the key cache logic.

Instructing new domains

It is currently hard for a PL/I program to create and instruct a new domain. We would like to support a PL/I program that looks something like the following:

SHOW: PROC; ... CALL CREATE_DOMAIN (INSTRUCTIONS, REF_ENTRY_KEY); ... INSTRUCTIONS: PROC; /* CODE TO BE EXECUTED BY THE NEW DOMAIN */ END INSTRUCTIONS; END SHOW;

If we write such a program the routine CREATE_DOMAIN gets access to a stack frame address and the address of the code compiled for INSTRUCTIONS. The PL/I environment is prepared at this point for INSTRUCTIONS to be called with access to that stack frame. Such access will be used in case of variables referenced within INSTRUCTIONS and declared outside. We shall require that the block where the call was executed remain active while the domain exists if there are such references.

The effect of the call is to create a domain that shares storage with the existing domain {like two cpu's sharing main storage} and starting the domain with PSW pointing at the code of INSTRUCTIONS and the display register pointing at the stack. An start key to the new domain would be returned to REF_ENTRY_KEY

The new domain would have a {virtual} copy of the keys of the creator. The effect of a return in the new domain would be to delete the new domain.

The meaning of “CALL CREATE_DOMAIN(INSTRUCTIONS);” is thus very much like that of “CALL INSTRUCTIONS TASK;”.

The domain would remain busy for its duration unless it executes a KRETURN statement. In such a case the start key to that domain would become useful for communicating with the domain.

Whether to share keys

A dilemma here is whether to share keys. We have said that we will not.

If two domains share a FIXED BIN(15) variable in a slot-defining context the semantics are strange at best and perhaps fatal. If we were to share slots as well as storage we would have all of the key cache problems that designers of multiprocessor 370's have with storage caches.

Such a design would require that the supernode be shared and also that either the cache be shared or that there be cache coordination logic between the caches. Neither of these ideas seem attractive to me.

The problems referred to in (key-stack) and (share-key) lead me to question the whole key cache design. I have no alternative design now.

I think a less accurate and quicker LRU algorithm would win.

We recommend including ;PUT; statements and using the SYSP facility {(p2,sysp)}.

Program interrupts in Gnosis

See (osparm) about directing your program traps to DDT. See the following for details for why.

PL/I normally issues a SPIE macro requesting control upon interrupts. When the program reaches a breakpoint set by DDT the interrupt is given to this PL/I error handler instead of DDT.

The PLIXOPT feature referred to in (osparm) disables the SPIE macro and gives all interrupts to DDT.

When a key invocation resulting from a KALL instruction traps due to a rejected return code, the OS simulator knows that no real OS program will understand this kind of interrupt and so it gives it to DDT even when SPIE has been issued.

Thus the statement “KALL (RETR, 1);” will cause a DDT to appear over the program even if the PLIXOPT has not been used. Breakpoints will not work without PLIXOPT because the interrupts they cause are thought by the OS simulator to belong to the PL/I runtime stuff.

If DC is the domain creator for the domain executing the compiled and X is a start key to that domain then:

KC DC 2 (,X) (,D) KC D 2 () (,DK) KC DK 1 () (,SDK) DEBUG SDK

Will create a DDT over the domain. The ;%x; DDT command may be used to stop the program if it is looping.

“plistack;”; shows the stack indicating stack frame location and the subroutine name when available and line number if the program was compiled with the GN option. The compiler output gives the address of automatic variables within the stack frame. Those variables may thus be displayed.

See (kjumpadebug) about finding keys in the key cache.