Directories

The command language provides the facilities to invoke all the keys available in a DIRECTORY in full generality. In this sense it is a slave to its user. The directory is provided when the command interpreter is created. The directory is a hierarchical set of Name Sequenced Record Collections {(rec-collect)} accessed with the aid of a REGISTRY {(p2,registry)}. This structure provides features similar to the hierarchical directory systems in MULTIX and UNIX(r) with some very important differences.

The most important difference is that a Gnosis directory structure can have many names for the same key to an object. As a result of this characteristic, it is possible to remove the directory entry for an object without deleting the object itself. The general problem of space recovery and the life time of objects is handled with guarded space banks {(p2,guarded)}. This technique allows direct user control over the lifetime of objects.

Another important differences is the lack of a system-wide root directory. This means that, unless you explicitly pass your directory to another user (or the process that created your command system passes it), there is no way that ANYONE else can access it.

It may happen that there is a key in your directory with same name as a CL84 reserved word. In order to access one of these keys it will be necessary to specify the name as a string (i.e. in quotes).

There are two levels of command syntax available in the command interpreter called the high level and low level syntaxes respectively. The high level syntax allows key invocation with syntax similar to the command languages on many current interactive systems (e.g. IBM CMS). The low level command syntax is similar to the syntax used to describe gate jumps in the Gnosis External Specifications manual. It may be used to call any key in the directory.

Either level of command syntax may be proceeded by the key work "FORK". If this is done the key will be forked rather than called. Any returned data or keys will be lost.

The High Level Command Syntax

A high level command consists of a sequence of tokens separated by one or more blank spaces. The first token must be the name of a key in the directory and the second the name of an operation that is valid for the type of the key. If the second token is missing the operation called "DEFAULT" will be attempted. (n.b. If the second token starts with an open parenthesis "(", then the call is a low level call.)

The tokens that follow the key and the operation are interpreted as parameters of the operation. They are divided into two groups, positional parameters and key word parameters. The positional parameters come first. The key word parameters are separated from the positional parameters with a comma. They are specified as key word - token pairs. A list of the key words may be obtained by using the "help" operation (a question mark) after typing the required positional parameters and the comma.

A token may be of one of five general types:

A "word" is a string of non-blank, printable characters that do not contain the characters comma, question mark, left or right parenthesis, quote, or apostrophe. Note that decimal numbers are considered "words" at this level. Examples:
123word456

Template_directory

63

A "string" is a string of any characters except carriage return, or Control_T (DC4) enclosed with either quotes or apostrophes. If the enclosing characters are to be included in the string then they must be doubled. Examples:
"This is a string"

'that''s mine'

"that's yours"

A "number" is a string of pairs of hex digits (0123456789abcdefABCDEF) enclosed in quotes and followed by an X. Examples:
'AB CD'X

'012345'x

A "list" is a sequence of tokens (including other lists) separated by one or more blanks, and enclosed in parenthesis. Examples:

nocompile)

A "special token" is a "word" that defines a key that will be provided by CS84. The special tokens now defined are:
CCK6, SIK6, or SOK6
If this is the first of CCK6, SIK6, or SOK6 encountered, a new terminal branch will be created. The appropriate terminal key will be provided in this slot. This new branch will automaticlly become the active branch immediately before the jump. After the key returns, the branch will be deleted. (N.B. if the key is FORKed, the branch will not be automaticlly deleted.)

The high level syntax is converted to the low level syntax with the aid of a data structure called a "template". When a high level command is recognized, the template is acquired through the following process:
(1) The type of the key is determined by first using DISCRIM {(p2,discrim)}. If it is a data key then KT+1 is assigned as the type. If it is an exit key then KT+2 is assigned as the type. If it is a meter key then 6 is assigned as the type. Otherwise the key is called with order code KT and the return code from that call is used as the type.

(2) The key named TEMPLATE_DIRECTORY in the directory is accessed. If there is no key with that name then high level syntax calls are not available.

(3) The TEMPLATE_DIRECTORY key is assumed to be a named sequence record collection, and is accessed using the type of the key expressed as a four byte binary number. If there is no matching record or if the record does not have an associated key then high level calls are not available for this key.

(4) The key returned in step 3 is assumed to be a named sequence record collection and accessed using the EBCDIC operation specified in the command, translated to upper case if necessary. The data area of the record is then interpreted as the template.

The first part of the template describes the rest of the tokens in the high level syntax. Each token has information that will be printed by the interpreter when the HELP operation is invoked (the question mark key), and optionally, restrictions on the values that the parameter may assume. (e.g. it must be an existing key or a number.) An error message to the user will be issued if the value is of the wrong type and the key will not be invoked.

The second part of the template describes, using the low level syntax, how the parameters specified in the high level syntax are to be interpreted as a gate jump.

The Low Level Command Syntax
in this file for the BNF. A low level command consists of key_name( instead of the required KEY( as specified in that BNF.

Help Facilities
Control-T may be used to fill in the characters in common in all entries matching a partially entered "word" token. These tokens include keys in the directory, operations, and key words.

Question mark (?) may be used to request help at any point. If it immediately follows (no spaces) a "word" token it will list all the choices matching the partially typed token. If it is entered alone it will list the available options (e.g. key names in the directory or available key words) or print the "help" data for that specific token.

Pipe Syntax
It is possible to tie keys defined in either level of command syntax together in UNIX(tm)-like pipes. This facility uses the same "special tokens" described in the high-level syntax {(st)} to connect a series of keys in a coroutine linkage. The individual key invokations are separated with the vertical bar (^). If the first key specifies a SIK6 or the last key specifies a SOK6 a terminal system will be built as in the non-pipe situation. If the line is proceeded by the key work "FORK", the last key will be forked rather than called and no keys or data will be received. (N.B. Only the keys and data generated by the last key specified will be received.)

Examples:

list(0,sok6==>) ^ filter(0;sik6,sok6==>) ^ format(0;sik6,sok6==>)
This command line forks key "list" causing its output (on "sok6") to be passed to key "filter" with a coroutine linkage to "sik6". The output of "filter" is likewise linked to "sik6" of "format". Since "format" is the last key and specifies a "sok6" key a terminal system is built to pass the output of format to the terminal.

Input/Output Redirection
If the first (or only) command of a pipe expression is followed by "< KEYNAME" the data in the object KEYNAME (which must be acceptable to the os simulator {(p3,ossim)} for QSAM simulation) will be converted to a byte stream and passed to the first command as its "standard input" (SIK6) key.

Similary, if the last (or only) command of a pipe expression is followed by "> KEYNAME" or ">> KEYNAME" then its "standard output" (SOK6) will be respectivly placed in or appended to the object KEYNAME (which must be acceptable to the os simulator {(p3,ossim)} for QSAM simulation). If KEYNAME does not exist in the directory, a fresh segment {(p2,fsc)} will be created to hold the data.

The following words are "reserved" in the sense that if you want to access a key in your directory with the same name as a reserved word you must specify its name as a string (i.e. in quotes).
CCK6

FORK

SIK6

SOK6

Relation to Extended Jump Protocol
The command interpreter uses extended jump protocol {(p3,ejp)} whenever the low level syntax (as generated from a template or typed directly) specifies more than three keys or more than 4096 bytes of data to be passed. This behavior can cause problems in specific instances so the following exceptions have been built into the interpreter.
When an order code of KT+5 is specified in a jump specification, exactly that jump is performed. A return code from the gate is not interpreted as an invitation to receive more data and/or keys, but is treated as a non-extended jump return code and printed on the terminal (if non-zero).

The ability to directly control which data and keys are passed on which jumps of the extended jump protocol is provided to aid in calling factories passing strings and other similar situations. (N.B. the factory can not accept a string on the first call of an extended jump sequence.) For example:

factory(kt+5;sb,meter,sb==>); cokey(0,string==>;entry)