See (p3,ossim) for information about the environment produced here.

OS Environment using Binder

Old OS Environment

Usage

OS programs can be viewed at three levels. The simplest for the CMS or OS programmer is when no explicit gate jumps appear in the OS program. All capabilities accessed are either not known by the programmer {i.e., CLOCK} or through some file access. "files" are accessed through DDNAME's and involve the use of FILEDEF. Factories using GNOBIBMA are most appropriate.

The simplest for the Gnosis programmer is when no FILEDEF's are used. All keys are passed via explicit gate jumps. Any "file" operations are done with explicit gate jumps or memory mapping. In this mode the OS simulator is supporting only the needs of the run time memory management of the high level language.

The third use takes advantage of both the Gnosis world and the OS world. Some keys are passed through FILEDEF and some via explicit jumps. "File" access is sometimes accomplished with the language access methods and sometimes via explicit gate jumps. The programmer must be familiar with many of the "back doors" of the OS simulator {OSFD and OSCOM, for example} to move keys in and out of the OS simulator environment.

With multiple FILEDEF contexts, it is possible to have fairly standard programs operate in different environments with only changes in the surrounding command system calls. This represents a not too desirable reversion to the days of OS but provides that the structure of an application is visible from the outside through directory listings and FILEDEF? listings.

Slot 3 & 4 are SIK6 & SOK6 keys {(p2,sik6)}. Guard them well: they are the only authority to the circuit that there is. The circuit is lost if they are lost.

Statements like "PUT LIST('XYZ')" mean "PUT FILE(SYSPRINT) LIST('XYZ')" {According to official PL/I rules}. If FILEDEF {(p2,filedef)} tells the PL/I library that SYSPRINT is a terminal, or FILEDEF provides no definition for SYSPRINT, then output to SYSPRINT will be via SVC 93. The OS simulation handles SVC 93 {TPUT} by using the above SOK6 key.
The PL/I library does an SVC 93 for each PUT FILE(SYSPRINT) statement. This has the fortunate consequence that the data comes out on your terminal shortly thereafter rather than waiting for the line to fill up, which would be the case if the library did not consider SYSPRINT to be connected to a terminal.

Similarly for GET and SYSIN.

Actually it is more complex than this: Much of the OS simulation merely assumes that c-slots 3 and 4 hold terminal SIK and SOK keys. This will not be the case if your program has put something else in these slots or if have initialized your object via the facilities described at (gnbc) or (hi-ord) in which case your object will have no standard terminal keys.

When the program accesses a file by specifying a DDNAME {OS jargon} the name will be satisfied by the FILEDEFQUERY key provided by the requestor. Output to files whose DDNAME is not defined by the FILEDEFQUERY key is directed to the terminal co-routine whose SOK key is expected to be found in c-slot 4. This is the convention for programs loaded with GNOBIBMA but not GNOFIBMC. Input from undefined files is similarly via the SIK key expected in c-slot 3.

The builder may wish to install some keys that can be used by the program without reference to a directory. The builder is not likely to want his or her directory installed as a component.

The components node is also in c-slot 0 {of the cache} (after the old convention of having WOMBFACIL there).

The requestor, by supplying a FILEDEFQUERY key, allows the program access to some directory. If such access is not wanted {the requestor doesn't know what the builder might do to his/her directory} Filedef's can be done in advance via the OSFD key and the FILEDEFQUERY key may be one that always returns "file not defined". This is how a compiler front end would work.

OSCOM

OSFD - Filedef from the Program

The OSFD key is used to move keys into the OS simulator world. The program (or an outsider) can associate a key with a DDNAME using this key. After this "binding" of key with DDNAME, the program can access the key by OPEN of a DCB with the DDNAME matching the DDNAME given to the OSFD key.

The effect of defining a DDNAME with this key has precedence over defining the DDNAME through the FILEDEF domain. The external FILEDEF key is not called to resolve a DDNAME if the DDNAME has been defined with this key. The binding of the DDNAME with the KEY is permanent, however the key can be replaced by redefining it.

If FK is the capability designating some kind of file supported by OS access method simulation, then:

{ni}OSFD(0,command-image;FK==>rc,error-message;) causes the key FK to be accessed whenever the program requests I/O to the OS DDNAME specified in command-image. Command-image is in nearly the same form as (p2,filedefdef).

OSFD(1,((8,DDNAME),(176,JFCB));FK==>;rc) defines a file via a JFCB and associates it with a specific DDNAME. DDNAME must be left justified, with trailing blanks. Rc will be 0, if the JFCB was accepted and the key FK will be accessed whenever the program in OSR requests I/O to the file known by DDNAME. Rc will be 2 if the JFCB was not valid. The key associated with DDNAME can be replaced by a subsequent call specifying the same DDNAME.

The JFCB is a 176 byte OS style control block which describes a particular file. The JFCB holds coded information from the DD statement in OS JCL. The Gnosis FILEDEF object holds such blocks for each file that it knows. The following fields should be defined: DSNAME, RECFM, LRECL, BLKSIZE, RKP, and KEYLEN. DSNAME may be supplied as a clue in debugging situations. The IBM publication "S229-3169" provides detailed information on the names and positions of the fields of the JFCB as well as clues as to their meaning. Some excerpts follow:

RECFM: byte at 100 10.. .... F Fixed. 01.. .... V Variable. 11.. .... U Undefined. ...1 .... B Blocked (with Undefined only!).

LRECL: two bytes at 104, Logical Record Length

BLKSIZE: two bytes at 102, Maximum Block Size

{ni}OSFD(2,(8,DDNAME);==>c;FK) returnc rc = 0 and releases the JFCB associated with DDNAME, and returns the capability FK associated with that JFCB. If no JFCB exists, rc will be 1.

OSFD(kt;==>x'414')

Access to the synthetic domain key is provided in the following indirect manner. The assumption is that the synthetic domain key is of no use if the OSSIM domain keeper is busy (it is an entry key to the same domain). The domain creator is passed the entry key and asked for the real domain key. The domain key is used to fetch the domain keeper key and the domain keeper is requested to return the synthetic domain key {(getsyndk)}. The synthetic domain key is not returned by the requestor key.

The domain key found in c-slot 3 of the program is the synthetic domain key.

There is an extended question here about what happens when OSSIM itself traps thus leaving the program stopped and itself busy. This is no worse than it is now. An improvement may be to give the OSSIM domain a domain keeper that does not go to DDT but sends the OSSIM domain to a safe place where it can save the reason for the trap and exit to a zero data key. The program domain could be restarted after any repairs are made to the OSSIM domain by the builder.

Eventually there will be two OSSIMF factories. One will be discreet and not trap. It will simply appear to stall when an error occurs. The requestor of the service will have to get the cooperation of both the builder of the service and the builder of the OSSIMF to determine what is wrong. The builder of the service will determine that the domain is trapped and give the synthetic domain key (he may think it is real) to the builder of OSSIMF. OSSIMF may now be debugged.

The second OSSIMF will trap to a DDT on the builder's switcher.

See (p3,synkeys) on similar issues.