This is the original command language. See (ncs) for a newer available command system. For older ideas about command languages see (p2,gnocli). DDT {(p2,ddt)} also provides a facility to directly execute commands.

New User Names and New Instances of Command Systems

Instances of the context switchers are normally created in the process of installing new user names by tools alluded to in (p2,admin). Context switchers create new command systems for each new context (p2,context-create).

{arcane}The installation of a new user creates an entry in the LUD {(p2,lud)} under the new user name. The start key of that entry will be to the zapper module of the context switcher. All command systems within a context switcher share the same zapper key, and thus most of the time the zapper key in the lud "connects to" one of the command systems.

{spec}See (p2,login) for some ideas about passwords and other things.

Each command system within a context has a distinct directory, meter and guarded space bank. Several other keys unique to the command system include a REGISTRY, FILEDEF and VDKF. The directory of each context has an entry COMMON, which is a subdirectory common to all contexts. It is the only such directory into which keys may be written by the context which is shared between the contexts.

The user name "GNOSIS" is usually added to the system upon big bang. Thus you get to the command language by getting to a Gnosis receptionist {(p2,receptionist)} and identifying yourself as "GNOSIS". The SYSTOOL command "INSTALLUSERS" installs an assembled set of usernames.

A command system is always part of a context switcher! The first time a user logs on to a context switcher, there are no contexts (with command systems). It is necessary to create a command context before using Gnosis. At the initial character prompt of "[" type "CREATE main<CR>" and wait for a bell that indicates that the command system has something to say. Hit return and the system will type "MAIN.A]" indicating that the switcher has switched to branch "a" of context "main". It should say "WELCOME TO GNOSIS (CSMxxx)" and then prompt for input with "A:". You may then enter commands. See (p2,cswitchc) for more information on the commands available to direct and control contexts.

In all cases where commands cause keys to be added to the directory, there is the possibility that there exists in the directory a key with the same name. In this case the system will prompt for corrective action if the key to be overlaid is anything but a data key. The action selected may be to replace the key or to select a new name. If the key is replaced the old key will be lost. No action is taken other than to replace the key, the old object will still exist (if it existed at the time the directory was updated). If it is desired to destroy the old object the ZAP command can be used before the key is lost if the object is a space bank guard. Directory entries can be deleted by using the DELETE command.

SPECIAL KEY NAMES

The Command System circuit keys are available as the names SIK6, SOK6 and CCK6. These names are not in the directory but are recognized as special names and the keys are moved in and out of the Command System slots where they are kept.

The key named by SOK6 disappears at the end of the command. Ditto SIK6.

ADDLUDKY name password ludbyte key controlkey [spacebank] [meter]
"name" is up to 11 characters that is the LUD name.

"password" is the password that must be typed (in UPPER case) on the first login to the new LUD name to get the key put into the LUD (11 characters max)

"ludbyte" is a number that is converted to binary which becomes the first byte of the ludstring {(p2,ludformat)}.

"key" is the name of the key that is put into the LUD.

"controlkey" is a key that can be used to change the key in the lud. "KEYCALL controlkey 0 (,newkey)" will change the key in the LUD to newkey. (p2,addlud)

"spacebank" (if present) is the spacebank out of which the circuits will be built. The default is to use the user's command system spacebank.

"meter" {if present} is the meter used for the circuits. The default is to use the user's command system meter.

RETURN CODES

1 - LUD name is not unique.

2 - 4 internal errors, see a Gnosis expert.

AUXDEF keyname1 keyname2 sysno FILENAME FILETYPE [FILEMODE] [RECFM F^V LRECL NNNNN] ["PROJECT CODE AND POST LOGIN STRING"]
This command will put into the user's directory under the name keyname1, a key to a domain {(p2,auxmangr)} that will manage the transfer of the file to or from a Gnosis application. The management domain will return a co-routine key for a record stream consumer or producer to transfer the file to the application after it is called at OPEN time. The CMS file is accessed in a PL/I or PASCAL program by use of the FILEDEF command. Keyname1 is the key to the capability to access the remote file, keyname2 is a circuit building capability, and sysno is the Tymnet host number for the circuit.

For a complete description of the parameters see the AUXFILE command (p3,auxfile).

RETURN CODES

See a Gnosis expert.

AUXFILE SEND^GET SEGMENT^RECORD directory-name circuit sysno FILENAME FILETYPE [FILEMODE] [RECFM F^V LRECL NNNNN] ["PROJECT CODE AND POST LOGIN STRING"]
This command causes a file to be transferred between Gnosis and CMS immediately.

Directory-name is the key to a Gnosis data structure of the type SEGMENT or RECORD keeper. For the "GET" operation, AUXFILE creates a fresh segement. "circuit" is the key to a circuit building capability {(p2,getcircuit)} and "sysno" is the Tymnet host number of the circuit {specified as a decimal number}. Many users will have a circuit key in their directory when they are joined to Gnosis. This key is to his or her CMS userid and is in the form of TYMNET.userid. The type parameter (SEGMENT^RECORD) is required on a SEND operation for consistency only, the type of the structure is determined from the key. Segments are of the File Transfer Segment format {(p2,record-file-format), compatible with the bootstrap loader}. If the records in the file are larger than 4091 bytes then the record collection built for type RECORD must be accessed via the OS simulator.

FILENAME FILETYPE FILEMODE and the rest of the file specifications are CMS File specifications and specify the exact CMS file involved in the transfer. "*" is not allowed in the filemode field. Unlike other situations, the FILEMODE must be specified as two characters. A file sent to CMS will replace one that already exists.

The project string is almost always required (by the CMS host) and can only be omitted if the USERID is known to be "disconnected". There is currently no way to specify multiple lines in the project field through the command system.

CAUTION. There is one known way to cause this transfer to "hang up". If the RECFM specification is not correct the CMS host may abort the transfer (such as sending a variable length file with RECFM F). The file transfer mechanism does not recognize this abort and the transfer will stop. Forcing the CMS USERID off breaks the circuit and terminates the transfer.

A second problem that seems to hang the transfer is if a DISK FULL condition occurs while sending a file to CMS.

RETURN CODES - see (p2,auxfail)

There is an extended return code supplied for this command. The extended return code refers to the return code of the process invoked by the auxmangr key, and the return code is the auxmangr return code which can be used to determine which process failed and hence what return codes to look up. For example, "EXTENDED RETURN CODE = 5 RETURN CODE = 7 says that auxmangr return code of 7 indicates an RFRSC error on a get immediate operation. The RFRSC return code of 5 indicates that synchronization between CMS and Gnosis failed probably because the file did not exist as specified on the CMS userid or the userid did not have access to the Gnosis "TOOLS" disk upon which is the AUXFILE module to support the CMS side of the file transfer. See (p2,auxmangr), (p2,getcircuit), (p2,rfrsc) (p2,protc) for descriptions of return codes.

CHECKPOINT
The CHECKPOINT command is use to force a system checkpoint {(p1,checkpoint)} in order to insure recent changes will be around when the system is restarted. It is an interim command and will disappear soon.

RETURN CODES

None

CHGLUDKY ludcontrolkey key [spacebank] [meter]
The controlkey obtained from the ADDLUDKY command is used to change the LUD key. A new spacebank and meter for the circuits may be specified.

"ludcontrolkey" is the control key returned by the ADDLUDKY command

"key" is the new key to be added to the LUD. It replaces the key added by the ADDLUDKY command.

"spacebank" "meter" These keys are used by the receptionist to build circuits. If they are not specified, the directory entries for SPACEBANK and METER will be used.

RETURN CODES

none

CMDFILE keyname
This command interprets a file of commands as if they had been entered from the terminal. Only the command is read from the file, all other input is from the terminal so that asynchronous input will come from the terminal. All commands read from the file are printed at the terminal preceded by "F:" so that they appear like they were entered from the terminal but can be distinguished.

At the end of the command file or after any error reading the command file (including null lines), input will resume from the terminal.

CMDFILE keyname1

keyname1 is a directory name of an entry sequence record keeper. No other structures are allowed.

RETURN CODES
none

COPYKEY keyname1 keyname2
The key found in the directory under the first name will be duplicated in the directory under the second name. Note that if the second name was already in the directory, the key may be replaced. No action is taken on the objects.

RETURN CODES

none

CPUTIME
The CPUTIME used during the current session (actually since the previous LOGOFF command) by all domains which run under the command systems meter is displayed. All objects created via the command system run on this meter, although any second order domains which are created which use the meter provided as part of the womb facilities.

RETURN CODES

none

CREATE filename segmentkey
An entry sequenced record collection is created and given the name "filename". If segmentkey is specified, the segment {which was probably transferred from CMS using the RECEIVE command} is converted into records and loaded into the record collection.

Until a bug in STRCC is fixed this command may not complete if the provided segment is not a segment or is in the wrong format.

RETURN CODES

3 - error writing to record collection

5 - segment record exceeds 4091 bytes

CREATEBS format producer consumer
A byte stream is created and the producer key {(p3,bsp)} is stored in slot producer and the consumer key {(p3,bsc)} in slot consumer.

Format is the format type:

0 for standard record stream

1 for standard byte stream

2 for standard blocked record stream

RETURN CODES
See Gnosis expert

DEBUG domainkey
DDT is a machine language debugging tool. Its use is described in (ddtdoc,).

A DDT is created and installed as the domain keeper of the domain designated by "domainkey". {"Domainkey" may be of the form entrykey.DOMKEY if it is desired to debug the domain whose start key is known as "entrykey" (see LOAD command).} If no operand is specified, a DDT is created for the command system interpreter.

If the DDT command ";t" is given DDT will use the symbol table in the segment whose memory key is in D10 of the domain. If the command "EB;t" is given where "EB" is some upper case EBCDIC string ,then the DDT will retrieve a key from the memory tree that allows it to communicate with the binder product and get the indicated symbol table.

When this DDT is installed you will get a message saying "USE BRANCH c". This means that you may talk to the DDT by switching your terminal to the virtual terminal denoted by branch c. This is done by typing {at any time} escape followed by c and carriage return. To switch back to your command system type escape b return.

If your domain breaks before you explicitly install a DDT on it, a DDT will be created in your behalf anyway. However, in this case you won't necessarily know which branch goes with which domain.

Key 19 of your DDT will be key to the directory of the context where the DEBUG command was issued or the directory where the broken object was built. Typing "0rb;x6;000403c4c4e3" and then "key 19,5,(12)" will result in the key in DDT's slot 12 being placed in the main directory under the name "DDT".

RETURN CODES

See Gnosis expert

DELETE token
The name "token" is deleted from the directory. The "token" may contain dots "." and if it does any directories in the directory tree that become empty will be deleted.

RETURN CODES

1 - name not found in directory

2 - illegal characters in name

3 - nome too long

DIR (see LISTFILE)

DUPLICATE oldkeyname newkeyname

If "oldkeyname" is a record collection, and if "newkeyname" does not yet exist, then a new record collection is made and the data and keys from the old record collection are copied into it.

Similarly, if "oldkeyname" is a file transfer segment, it is copied into a new file transfer segment "newkeyname".

No conversion is possible. It is not possible to overlay data in the second structure.

RETURN CODES

none

EDIT filename
The CMS editor is invoked allowing you to edit the Gnosis data structure "filename". Any Gnosis data structure that is supported by the OS simulator is supported. This version of the CMS editor does not have the TYMSHARE goodies installed. Only the Data in "filename" can be edited. The editor will automatically GET the designated file. The FILE command does an implied PUTFILE.

The directory key EDITOR is used for the edit. If no such key exists then the EDITF key from the womb or SYS.EDITF is used to create an editor. If a particular editor is desired other than the standard one, the user may provide one and put its start key into the directory with the name EDITOR. The calling conventions for the editor are described in (p2,editor).

RETURN CODES

none

ERASE keyname
The key in the directory with the name "keyname" is invoked with order code kt+4. Return codes are ignored. The directory entry is then deleted.

RETURN CODES

none

EXECUTE startkey parameterstring
The program is executed passing whatever characters are in the parameterstring to it. Note that PL/I expects its parameter string to begin with a slash "/" if the parameters are intended for the program itself and not for the PL/I library.

The start key "startkey" was probably generated by the use of the OSFLOAD {(osfload)} command.

The program is given the keys to the current branch of the terminal.

The command system will proceed to use the returned keys as terminal keys. If the returned keys do not behave as terminal keys the command system will acquire new keys to the terminal on another branch.

The paranoid must beware that the executed program acquires the authority of the command system. See (p2,exe) about this problem.

RETURN CODES
If the program returns a nonzero return code, the HEX value will be printed after the command completes execution.

FACTORY
This command builds a factory. The requestor's key is put into the directory. The .keeper is one that will produce a DDT on the Command system switcher. The .program is the code provided by a key you supply.

FACTORY Keyname1 Segment Type [Ordinal] F^S^H0=keyname2 ...F^S^H15=keynameN

"Keyname1" is the directory name by which the factory requestor's key will be known.

"Segment" is the directory name of a binder L-segment factory (LSF) or a file transfer segment containing the .program for the factory. The special string ".fetcher" is recognized and no program is installed; the factory becomes a fetcher factory.

"Type" is a decimal number between 0 - 2**31-1 that becomes the alleged type of the factory

"Ordinal" is a decimal number between 0 - 2**31-1 that becomes the ordinal of the factory (optional, zero assumed)

The starting address of the factory comes from the module {perhaps the assembler's END card}.

"Keyname2" through n are optional keys that are installed in the designated component of the factory with F specifying a factory component and S specifying a sensory component.

Several keys are added to the directory within a subdirectory "keyname1.". These keys are enumerated.
keyname1.SBANK a guarded spacebank used to build the factory

keyname1.METERNODE a node key to the meter used to build the factory

keyname1.METER the meter key used to build the factory

keyname1.GUARD the guard for the bank keyname1.SBANK

keyname1.BUILDER the builder key for the factory

RETURN CODES
none

FILEDEF [&filedefname] operands
The FILEDEF_DEFINE key called filedefname key is invoked, passing the designated parameters. See the full key description {(p2,filedefdef)} for details. If &filedefname is not specified, directory key FILEDEF is used.

A few highlights: The operands are ordered ddname, directory-name, options. Most of the options are familiar, with the exception of FILE (means entry sequence record collection), DIRECTORY (means name sequence record collection) and SEGMENT (a segment in some format), TAPE means a tape, and TERMINAL which means use the terminal support system of the OS simulator (whatever that is).

If &filedefname is specified, the filedef context "filedefname" produced by the NEWFDEF command is used (p3,newfdef), else the default filedef context for this command system is used.

If operands is omitted this is a "filedef define query" operation (a la CMS) and all filedef commands that are active for the context "filedefname" (if present) or the default filedef context are listed with the options that were specified on the FILEDEF command that define the DDNAME.

RETURN CODES

none

FORK Startkey parameterstring
Startkey is invoked as in the EXECUTE command with the following exceptions. The program executes in parallel with the command interpreter. The latter uses a new branch of the terminal. No signal is given when the program returns.

RETURN CODES

none

KC (See KEYCALL)

KEY (See KEYCALL)

KEYCALL

This command executes generalized key calls from the command system.

KEYCALL keyname oc (string,k1,.. kn) (RS,Rk1,... Rkn)

keyname is a token that is resolved in the directory.

oc is a decimal order code in the range 0 - 2**31-1 or the strings KT and KT+n, where n is between 0 and 9.

string is limited to 255 characters and can be specified in several ways. In any of these cases string is translated to upper case and there may be no ","s or ")"s or "="s.

%Ealphabetic data - a character string that is passed as EBCDIC

%Aalphabetic data - a character string that is passed as ASCII

%Xhexidecimal data - a character string that is converted to hex and passed (there must be an even number of characters in the string)

keyname - a token that is resolved in the directory, the data portion of the directory entry is passed (0 - (255-length of last subtoken))

NOTE. Commas can normally be used anywhere as a token delimiter but are required after "string" in order to allow for embedded blanks

k1 through kn are names that are resolved in the directory. The key portion of the entry is passed.

RS specifies the format of the return string.

%E - treat the return string as EBCDIC and type on terminal

%A - treat the return string as ASCII and type on terminal

%X - treat the return string as hexidecimal and type on terminal

keyname - put the returned string in the directory under the given token name as the data portion.

A combination of the above such as %E%Xkeyname, as long as %A does not precede %X or %E and keyname is last.

Rk1 thru Rkn are names under which returned keys are to be placed in the directory.
If these names are already in the directory and the existing key isn't DK(0) then the user is allowed to specify a new name.

Note that the string "()" must be entered even if no parameters are offered on the keycall command if one wishes to receive returned parameters.

RETURN CODES

see the return codes for the key invoked

KEYFORK
This command has the same syntax as the KEYCALL command except that there is a fourth key possible in the calling parameter list, and there is no return parameter list (it is ignored if specified).

KT anykey
You may ask any key in your directory what it alleges to be. (It may not return.) KT will refuse to call a return key and tell you.

RETURN CODES

none

L (See LISTFILE)

LISTFILE token

Listfile lists directory entries based on the token. While there is no relationship between the names listed and "files", the name listfile is used to make CMS users feel more at home. The old directory command has been deleted.

"Token" may contain wild card designators "*" and "?" and dots ".". If no token is specified "*" is assumed. Contrary to some expectations "*" does not list all of the directory. Only first level names are filtered by "*". "*.*" will select second level names. Note that "*.*" and "*.*." select different names. "*.*." is more restrictive in that it requires a trailing dot (the name specifies a directory).

RETURN CODES

1 - not found

2 - name contains illegal characters

3 - name too long

LOAD See OSFLOAD {(osfload)}

LOG

A synonym for LOGOFF

RETURN CODES

none

LOGOFF
The terminal is disconnected from the system. Nothing else is done.

RETURN CODES

none

NEWFDEF filedefname [directory]
A filedef object {(p2,filedef)} with the name "filedefname" is created. The keys "filedefname.FILEDEF" and
"filedefname.FILEDEFQUERY" are installed in the command system directory. If "directory" is specified, the filedef context is restricted to the named directory for its resolution of Gnosis names. Otherwise the filedef has access to the directory of the command system. See (p3,filedef), (p3,osfload).

RETURN CODES: none

OSFACT
This command puts OS programs into factories using the old environment of (p2,old-osfactory). To use the new environment with the binder, just use the FACTORY command.

Like the FACTORY command {(factorycmd)} the .keeper is "VDK" from the current directory. The .program is the code contained in the filetransfer segment. The program is put into a VCSK factory so the OS program need not worry about dynamic storage.

The program must be linkedited on CMS with the GNOFLINK or PLIFLINK exec's. These exec's link in the necessary code {GNOFIBM} to initialize the factory environment.

Section (p2,old-osfactory) describes the environment found by the OS program and the meaning of the ordinal.

OSFACT requestorkey segment type [ordinal] F^S^H0=keyname1 ... F^H^S3=keynameN, F^H^S10=keynameN+1 ... F^H^S15=keynameM

All operands are specified exactly as in the FACTORY command (factorycmd). The components 4 - 9 are those needed to build and maintain the OS environment and are installed by the command system. See (p2,old-osfactory). Only components 0-3 and 10-15 may be specified by this command.

See (p2,old-osfactory) for information on the internal logic for this.

Component 2 is the .program and component 15 is a data key with the first 4 bytes being the starting address of the .program.

Several keys are added to the directory in a subdirectory named "requestorkey.".

requestorkey.SBANK the guarded bank used to build the factory

requestorkey.GUARD the guard for the bank requestorkey.SBANK

requestorkey.METERNODE the node key for the meter used to build the factory

requestorkey.METER the meter key used to build the factory

requestorkey.BUILDER the builder key for the factory

RETURN CODES
none

OSFLOAD requestorkey Startkey akt [arg] [&filedefname]
Requestorkey is an OS factory requestor key {such as that built by the OSFACT command (osfactcmd)}. See (p2,osfacty) and (p2,osfactx) concerning the nature of the requestor key.

Startkey is the resultant key to the OS object.

Akt is the alleged key type by which the loaded object will be known. If the program itself exits directly to the caller, it may respond to KT with a different value.

Arg is a key that may be found in cache slot 10 of the OS program.

If &filedefname is specified, then the filedef context "filedefname" (p3,newfdef) is used to resolve filedefs when this program is run. &filedefname must be the last token of the command line.

The OSFLOAD command produces objects that are compatible with the EXECUTE and FORK commands. The source of these objects is OS factory procedure OSFACT. The use of factories does involve the additional step of the OSFACT command to build the factory but the environment in which the program is put is controlled.

Several keys are put into the directory in a subdirectory called "entrykey.".

entrykey.SBANK the new spacebank that was used to build the object

entrykey.GUARD the guard for the bank entrykey.SBANK

entrykey.METER the new meter used to build the object

entrykey.METERNODE the node key for the new meter entrykey.METER

entrykey.DOMKEY the domain key for the object (only if requestorkey.BUILDER is present in the directory).

entrykey.FILEDEF the OSFD key for the object

RETURN CODES
none

RECEIVE password segmentkey
The file most recently placed upon the CMS-Gnosis transfer disk will be converted into a newly created segment {see Load command} if the password is correct. The password should be an integer < 32767. If the password is not a valid integer, a message is printed and the command is ignored. If the password is not the correct integer, or something else breaks, the return code will be as specified in {(p2,srup)}.

If the file was transfered using the CMS GSEND exec, the key to the newly created segment will be placed in the directory as "segmentname".

If the file was transfered using the multifile transfer MGSEND exec, "segmentname" will be ignored, and a message will be printed giving the CMS file name for each file, followed by a prompt requesting the corresponding Gnosis "segmentname".

RETURN CODES

3 password incorrect

6 out of space

7 disk not ready

8 disk error

RENAME token token
The key with the name of the first token is renamed to the name of the second token. Both tokens may contain dots ".". If any directories become empty while deleting the first token name, they are destroyed. New directories required by the second token will be built.

RETURN CODES

1 - name1 not found

2 - name1 contains illegal characters

3 - name1 is too long

4 - name2 contains illegal characters

5 - name2 is too long

6 - name2 is not unique

START meterkeyname
Start undoes what stop did, and allows domains to resume execution by restoring the CPU resource limit by that saved in slot 14 (only if slot 14 contains a nonzero value).

START and STOP will function for meters created by the command system because these meters have been given a meter keeper (p2,mkeeperc) that saves all restart keys. This meter keeper understands order code 0 to mean restart all domains that have trapped to it.

RETURN CODES

none

STOP meterkeyname
If meterkeyname denotes a node key to a node which is used as a meter, stop will remove all resources from the CPU component of the meter, which effectively halts the execution of all such domains. Note: The LOAD command produces such a key and stores it in the directory under the name "entryname.METERNODE".

The value of the remaining CPU resources is saved in slot 14 of the meter node.

RETURN CODES

none

TYPE keyname
Objects that may be edited (i.e., File transfer segments (p2,record-file-format), Record Collections (p2,rcc)) may be typed at the terminal with the TYPE command. There is no way to stop the TYPE command except to zap the context.

ZAP spacebank
Zap destroys all of the objects built from space serviced by spacebank, and then destroys the spacebank. Keys to the destroyed objects become zero data keys. (Their names will still exist in the directory.)

RETURN CODES

See a Gnosis expert

USER. - a sub-directory which is shared by all contexts of a particular user, and contains the keys representing the authority of the user, independent of any specific context. Depending on actions of the system administrator {(sysadmin)} it may initially contain some of the following:
{arcane}CHECKPOINT - a key to cause a checkpoint to be taken

{arcane}DUMP. - a directory with system dumps

JOURNALIZERNODE - stuff for journalizing. See (p2,journal-node) for details.

PUB. - a name sequence record collection used for inter-user communication.

LUDCONTROL - This is a "MODIFYLUD" key {(p2,modlud)}.

SYS. - a read-only directory of keys available to general users.

{arcane}SYSNODE - the node key to sysnode {(p2,sysnode)}

TYM_username - A circuit building key to tymnet.

WOMBFACIL - a private copy of the primordial womb

CSMxxx.DOMKEY - the domain key of this command system (xxx is the version number).

DIRECTORY - the command systems first level directory (record keeper)

DOMCRE - a unique domain creator.

FILEDEF - a filedef define key which uses the command systems directory

FILEDEF. - a directory containing the FILEDEF domain keys.

FILEDEFQUERY - a filedef query key which uses the command systems directory

METER - the command system meter key.

METERNODE - a node key to the command system (and everything which runs under it) meter

SPACEBANK - a guarded spacebank for this instance of the command system (user).

SWITCHER - a switcher which creates branches for the command system

VDKF - a fetcher factory to the VDK used by the command system. It creates a branch on the current context.

ZAPPER - a zapper key for the command systems terminal