VOC Catalog Types (TB#21) (Functions/Subroutines/Programs)
Created at 12 AUG 1996 03:21PM
VOC Catalog Types
Each command executable from TCL must have an entry in the VOC file. The VOC entry contains information that tells TCL (RTP18) how to execute that command.
Although it is not frequently apparent (or important) when the command is executed, there are different types of VOC commands. Some TCL commands execute cataloged R/BASIC commands, others are TCL batch items, and still others execute DOS-level commands.
VOC Catalog Entries
The first attribute of each entry in the VOC file is the type designator. For example, a cataloged R/BASIC program will have a four-attribute entry in the VOC file with a structure similar to this:
Field Contents
1 RBASIC (literal word type designator)
2 (blank)
3 cataloged file name (e.g. BP)
4 cataloged program name (e.g. MYPROG)
Examination of the VOC file reveals that there are 14 possible types of VOC entries, subdivided into five generic categories. The full list, and a brief explanation of each one, is presented in Figure 1. Details about the layout of each type appear below.
VOC Catalog type layouts
There are five generic types of pointers that are maintained in the VOC file. These include pointers for Qfiles (file name synonyms), volumes, DOS commands, TCL batch items, and verbs (executable R/BASIC routines).
Qfile pointer
Qfile pointers identify synonymous names for existing files. The name of the VOC entry is the synonym; the VOC file entry identifies the file to which the synonymous name points.
Note: If the file QFILES exists, Qfile pointers are stored there. In the absence of a QFILES file, entries are stored in the VOC file.
Layout:
Field Contents
Key file name synonym
1 QFILE (literal word)
2 account of source file
3 "real" name of source file
Volume pointer
Volume pointers identify the location and filing system of a group of files. (Volume pointers are not needed if the filing system for a group of files is RPT57 —- Linear Hash. However, the use of volume pointers for all filec types is a good practice.)
For example, if a group of files is to be maintained on drive C:\AREV\DATA and if the files are to be ROS files, a volume pointer must be created to indicate the location and filing system of the files. The group of files can then be attached using the volume pointer name.
Layout:
Field Contents
Key volume name
1 VOLUME (literal word)
2 filing system program name (example: RTP59)
3 location (example: DOS path)
DOS command pointer
Any DOS command can be cataloged by creating a VOC entry for it. The DOS command can then be executed from TCL. Command line parameters can be passed as if passed from the DOS command line.
Layout:
Field Contents
Key DOS Name
1 PCPERFORM (or) PCEXECUTE (or) SUSPEND
Note that there is no additional information required in the VOC entry only the first field. The DOS command to execute is the word typed in at TCL.
PCPERFORM and PCEXECUTE use the PC command to shell out to DOS before executing the command. SUSPEND uses the SUSPEND command to shell to DOS.
TCL batch item pointer TCL batch items allow the execution of a series of TCL commands using a single command at TCL.
Layout:
Field Contents
Key Batch command name
1 TCL (literal word)
2 TCL command 1
3 TCL command 2
4 TCL command 3 (etc.)
Verb pointer Verb pointers execute object code routines (R/BASIC, C, or assembly language). The pointer entry identifies the location and name of the object code to be executed.
Layout:
Field Contents
Key Verb or command name
1 Verb catalog type (see below)
2 (blank)
3 file name
4 program name
The program name in field four identifies the object code name. However, the entry in field four does not have the dollar sign ($) in front, as the object code record key does.
The program name in field four does not have to have the same name as the VOC entry itself. For example, the VOC entry POST.INVOICES might point to a program actually named INV201. In that case, field four of the VOC entry would simply contain INV201.
Using VOC Catalog Types
Developers normally use only two of the types – TCL and RBASIC. The former type is created by direct editing of the VOC file, or by use of the [Shift-F1] key from TCL. The latter type is created by the CATALOG verb. The remaining types appear in the VOC file to flag system commands such as ATTACH, GET-LIST, BLIST, MAKEFILE, RECORDCOPY, LIST, and SELECT.
Using additional types, developers can take advantage of capabilities available through TCL. These capabilities include:
_ parsing for options such as P and B
_ creating a select list within a program and retaining it upon return to TCL
_ creating a select list out of keys passed in the command line
_ calling a window automatically to prompt for portions of the command
Developers should note that most of these capabilities are mutually exclusive. For example, it is not possible to have a single VOC type that parses for options, uses a window, and retains a select list.
Parsing for Options
The VOC types RBASIC and VERB1 parse the TCL commands for options in parentheses, and act accordingly. This saves the programmer the effort of having to code logic to test for these options.
The options that can be passed to RBASIC and VERB1 types are:
Option Meaning
P Send output to printer
B Save video image, restore after termination
In addition, the RBASIC type will look for the (D) option, and call the debugger immediately if this option is set.
Creating and Retaining a Select List
For most TCL commands, any select list active while the program is executing is cleared upon return to TCL. However, the type VERB1F will retain any active select list. This type is used for the system commands such as GETLIST and FILTER that are used to activate select lists.
A programmer can thus create and activate a select list in an R/BASIC program, and then simply return to TCL. Because the select list will not be cleared, it can be used by the next TCL command.
Creating a Select List out of Passed Keys
The VOC types VERB2 and VERB2T can be used if a list of keys is to be passed to a command. This is the case, for example, in such system commands as BLIST, RECORDCOPY, and EDIT. The type VERB2T differs from VERB2 in that it expects (and prompts for) a TO: clause.
These VOC types accept a list of keys in the command line (or in a window see below) and turn the key list into a select list before calling the actual cataloged program. For example, if MYPROG has been cataloged as a type VERB2, the following TCL command will result in a three-element select list:
MYPROG INVOICE 100 101 102
Note that the word INVOICE does not become a part of the key list. The second position of the TCL command is always assumed to be a file name.
A special case is the reserved character "*". If this character is passed in place of a key list, a simple R/BASIC SELECT is executed before the cataloged program is called, resulting in a latent select list.
In this case, the R/BASIC SELECT will be executed specifically against the file passed as the second word of the command. In the example above, the file is INVOICE. (In contrast, if an explicit key list is passed in the command line, a generic, non-file-specific select list is generated.) Because the select list is file-bound if the keylist is *, the cataloged program should extract the file name from the command line. Logic to do this is illustrated in Figure 2.
Calling a Window
In addition to accepting key lists, the VERB2 and VERB2T types are designed to present a window front-end to the user. If a VERB2 or VERB2T cataloged program is called with missing, incomplete, or incorrect parameters in the command line, TCL will display a window to collect these parameters.
An example is EDIT. If EDIT is called with no parameters, a window labelled Edit displays. The user can fill the parameters in at the prompts, taking advantage of [F1] and [F2] functions for assistance. When the [F9] key is pressed, the TCL command is constructed from elements in the window and executed.
To support this capability, the windows VERB2 and VERB2T are available in the COMMANDS file. These windows can be modified, but since the windows are shared by all VERB2 and VERB2T commands, developers should first examine the effect of changes on all applicable system commands. To find a list of VERB2 commands, a simple R/LIST sentence can be executed:
LIST VOC WITH F1 VERB2
Figure 1
Type Meaning
QFILE Indicates Qfile
VOLUME Indicates volume pointer
PCPERFORM PCs, executes DOS-level command
PCEXECUTE PCs, executes DOS-level command
SUSPEND Suspends, executes DOS-level command
TCL Indicates batch command
RBASIC Tests for (PDB) options, calls program*
VERB1 Tests for (PB) options, calls program*
VERB1F Tests for (PB) options, calls program, preserves select list upon return*
VERB2 Creates select list, calls program or window*
VERB2T Creates select list, calls program or window (includes TO:)*
VERB3 Calls program; does not check for options
VERB4 Calls R/LIST processor
VERB4S Adds BY @ID to command, calls R/LIST processor
* details provided in text
Figure 2
FILE.NAME = FIELD( @SENTENCE,' ', 2 )
OPEN FILE.NAME TO FILE THEN …