MultiValue Trilogy: Commands

This set of SOFACards gives an introduction to commands for MultiValue or Pick® platforms. Use these cards to introduce technical professionals serving as managers, marketing professionals, students, or developers to the MultiValue server environment.

There are multiple flavors of MultiValue, at times using different vocabularies. Two variations are those designated in these cards as R83 ("pure Pick") and PI (Prime Information and "Pick-like" systems). The author's bias toward the PI, including UniData�, environment will be evident as that is the origin of the experience represented here. It is likely that not all statements are 100% accurate for all MultiValue flavors, so please refer to your vendor documentation for development details.

LIST

This is the verb used for native queries to MultiValue databases.

The LIST statement provides the user with the query syntax for extracting data from a MultiValue database and formatting the output. It corresponds to the SQL SELECT statement. As in SQL-99, it retrieves data from multivalues (parent and child tables) without need for specifying a JOIN. It functions on only one file at a time. However, data from other files may be retrieved in the LIST statement through virtual fields in the form of custom I-descriptors (PI) or correlatives (R83).
LIST CLIENTS WITH PURCHASE_ORDERS
WITH PO_DATE > '28AUG02' AND NO SHIP_DATE
CLIENT_NAME PO_NUMBER PO_DATE

VOC: Vocabulary File

PI VOC = R83 MD

With one of these per account, it is the MultiValue master dictionary

If you can type it in as the name of a command at the command prompt, then it is defined in the VOC file for the account. VOC entries come in many types, including Files, Verbs, Programs, and Paragraphs. If you can LIST it with a query statement, then it is a file with a corresponding record in the VOC file. This master dictionary is extended by defining new vocabulary in a number of ways and can also be shrunk for security purposes. For example, it could include only those vocabulary items useful or permitted for a particular group of users. In fact, the VOC file is often the means of implementing MultiValue database security.

MD: Master Dictionary

R83 MD = PI VOC

With one of these per account, it is the MultiValue vocabulary file.

If you can type it in as the name of a command at the command prompt, then it is defined in the MD for the account. MD items come in many types. Depending on the flavor of MV system, possible items include Files, Verbs, Programs, Procs, Menus, Macros, or Paragraphs. This master dictionary is extended by defining new vocabulary in a number of ways and can also be shrunk for security purposes. For example, it could include only those vocabulary items useful or permitted for a particular group of users. In fact, the MD is often the means of implementing MultiValue database security.

Verb

Verbs are commands, and they are defined in the VOC or MD.

Verbs are invoked (executed) at the system command prompt. Each account has a set of verbs, such as CREATE-FILE or LIST. Many verbs accept arguments or parameters. It is common for the first parameter of a verb to be a filename. A second parameter could be a record name, for example. Check vendor documentation for the exact syntax and options for each verb.
R83 >LISTVERBS
PI :SORT VOC WITH F1 LIKE V... ID.SUP @ID FMT "30T"
or :COUNT VOC WITH F1 LIKE V...
242 records counted.

SELECT

Activates a qualified list of items to be used for further processing.

This SELECT statement is NOT the SQL SELECT statement. It often retrieves only the @ID or item-id from the qualified records or items in a file. When there is an active result-set from the SELECT command, relevant verbs will operate only on the subset of a file corresponding to the active list. In a SELECT statement, only the rows of data are narrowed down, whereas, the LIST statement can also specify columns.
:SELECT CLIENTS WITH PURCHASE_ORDERS
WITH PO_DATE > '10SEP02' AND NO SHIP_DATE
130 records selected to list 0.
>LIST CLIENTS CLIENT_NAME PO_NUMBER PO_DATE

SAVE-LIST

Use this verb to save a list of values after a SELECT command.

Since the SELECT verb genie grants only one wish (command) when a SELECT statement is active before the results of the SELECT disappear, smart Alladins often make that one wish a SAVE-LIST command (or SAVE.LIST for UniData�, for example). Once a list has been saved with a name using this command, it can be retrieved forever thereafter using the GET-LIST command. Make this list active again to process records corresponding to these selected, saved, and retrieved values in the same order as specified in the SELECT command, accessing the current data values from those records.
:SELECT SOFACARDS WITH NAME LIKE "...BASIC..."
:SAVE-LIST MYLIST

GET-LIST

Use this verb to turn a SAVEDLIST into an active SELECT list.

So much more delightful than SQL JOINS, after a MultiValue SELECT statement is executed, the resulting list of values may be permanently stored in a record called a "savedlist" and then retrieved again using this verb. R83 uses GET-LIST, while PI uses either GET.LIST (e.g. UniData�) or GET-LIST. Once retrieved, it becomes an active select list and the next verb issued on a file will restrict the processing of the file to only those records or items corresponding to the active list.
:SELECT SOFACARDS WITH NAME LIKE "...BASIC..."
:SAVE-LIST MYLIST
:GET-LIST MYLIST
:LIST SOFACARDS CARD_DESCRIPTION

BASIC

Compile DataBASIC programs before you catalog and run them.

Whatever flavor of DataBASIC is used in your MultiValue system, programs will be written using an editor, then stored as records or items in a file (PI requires the file to be a directory). Compile programs using the BASIC command. The result will be BASIC object code or p-code to be executed by the BASIC runtime component of the MV Virtual Machine (typically). The object code will be named by the compiler, e.g. _MYPROGRAM. Different flavors of Pick� store the object code in different places, some permitting the developer to specify a file.
:BASIC BP_SOURCE MYPROGRAM
Compiling Unibasic: BP_SOURCE\MYPROGRAM in mode 'u'.

CATALOG

Catalog programs after compiling to turn program name into a verb

R83 simply makes a verb out of the name of the cataloged program, placing it in the MD, with some variations in PI. For example, UniData� requires the parameter "DIRECT" for the same result or it will also place a copy of the object code in a system level catalog space (e.g. UNIX file $UDTHOME/sys/CTLG) or locally in a file in that account (CTLG). When running a program, the object code is loaded into memory for that user. Run a program using the program name as a verb after cataloging it.
:BASIC BP_SOURCE MYPROGRAM
:CATALOG BP_SOURCE MYPROGRAM
:MYPROGRAM

ED

Be it ever so humble -- AE, ED, and EDIT are all line editors.

For all you youngsters accustomed to word processors, GUI interfaces, and clicky-clicky input, some of us felt just as productive with a line editor, entering commands to change text. Screen editors, such as vi and emacs came later, but many a program and even books were written with line editors (using languages like RUNOFF or Waterloo SCRIPT). While a line editor is an admittedly primitive word processor, one is packaged with most MultiValue systems for modifying programs and data files, functioning somewhat like the DOS "edlin" line editor. Get to know your editor in case screen editors and client/server GUI tools are all missing or require configuration you would prefer to defer.

TCL: Terminal Command Language

R83 TCL = R83 or PI "Command Prompt" = PI "Colon Prompt"

Along with the query language commands are other commands for running programs, creating files, and anything else a system administrator, DBA, or programmer might want to do to interact with their MultiValue environment. Whatever indicates that you are "in" your MultiValue environment, such as the > or : prompt characters, when you see it, you can enter any system command. This includes all verbs in the MD or VOC file. Paragraphs and programs may also be executed -- they are custom extensions to the vocabulary of the system.
>LIST MD WITH *A1 EQ "[V]"
>LISTVERBS

: Colon Prompt

PI Colon Prompt = Command Prompt = UniData� ECL = R83 TCL

"At the colon prompt, type ... " is commonly spoken in PI shops, while others might say "At the TCL prompt, type ... ". When you are at the command prompt, you are "in" the MultiValue environment. Today the colon prompt is shielded from most users of MultiValue systems, given GUI interfaces to any necessary commands and point and click query tools. But the colon prompt is the DBA or MultiValue administrator's friend. Sure we can slap a GUI on it too, but for optimum speed and control, seasoned developers often prefer to type away at the colon prompt, requiring no client software other than a telnet session (or not even a client computer if you connect a dumb terminal to your server!)

PA: Paragraph

Interpreted program written in the system command language.

Rather than typing a set of system commands repeatedly, such as a LIST statement for retrieving and formatting data, save the commands in a paragraph. Not all flavors of MultiValue include "PA" entries in the VOC or MD, but those that do permit lists of commands to be turned into interpreted programs. These paragraphs may also include simple conditional logic and input variables. Whatever you name any paragraph in the VOC or MD becomes a new vocabulary item. Use an editor to create a paragraph, save it as a record in the MD or VOC file, and execute the PA by typing its name at the command prompt.
:LIST-SOFACARDS-ALPHABETICALLY

PROC: Procedure

R83 PROC is typically replaced by paragraphs or DataBASIC in PI

Procedural scripting language, like JCL, often found in legacy code

Prior to DataBASIC permitting TCL, MV Query, or system commands to be executed from within a program, a separate PROC language was used to bridge BASIC and QUERY, serving as a Job Control Language (JCL) for Pick�. If you are writing new software, except in extreme circumstances where company standards require it, you should not use PROC at all. The pointer to the PROC in the master dictionary has PQ or PQN on line 1. I've never really seen a PROC and never hope to see one (did my time with JCL //PARM=('CIRCA="1980"')). Refer to vendor doc or members.aol.com/_ht_a/mbtpublish/index.html

DataBASIC

DataBASIC as developed by Ken Simms is far beyond BASIC.

Based on Dartmouth BASIC with influences from other languages, this powerful 3GL, greatly enhanced for data and string handling, is found in all MultiValue installations. It is sometimes referred to as Pick� BASIC, and many implementations brand it with a name. DataBASIC is as much like the Gates/Allen version of BASIC, also developed in the mid-1970's, as Grandma's apple pie is like McDonald's. It has held up as a 3GL, typically compiled to P-code and run in the MultiValue Virtual Machine. Alternatives to DataBASIC include object languages now too. For Java"! jdbc GOTO java.sun.com. For an excellent online resource on DataBASIC, see jes.com/pb/index.html

HELP

Online help is available for most MultiValue systems.

While most MultiValue databases include online help, the way you invoke help varies greatly from platform to platform, so consult the documentation from your vendor. For example, the UniData� database has a HELP command that can be entered at the command prompt, functioning much like the UNIX "man" command, while other MultiValue environments might respond to "?" as a command. At the prompt in UniData, type HELP UNIQUERY or HELP LIST. The "HELP" command is typically not available in newer versions of the R83 branch. Modern database administration tools for some MV flavors provide Help through a more contemporary Menu bar Help command, as one would expect.

SPOOL: Simultaneous Peripheral Operations On Line

PI SPOOL has no equivalent in classic R83.

Acronym originated at IBM in the 60's. To SPOOL is to PRINT.

Output options typically include SPOOLing to a printer or the screen. The SPOOLER environment will pass printed materials to the printer, one report at a time. For those raised on PCs, typing a SPOOL command is like the more obvious Windows� applications' File | Print commands. The spooler and related commands were often primary tools of data processing operators in days of yore.
:SPOOL VOC SOFACARDS -T
F
SOFACARDS
D_SOFACARDS

Wahka Wahka: <<Input prompt and variable>>

PI "Wahka Wahka" is written as << >> sometimes spoken "Norkie Norkie"

The tag is the variable with this Paragraph and I-desc input syntax

While DataBASIC programs use a more traditional approach to data input, paragraphs and I-descriptors allow for variables between paired wahka wahkas, often gestured when spoken. If the variable has not yet been assigned, the paragraph will prompt the user for a value using the words between the < < and > > as the prompt to the user, as well as, the non-standard variable name. Speaking of non-standard, putting variables in comments executes them! We like << >> none-the-less (and you know how to read this sentence now, right?).
LIST FRIENDS WITH GENDER = << M to list Males, F for Females: >>

MV Query

Older, similar, yet more delightful than SQL to use, it isn't standard.

Where are all the MultiValue Query books in your local bookstore? What would we even name such a book? Each vendor implements their MV system with a different name for this language (e.g. ENGLISH, ACCESS, AQL, R/LIST, UniQuery, Retrieve, jQL) and none name it "MV Query". There are features of MV that make it SQL-99 and XML compatible in a way that SQL-92 customers would envy, if they only knew. Could we take the best of SQL-99, XQuery, and MV Query and drive standards for query tools that would work for MultiValue users too?
LIST SOFACARDS WITH PACK_CODE = "MVC" BY CARD_NAME
In SQL this MV Query statement would be
SELECT ID FROM SOFACARDS WHERE PACK_CODE = "MVC"
ORDER BY CARD_NAME;

MV SQL

SQL extended for the MV data model for use with odbc and jdbc.

Unlike MV Query, MV SQL has been implemented by each MultiValue vendor differently. The MV data model differs from standard SQL databases, so there are some challenges when deploying SQL against MV systems. Along with the obvious difference that SQL-92 and ODBC do not support multivalues, there are other seemingly small issues like MV field and file names permitting dots in them, SQL and MV databases handling NULLs differently, MV databases storing untyped and variable length data, etc. These details have been known to prompt expletives from MV SQL developers. But SQL is an industry standard and it works with office software, pleasing end-users, once it is set up for their use.

MultiValue Branches

R83, µData, and PI

These cards use the terms R83, µData, and PI to identify three not-entirely-distinct streams of development of the MultiValue platform. The MultiValue Family Tree diagram, available as a free pdf from store.tincat-group.com, provides a corresponding visual. These terms are used at times in the cards as shorthand identifiers for the three interwoven but separate branches of MultiValue.

In the late 70? s, the Pr1me Information (PI) stream started, emulating functionality roughly equivalent to Microdata? s Reality 3.x product (µData), which was roughly equivalent to Pick® R77. After that (e.g. R83), the streams diverged. Pick historians indicate that R80 is the software version that was marketed as R83, but the marketing term serves our purposes in these cards none-the-less.

Terms related to MV data and commands are identified with the two primary flavors -- R83 and PI -- with µData typically aligned with the R83 camp.

SOFACards MultiValue Commands Pack

Many people and web sites were consulted in the development of these cards. Special thanks to the following people whose help was invaluable and whose years of experience in the MultiValue world total over 80:

Dave Weaver for prompt responses of encouragement when I needed it and excellent proof-reading skills in both form and content.
Mark Pick for sharing stories and sending the thumbs up signals.
Jon Sisk for knowing so much and coming to my aid in the 11th hour, plus his detailed publications that aided my research.
Virginia VanAndel for "doing lunch" and passing along helpful intuitive reactions as well as knowledge from her vast experience.