Command Definition Items
Overview
Any command you can execute in Reality must have an item in either the MD of your account or in an alternate verbs file specified in your user profile. The MD and alternate verbs items that define these commands point to the location of the code that performs their function. More details about the processing and use of commands are given in TCL and General User Commands.
Case sensitivity
If keyword case-insensitivity is selected, attribute 1 of a command definition item can be in any combination of upper or lower case. Otherwise, it must be in upper case.
TCL-I Command Definition Items
TCL-I commands do not require a file-name. A TCL-I sentence comprises a TCL-I command followed by a carriage return. There can be optional parameters.
Caution
Never attempt to create your own TCL-I commands or change existing ones in any way.
The attributes of a TCL-I command definition item are detailed below.
| Attribute | Description |
|---|---|
| Item-id | Command name. |
| 001 | Ptag - The first character of attribute 1 is always P. The second character (tag) defines special functions to be performed by Reality software. |
| 002 | Entry Point. Defines the entry point for the command. |
TCL-II Command Definition Items
TCL-II commands require a file-name and an item-id, item-list, or asterisk. A TCL-II sentence begins with a TCL-II command followed in order by a file-name and item-id, item-list (which can be supplied by a list generating command), or asterisk (to specify all items). The sentence ends with a carriage return. There can also be optional parameters.
Caution
Never attempt to create your own TCL-II commands or change existing ones in any way.
The attributes of a TCL-II command definition item are detailed below.
| Attribute | Description |
|---|---|
| Item-id | Command name. |
| 001 | Ptag - The first character of attribute 1 is always P. The second character (tag) defines special functions to be performed by Reality software. |
| 002 | Entry Point. This is always 2 for TCL-II commands. |
| 003 | Secondary Transfer Point. |
| 004 | Tertiary Transfer Point. Attribute 4 is typically null. |
| 005 | Parameter String. This is a string of indicators passed to the processor to specify common execution paths. |
English Command Definition Items
English commands require a file-name. An English sentence begins with an English command generally followed by a file-name and optional clauses that specify item selection and output specifications. The sentence ends with a carriage return. Refer to the English Reference for details.
Caution
Never attempt to create your own English commands or change existing ones in any way.
The attributes of an English command definition item are detailed below.
| Attribute | Description |
|---|---|
| Item-id | Command name. |
| 001 | Ptag - The first character of attribute 1 is always P. The second character (tag) defines special functions to be performed by Reality software. |
| 002 | Entry Point. This usually ends in 35 for English commands, but may have other values. |
| 003 | Secondary Transfer Point. |
| 004 | Tertiary Transfer Point. Attribute 4 is typically null. |
| 005 | Parameter String. This is a string of indicators passed to the processor to specify common execution paths. |
Cataloged DataBasic Program Definition Items
When a DataBasic program is cataloged, Reality creates a command definition item in the MD with the program name as the item-id. A sentence invoking the cataloged program must begin with the item-id as the command and end with a carriage return character (X'0D').
For details about cataloging DataBasic programs, refer to the DataBasic Reference.
Caution
Never change in any way the command definition item of a DataBasic program delivered with the system.
The attributes of a cataloged DataBasic program command definition item are detailed below.
| Attribute | Description |
|---|---|
| Item-id | Command name. |
| 001 | P - There is no tag for cataloged DataBasic programs. |
| 002 | Entry Point. This is always 10B4 for DataBasic commands. |
| 003 | Null. |
| 004 | Null. |
| 005 | Null. |
| 006 | File-name of executable code. |
| 007 | Name of executable object. |
Attributes 6 and 7 allow the executable to be in any file and with any name.
Note
The system also understands the form of cataloged program definition item used on RealityX 4.0 and earlier, in which attribute 5 contains account-name {item-id} (where account-name is the account from which the program was cataloged and item-id identifies the item that contained the source of the program when it was cataloged). In this case, attributes 6 and 7 are null.
Proc Definition Items
In order that a Proc can be executed by a command at TCL, the name used to execute it must be an item-id in the MD. A sentence invoking the Proc as a command must begin with the item-id followed by a carriage return.
Although all the code for a Proc can be held in the MD item, this is not recommended practice. Instead, a separate file should be created to hold all Procs used in an account, then for each Proc, a definition item should be place in the MD which transfers control to the main Proc in the file.
Placing Proc code directly in the MD has a markedly negative effect on the time it takes to execute commands. It can also cause problems if changes are made to the MD while the Proc is executing.
The attributes of a Proc definition item are detailed below.
| Attribute | Description |
|---|---|
| Item-id | Name of the Proc. |
| 001 | PQ{N} - PQ specifies Proc; PQN specifies New Proc. |
| 002 |
(file-name {item-id}) The instruction in attribute 2 defines a transfer to the Proc code in item item-id in file file-name. If item-id is not specified, the system uses the item-id of the executing Proc. In Procs delivered with the system, file-name is typically PROCLIB or SYSPROG-PL. |
For details about the Proc language, refer to the Proc Reference.
TCL Macros
TCL macros allow users to perform simple batch tasks formed by combining TCL commands. Four types are available: N- and M-types, S-type sentences and TCL menus.
You can create TCL macros with any of the Reality editors, or by using the .C TCL Stacker command to save commands from the stack as an S-type sentence.
N- and M-type
Both these types of macro execute a sequence of TCL commands. M-type macros differ from N-type in that they present each command to the user for editing before execution.
The format of an N- or M-type macro is as follows:
| Attribute | Description |
|---|---|
| Item-id | Macro name. |
| 1 |
First character: N or M as appropriate Provided the second characters is a space, any subsequent text is ignored; it can therefore contain a comment if required. |
| 2+ |
Each subsequent attribute must contain a single TCL or macro command. Responses to prompts for input generated by the command can be provided, separated by value marks. Empty lines and those beginning with asterisks (*) are ignored; the latter can therefore be used for comments. The macro terminates at the end of the item. |
S-type sentence
These are similar to N-type macros, but provide additional capabilities. In their simplest form, they are identical to N-type macros. Various item formats are supported, for compatibility with other MultiValue systems.
The format of an S-type sentence is as follows:
| Attribute | Description |
|---|---|
| Item-id | Macro name. |
| 1 |
First character: S Provided the second characters is a space, any subsequent text is ignored; it can therefore contain a comment if required. |
| 2+ |
Each subsequent attribute must contain a single TCL or macro command. Responses to prompts for input generated by the command can be supplied, with value marks as separators. Empty lines and those beginning with asterisks (*) are ignored; the latter can therefore be used for comments. The macro terminates at the end of the item. Note Attribute 2 cannot be an unsigned integer, to prevent confusion with an S-type data definition. If necessary, attribute 2 can be empty or an asterisk. For compatibility with other MultiValue systems, responses to prompts can also be separated by two left chevrons ("<<"). In this case, each response (and its chevrons) can be in a separate attribute. |
Note
You can use the .C TCL Stacker command to create S-type sentences.
TCL Menu
This type of macro presents a list of options to the user and then runs the TCL command associated with the selected option.
The format of a TCL menu is as follows:
| Attribute | Description |
|---|---|
| Item-id | Macro name. |
| 1 |
First two characters: ME Provided the third characters is a space, any subsequent text is ignored; it can therefore contain a comment if required. |
| 2 | The title of the menu. This is displayed centred in reverse video above the menu. |
| 3+ |
Each subsequent attribute must contain a single menu item containing the following fields, separated by value marks.
Empty lines are ignored. The menu terminates at the end of the item. |
Command Synonym Definition Items
Caution
Never change an attribute of a command definition item or copy a command definition item to another item to create a synonym command. To create a synonym command you must create a command synonym definition item, described below.
A command synonym definition item specifies an alternative name which can be entered at TCL to execute a command. The command to be executed is specified in attribute 2. The alternative name, entered at TCL, is the item-id of the item. The item format is detailed below.
| Attribute | Description |
|---|---|
| Item-id | Command synonym name. |
| 001 | V |
| 002 | Command name defined in the MD. |
Connective, Modifier, and Relational Operators
Any connective, modifier, or relational operator you can execute in an English sentence must have an entry in your account's MD. The MD items that define these, contain characters that specify for the English processor the type of operation it is to perform.
Caution
Never delete or change the English connectives, modifiers, or relational operators delivered with the system.
The definition item for a connective, modifier or relational operator is detailed below.
| Attribute | Description |
|---|---|
| Item-id | Connective, modifier, or relational operator name. |
| 001 | Ctag - The first character of attribute 1 is always C. The second character (tag) defines the nature of the connective, modifier, or relational operator to the English processor. |
You can create a synonym for a connective, modifier, or relational operator by copying the existing one to an item with the item-id of your choice. The item-id must be unique in the MD.