OS program factories (and all about GNOFIBM)

Code called GNOFIBM is available {(p3,gnofibm-use)} to be included in a .program. GNOFIBM is responsible for making the transition from the factory environment to the OS environment upon invocation of a requestor's key. GNOFIBM expects the following components:
The OSSIMF factory (c4) (ossimfact) (available from SYS.OSSIMF or WOMB_FACIL_SUPP_OSSIMF), Super Node factory (c5), the PL/I library read only segment (c6), Returner (c7), DKC (c8), and in c9 a data key with 2 bytes of time zone and 4 bytes for the address of the beginning of free storage allocation {will continue through address 6FFFFF. The .program component is a factory that produces an address segment with the OS program in it {such as a virtual copy segment factory}. GNOFIBM is declared as the starting address.

If the factory was produced by the Command System OSFACT command, Component 2 will be the .program, and Component 15 will be a data key with the starting address.

GNOFIBM, in response to the requestor, uses a modified version of the extended jump protocol to accept the FILEDEFQUERY key {(filedefqry)}, a CLOCK key, an argument key, and the OS parameter list if the program is to be run immediately. If OSFACT is a requestor's key to a factory with the above components then:
If the ordinal of the factory is less than 32768.
OSFACT(kt+5;SB,M,SB ==> kt+5;,,,,OSFACTCO)
The second Space Bank is used by the .program factory (such as a vcsk) to allocate space for changed pages.

OSFACTCO(kt+5;FILEDEFQUERY,CLOCK,ARG ==> kt+5;,,,,OSFACTCO)
ARG is a key that will be available to the program in cache slot 10.

OSFACTCO(oc,osparms;SIK,SOK,PARM ==> c;,PARM,SIK,SOK)
Run the OS program using the OS parameters passed on the third part of the extended jump. Destroy the domain when the program terminates. C is the return code from the OS program.

oc is currently unavailable to the OS program, but is included for consistency.

NOTE that the returned SOK may be DK(0) since the OS environment closes SYSPRINT and SYSOUT when the program terminates.

or

OSFACT(kt+5;SB,M,SB ==> kt+5;,,,,OSFACTCO)

The second Space Bank is used by the .program factory (such as a vcsk) to allocate space for changed pages.

OSFACTCO(akt;FILEDEFQUERY,CLOCK,ARG ==>c ;OSENTRY,OSFD)
Build the program domain and return the entry key to the program. The assumption here is that the program is reusable. OSFD is the key that can be used to simulate the filedef function. OSFD may be called with an OS JFCB and a key which will be bound together and made available to the OS program for use. The program may use the key in slot 1 of its domain (OSCOM) or simply OPEN a DCB with the DDNAME. C indicates the success of this operation.

Return codes

c = 0 success

c = 1 The first space bank is not prompt and official

c = 2 The first spacebank doesn't have sufficient space

c = 3 calling sequence error

c = 4 OSSIMF factory failure

c = 5 SNODE factory failure

Akt becomes the alleged type of the program. If specified as zero (0) the alleged type will be x'FF14'. 0 < akt < kt.

OSENTRY(oc,osparms;SIK,SOK,PARM ==> c;,PARM,SIK,SOK)

SIK,SOK,PARM will go into slots 3,4,5 and the factory keys from 3,4,5 will be moved to slots 7,8,9. Slot 10 will have the ARG key, and slot 11 has the key to the second spacebank. SIK, SOK, PARM will be returned to the caller in the same fashion as is currently done, that is the return keys are DK(0),PARM,SIK,SOK.

As in the previous case oc is not available to the OS program.

NOTE that the returned SOK may be DK(0) as the os environment closes SYSOUT and SYSPRINT when the program terminates.

OSENTRY(kt+4 ==> 0) destroys the OS program domain and its OS simulator domain. Any space allocated by the program itself will not be destroyed.

OSENTRY(kt ==> akt) or if akt was specified as 0, x'FF14'.

If the ordinal of the factory is between 32768 and 65535.
OSFACT(akt;SB,M,SB ==> c;OSENT)

This calling sequence is much like the traditional creator sequence. The OSFD key is in cache slot 10. The second spacebank key is in slot 11.

OSENT(oc,params;key1,key2,key3 ==> c;key1,key2,key3)

Note that the key order on the return is more traditional.

The order code is not available to the program.

Keys 1-3 go into cache slots 3,4,5. Slots 7,8,9 contain the factory keys that were in slots 3,4,5.

If the ordinal of the factory is greater than 65535.
OSFACT(oc;SB,M,SB ==> ?)
In this case the program is run immediately and is responsible for returning to the caller. The return key to the requestor is in cache slot 2. The program will answer KT rather than GNOFIBM. If the program returns to GNOFIBM, the domain will be destroyed and the caller (designated by the gate in cache slot 2) returned to with the contents of slot 3,4,5 returned as the keys.

The order code is passed to the OS program as a 4 byte parameter that is the binary order code.

Cache slot 10 has the OSFD key and slot 11 has the second spacebank key. The factory keys that were in slots 3,4,5 are in slots 7,8,9 but since 3,4,5 are not involved as parameters, they are the same as in the factory.

If the program ABENDs then the returned string is up to 4096 bytes of data that was the SYSPRINT file. High Ordinal programs have SYSPRINT defined to a page.

GNOFIBM uses the OSSIM factory key to request a domain keeper to support the OS environment. A supernode is created and KJUMP initialized. The OSSIM domain keeper is installed and GNOFIBM either returns with the entry key or runs the program. After OSSIM is installed as the domain keeper the program domain has as its domain key the synthetic domain key. Only the OSSIM domain holds the real domain key.

Free Storage

Dynamic memory allocation begins at the first page boundary after the end of the linkedited module and extends to the beginning of the PL/I library. Most programs can figure on having a total of 7 megabytes for the linkedited module and dynamic storage allocation.

When the domain is called, GNOFIBM calls the program as a subroutine (as in OS). The action taken when the OS program returns to its caller (GNOFIBM) depends on how the domain was called. If the ordinal is less than 32768 and the second order code in the extended jump sequence to the requestor key was kt+5 (indicating an immediate execution), then the OS program domain and the OS simulator will dissolve before returning to the caller. If any other order code was the second (setting the akt), then the program domain will return to the caller without dissolving. An SVC 13 will also destroy the domain. It is the responsibility of the program to destroy anything it creates before returning to GNOFIBM. The program of course may exit to the caller directly and even accept order code kt+4 (which may just cause an SVC 13).

Summary

C-slots
Slot 0 The components node

Slot 1 OSCOM key

Slot 2 EXIT to requestor key's caller

Slot 3 Parameter zero (often SIK)

Slot 4 Parameter one (often SOK)

Slot 5 Parameter two (often a node or CCK)

Slot 6 The domain creator

Slot 7 The synthetic domain key

Slot 8 The First Spacebank on the requestor call

Slot 9 The meter key

Slot 10 If the ordinal < 32768 Then the ARG key {(smord)} Else the OSFD {(osfd)} key

Slot 11 The key argument two of the requestor call

Components
0 - Space bank transformer

1 - Domain creator creator

2 - sometimes the .program {if created with the OSFACT command}

3 - A copy key

4 - OSSIMF the OS simulator factory

5 - Super Node factory

6 - read only key to PLILIB {PL/I libraries}

7 - Returner

8 - Data Key creator

9 - Data key with 2 bytes of time zone and 4 bytes of the start of Storage allocation (the highest address+1 of the .program)

15 - sometimes a data key with the start address {lower 4 bytes} if created by the OSFACT command

Ordinals
0-32767 The model of OS programs. They may be reused or single shot depending on the calling sequence.
With these ordinals, a call on the requestor's key returns an entry key without the OS program having been entered.

These programs are intended to interface with the command system. The OSFACT command produces factories of this type. The OSFLOAD command calls these factories and puts the entry key into the directory. The EXECUTE or FORK commands will call these entry keys with terminal keys as keys 3,4,5 and run them.

32768-65535 a not so useful model of the traditional Gnosis creator.
The OS program is not run as part of the "creation" process. All of the setup is in GNOFIBM. The OS program is first called when the "created" object is invoked. The key calling sequence is restricted because the order code is not available to the OS program once it is invoked. Only the keys in cache slots 3,4,5 can be passed in either direction.

65536- The model of the Gnosis creator.
The OS program runs as part of the "creation" process and is responsible for returning to the Caller {slot 2} for keys and order code. If the OS program returns {PL/I end of program}, The domain is destroyed and keys 3,4,5 are returned. The return code is the contents of register 15 when the OS program returned.

Note here that since keys 3,4,5 are not involved in the calling sequence, they are left as in the standard factory {(fac-slots)}. Keys 7,8,9 are duplicates. In fact keys 3,4,5 can be overlaid by the program without any ill effect.

High Ordinal OS objects can use the OS file SYSPRINT (as in PUT EDIT in PL/I) and PL/I run time messages will be written to this file. The contents of the file are returned as a string when the program terminates (returns to GNOFIBM). If the SYSPRINT file exceeds 4096 bytes, the domain will crash to a DDT. However if PL/I detects a run time error such as string size, the PL/I error will be returned along with the return code (2000 decimal usually) to help diagnose the problem.

This factory will be called from GNOFIBM and passed CLOCK, FILEDEFQUERY, the domain key of the program factory, and the data key that describes the time zone and the largest address in the program. The OSSIM factory has as components the Record collection factory (c4), Discrim (c5), the data key creator (c6), Super node creator (c7) and returner (c8).

OSSIMF initializes itself, installs itself as the domain keeper {databyte 0}, builds a new meter and installs itself as the meter keeper {databyte 3}, installs itself as the domain key {databyte 1}, windows the user memory, and returns the communication key {databyte 2} and OSFD {databyte 4} which is used to establish local filedef's.

OSSIMF(kt+5;SB,M,DOMKEY ==> kt+5;,,,OSSIMFCO)

DOMKEY is the domain key of the program domain that is to be kept by the OSSIM domain.

OSSIMFCO(0;FILEDEFQUERY,CLOCK,DATA ==> c;OSCOM,OSFD)
FILEDEFQUERY is a key that will resolve DDNAME's into keys. CLOCK is a time of day server. DATA is a data key that has 2 bytes of time zone and 4 bytes indicating the highest address used by the program in the domain. Free storage allocation will begin at this address and run until the address x'6FFFFF'.

See (p2,oscom) about OSCOM and (p2,osfd) about OSFD. This OSCOM does not obey order code kt+4.

The Domain Keeper key understands one explicit order code other than kt.

DK(1; ==> 0;SYNDOM) returns the synthetic domain key.

DK(kt; ==> x'214')