Introduction

This is a description of a system to simplify the definition and building of objects implemented in PL/I. Functions described but not marked "{ni}" are now coded and available.

Some text at the beginning of the program, called the preamble, indicates how the following program is to be compiled and installed in the system. This text is not processed by the PL/I macro facilities -- it controls those facilities.

PLAPACK is an object that takes: (1) a key to a segment holding a program, (2) a key to a directory from which to fetch keys referred to in the program's preamble, (3) a spacebank, (4) a output port upon which troubles will be reported. PLIPACK returns a factory that produces objects that obey the compiled program.

The preamble is composed of statements terminated by semicolons. PL/I style comments may occur within these statements. Some preamble statements refer to keys by name. These names are interpreted via a directory that is made available to the compiler controller by the requestor of the compilation. In such contexts "*" may be used to refer to DK(0).

These are key names that may be used by the program with no further introduction (their declarations are in effect but invisible):
RETR the returner key.

REQUESTOR return key to factory caller

DOMCRE domain creator of domain executing your code

SYN_DOMKEY your synthetic domain key

PBANK prompt bank argument to requestor key.

METER meter argument to requestor key,

BANK Key parameter two to the requestor's key. It must be a bank.

OSCOM {(p2,oscom)}

OSFD {(p2,osfd)}

The name "ORDINAL" is a FIXED BIN(31) variable whose initial value is the ordinal of the factory. The ordinal may be set by the call described at (p2,ord2) but it should be a multiple of 4K because the low 12 bits are used as communication to the mechanism of the L-seg factory.

The functions S and SI are automatically available along with their declarations.

Factory Component Specs
The statement "COMPONENT c, c, c;" or "CMP c, c, c;" defines keys that will be made available as factory components to the compiled program. Each component is described separately. The component descriptions c are separated by commas. Each description is of the form "x exname inname".

"x" is either "H", "F" or "S" depending on the clause under which the key is to be included as a factory component. See (p2,bf) for suitable circumstances for each sort of key.

"exname" is the name of the key within a directory provided by the user. The key is retrieved from the directory at compile time.

"inname" is a name that the key is known by in the program. If "inname" is omitted then the portion of "exname" to the right of all periods in "exname" is used in its place.

If "inname" is ".DEFOUT" and the key is either a SYSP key {(p2,sysp)} or a SWITCHER key {(p2,swc)}, then output to unfiledef'd files will be delivered via that key.

".DEFOUT" indicates that the key is to be placed in c-slot 4. It is slot 4 that gets the stream of output for undefined files. Your program may place another key there with a command such as "KALL (RETR, 0) KEYSFROM(SOKLIKE) KEYSTO(4);". That key must behave as a consuming byte stream.

Similarly, input for undefined files is supplied by the key in c-slot 3.

There is currently a limit of 15 components. This will be relaxed if there is sufficient pressure.

Segment Access
This facility provides access to segments available at compile time.

The statement "SEGMENT c, c, c, ...;" or "SEG c, c, c, ...;" defines segments that are to appear in the address space of the program. Each "c" is of the form "n segkey inname" where "segkey" is the name of a memory key to be located in the directory provided by the user and "inname" is the name of an external variable whose declaration is provided by the programmer and n is "12", "16" or "20" and is the code for the segment size. "n" is the log-base-2 of the segment size.

References to the external variable will be references to the segment.

Dynamic Segment Access
The statement "SEGMENTREFERENCE c, c, c, ...;" or "SEGREF c, c, c, ...;" is like segment access described above except that it is possible for the running program to install a segment whose memory key it holds.

The statement "CALL MAP_SEG(#zot, memkey);" causes the memory key memkey to be accessible via the external variable zot where zot occurs as the inname in some SEGMENTREFERENCES statement.

Using the SEGMENTREFERENCE facility costs more than using the SEGMENTS facility and there is a limit (about 14) to how many such uses there can be in one program.

External Facilities in General
The statement "FACILITY name, name, ...;" causes the "facility modules" called "name" in the provided directory to be included in your program.

Each facility module consists of a segment with two portions: some text to be included in your program before your text; and some compiler or assembler output.

Today such facility modules may be created merely by bringing the text deck from CMS by a command such as "AUXFILE GET SEGMENT TYMNET.ZZZ 85 FACIL TEXT" and then using the editor simply to add the textual information to the beginning of the object. Such information may include declarations for external entry points which are supplied by the following compiler output.

Specific External Facilities Available in USER.SYS.FACS.
ASCTOEB
This provides a CHAR(256) value called "ASCTOEB" suitable for the expression "TRANSLATE(ascii string, ASCTOEB)" which provides a corresponding EBCDIC string.

BINTIME
Returns a floating value which is the current reading of the TOD clock (microseconds since 1900).

DES
This implements the data encryption standard algorithm.

DCL NEWKEY ENTRY(CHAR(8)) RETURNS(CHAR(128)), (CIPHER, DECIHER) ENTRY(CHAR(8), CHAR (128)) RETURNS(CHAR(8));

CIPHER(pt, NEWKEY(key)) provides the encryption of plain text pt with key. DECIHER(CIPHER(pt, NEWKEY(key)), NEWKEY(key)) = pt

CIPHER and DECIHER are several times faster than NEWKEY. Saving NEWKEY's value saves time when keys are reused.

EBTOASC
This provides a CHAR(256) value called "EBTOASC" suitable for the expression "TRANSLATE(ebcdic string, EBTOASC)" which provides a corresponding ASCII string.

RDXSORT
This provides an in core sort. It sorts an array of records in its own space.

The following structure is declared whose value you provide by assignment statments and which is passed to the sort entry point "PLSRT" thus "CALL PLSRT(ARGS);".

DCL 1 ARGS UNALIGNED, 2 (FILE POINTER, SIZE FIXED BIN(31), (RSIZE, KSIZE, KEYOFF) FIXED BIN);

FILE is the address of the array, SIZE is the number of bytes in the array. RSIZE and KSIZE are the sizes of the record and the key. KEYOFF is the offset of the key within the record.

SHEX
SHEX takes a character string and returns a string of twice the length {but max 80} that is the hexidecimal representation of the argument. SHEX('23') = 'F2F3'.

ZMK
If you have earlier specified TSSC as a component such as: COMPONENT F SYS.TSSC;, the preamble statement FACILITY SYS.FACS.ZMK; will cause key names "ZMK" and "CCK6" to be available to your program. (The COMPONENTS statement must precede the FACILITY statement.) The ZMK key may be returned to your requestor, thus allowing your program to dynamically connect via a new branch to any context {(p2,connec)}.

Undefined output files, such as SYSPRINT will then appear as output on such a branch and undeclared input files such as SYSIN will get their data from that branch. See example at end for use of this.

The code: "DO I = 1 TO 3; KALL(CCK6, 4) KEYSTO(,,CCK6); END;" will delete the extra storage required by this facility and that storage will not otherwise be reclaimed as you exit your program.

Alleged Key Type
TYPE n; causes the decimal number n to become the alleged type of the factory requestor's key.

Macro Libraries
The statement "MACLIB x, y, z;" informs the compiler controller that the PL/I preprocessor is to run in the presence of PL/I macro libraries x, y and z. "%INCLUDE" statements must still be for the library members beyond the Gnosis preamble. The system macro library PLIGATES is automatically available and "%INCLUDE GNOSIS:" need not and must not be specified.

A macro library in Gnosis is merely a record collection holding as members segments or record collections that hold the text to be included. These records must hold the text to be included within the traditional columns: 2 through 72.

End of Preamble
The statement "PL1;" ends the preamble.

{ni}Error Message Filter
The form of the SUPPRESS statement is "SUPPRESS" followed by one or more clauses separated by commas.

Each clause in the SUPPRESS statement deletes a class of error messages produced by the preprocessor and compiler.

The clause begins with an eight character token that must exactly match the first token of any error message that it deletes.

IBM software conventionally puts a unique error message number there.

The second token of the clause is a numeral expressing how many of these messages should be suppressed. If there are more than that many messages, the user will be informed of the excess. PL/I consolidates some of its messages and we may count the error indications rather than merely the messages.

Some error messages may be given special handling. Messages such as "Dummy argument created for parameter 7 of PLIJMPC" are important in some cases and not in others.

Imagine a statement such as:

PARMS S v v, PLIJMPC v v v v v r r r r;

It would mean that the parameters of routine S were to pass values but only the first five arguments of PLIJMPC were values and the last three were by reference.

{ni}Compiler Options
"OPTIONS x, y, z;" causes x, y and z to be supplied to the compiler as compile time options. Parentheses within operands of OPTIONS must be matched and included commas may occur only between matched parentheses.

{ni}Possible Upward Extensions
We would like to support programs composed of several PL/I compilations loaded into one segment and also clubs of cooperating domains obeying a variety of programs.

We would like to support object and value locking {(p2,ob-lock) & (p2,val-lock)}.

Following your preamble is a sequence of PL/I statements that comprise your program. You should provide neither a "PROC" nor an "END" statement unless you also provide a call to that routine. The statements you provide are bundled with other statements which are then enclosed between PL/I "PROC" and "END" statements.

When your program proceeds beyond the last statement that you provided, the object deletes itself and then replies with a null message to key "requestor".

The following program illustrates much of this:

CMP H SYSP .DEFOUT; PL1; PUT EDIT('Hello')(A);

This program will buy a branch on the switcher upon which SYSP was created and say "Hello". It will then delete itself.

It is sometimes useful to make a factory much like the one produced for your program by PLIPACK. The following commands produce a new factory and leave its builder's key in NEW_BUILDERS_KEY. {You must declare FACTORY_COPY_KEY and NEW_BUILDERS_KEY as keys.}
KALL (0, 3) KEYSTO(FACTORY_COPY_KEY); KALL (FACTORY_COPY_KEY, 0) KEYSFROM(BANK,METER,BANK) KEYSTO(NEW_BUILDERS_KEY);

The logic described at (pli-ord) may be used to cause the objects created by the new factory to know that they are to behave differently.

See (p2,bf) concerning NEW_BUILDERS_KEY. You must learn about sealing factories and perhaps how to change factory components.

The packager is not installed as it will be eventually. The programs you write for the packager should remain valid but the directory names in the preamble may change.

The factory USER.SYS.PLIPACKC {USER.PUB.KEYPLI for prerelease version that corresponds to this document} is a factory that produces a packer. If P is a packer then
P(0;SOURCE,DIRECTORY,SYSP ==> c;,,,CO) -- CO(0;bank,SWITCHER ==> c1;REQ,list.,BUILD) returns a factory requestor's key, REQ, to a new factory that will produce objects obeying the program provided in the segment SOURCE. The New factory requires a space bank as key parameter two which need not be prompt.

The key DIRECTORY will be used to retrieve keys mentioned in the preamble. SYSP should be a reusable co-routine, such as provided by SYSPC {(p2,sysp)}. Problems encountered during interpretation of the preamble, compilation, loading and factory creation are reported via SYSP. DDT's that arise from faults in your program will appear on a branch under switcher key SWITCHER. Key 19 within such DDT's will be DIRECTORY. BUILD will be the builder's key to the new factory.

In a future version of PLIPACK the key SWITCHER may be a node key. In this case DDT's will have that key as their key 19 and will appear on a branch under switcher key found in slot 15 of the node.

The key "list." will refer to a directory with the compiler output as "list.LIST".

The program must be in a segment. Lines of the file may hold PL/I source in positions 1 through 90. There must be no sequence numbers in the file. Note that editors are not inclined to include trailing blanks in source lines and thus we suggest that quoted strings not span lines. Note that the compiler treats "ABC" ^^ "DEF" as "ABCDEF" even without optimization.
You can get an empty segment by saying "KEYCALL SYS.FSC 0 (,SPACEBANK,METER,SPACEBANK) (,COMMON.SOURCE)", and then saying "EDIT COMMON.SOURCE". You will then be in the editor.

Successive line numbers are generated as the lines are given to the compiler. If the compiler refers to line "XXXX0052" in an error message then the available editor will show that line in response to the commands "TOP" and "N 52".

The following suggestion has been made for fitting Packer factory output to the CAM and APPLMON.

CMP F SYS.TSSC; FAC SYS.FACS.MAKE_ZMK; PL1; DCL LBN FIXED BIN INIT(-1); KALL (REQUESTOR, kt+5) KEYSFROM(ZMK) KEYSTO(LBN);

This would provide an expected ZMK to the creator and accept a node to hold late bound values.