MultiValue Commands
This chapter provides an alphabetical listing of the command line commands supported by the Caché MultiValue Shell. In MultiValue database systems, these commands are also known as “verbs”. Several of these commands have an alternate name that includes a .VERB suffix. These suffix forms are not listed here.
Most command names that contain punctuation exist in two variant forms: the hyphen form and the dot form. For example, CREATE-ACCOUNT and CREATE.ACCOUNT. InterSystems supports these two forms for compatibility with different vendor versions of MultiValue code. In most cases, these two forms are synonymous. When this is the case, only one of the forms is listed in this chapter. The most notable exception is SP-EDIT and SP.EDIT, which provide different functionality.
Command names, command name keywords, letter code options, and many command arguments are not case-sensitive. Account names and item ID values are case-sensitive.
Letter code options are provided for some command line commands. These letter codes are always optional. Some commands can specify more than one letter code option. Multiple letter codes can be specified in any order. A letter code, or series of letter codes, is preceded by an open parenthesis; the closing parenthesis is not required. The letter codes must be the final item in the command syntax; keyword options, such as DET-SUPP, must appear before the letter codes.
Some MultiValue flavors (D3, jBASE, and UniVerse) permit letter code options enclosed in parentheses before the final item in the command syntax (for example, LIST VOC (P) 'BASIC'). Caché MultiValue emulation of these flavors does not support this syntax; letter codes options must be the final item in the command syntax.
In most cases, only one MultiValue command can be specified on a MVShell command line. You can, however, specify multiple ; commands on the same command line.
# (pound sign)
The # command causes the statement following it to be interpreted as an ObjectScript command.
# commandline
A ObjectScript command line can consist of one or more ObjectScript statements, separated by blank spaces. This ObjectScript command line is immediately executed and the results returned to the MultiValue prompt at the Terminal.
The # must be separated with or one or more spaces from the following ObjectScript command line.
If commandline changes the current namespace (for example, by issuing a ZNSPACE command), the Caché MultiValue Shell restores the initial namespace upon exiting ObjectScript.
The # should not be followed by the ObjectScript MV MultiValue Shell invocation command. Nested MultiValue Shell invocations may cause unexpected problems.
The following is an example of the # command:
USER:# SET x="Hello World!" WRITE !,x
The #, [, and COS commands are synonyms.
See Also: COS
; (semicolon)
The ; command causes the statement following it on the command line to be interpreted as an MVBasic statement.
; basicstatement
This MVBasic statement is immediately executed and the results returned to the terminal.
The ; can be immediately followed by an MVBasic statement, or one or more spaces can be placed between them. Unlike most MultiValue Shell commands, you can specify multiple ; commands on the same command line. Each MVBasic statement requires its own ; command.
Thus, the following is a valid use of the ; command:
USER: ; PRINT "hello" ;PRINT "world"
You can issue the ; command either from the MultiValue Shell prompt, as shown above, or from the MultiValue debug prompt following an MVBasic DEBUG statement, as in the following example:
USER:;myvar="ABC"
USER:;DEBUG
<BREAK>+1^MVBASIC1048.mvi
Source Id: File: Line:0
USER 7d1>;CRT "my variable",myvar
my variable ABC
USER 7d1>
[ (left square bracket)
The [ command causes the statement following it to be interpreted as an ObjectScript command.
[ commandline
A ObjectScript command line can consist of one or more ObjectScript statements, separated by blank spaces. This ObjectScript command line is immediately executed and the results returned to the MultiValue prompt at the Terminal.
The [ can be immediately followed by an ObjectScript command line, or one or more spaces can be placed between them.
If commandline changes the current namespace (for example, by issuing a ZNSPACE command), the Caché MultiValue Shell restores the initial namespace upon exiting ObjectScript.
The [ should not be followed by the ObjectScript MV MultiValue Shell invocation command. Nested MultiValue Shell invocations may cause unexpected problems.
The following is an example of the [ command:
USER:[ SET x="Hello World!" WRITE !,x
The [, #, and COS commands are synonyms.
See Also: COS
<< ... >> (inline prompting)
The << . . . >> command causes the Caché MultiValue Shell to prompt for an input value.
<<[code,]prompt[,patcode]>>
The prompt is a text prompt that requests a user input value. It can include blanks spaces and any character except the comma.
The optional code is separated from the prompt by a comma. You can specify multiple comma-separated code values. The following code values are supported:
A | Prompt even when prompt was previously issued. |
Cn | Uses the nth word on the command line as an argument in an inline prompt. This option allows the user to enter responses to inline prompts at TCL on the same line following the paragraph name. |
F(filename,record[,att.num, value.num,subvalue.num] | Retrieves input from record in filename, and optionally from att.num, value.num, and subvalue.num. Prompt text is optional. |
In | Uses the nth word on the command line as an argument in an inline prompt. This is the same as Cn when n is supplied. Else, prompts for n if n is not specified. |
R | Prompts repeatedly for multiple values. Prompt repeats until the user responds to the prompt with the Enter key. R(text) does the same thing, but inserts text between the user input values. |
@(BELL) | Ring the bell. |
@(CLR) | Clear the screen. |
@(TOF) | Move cursor to top of form. |
@(col,row) | Move cursor to specified column and row. Rows and columns are counted from 0. |
The optional patcode can take two kinds of values:
-
A patcode without parentheses matches the input value with a pattern match code. For example 6A requires that the input value consist of 6 alphabetic characters. If the input value does not match the patcode, an error message is displayed and the user is prompted again until a valid input (or no input) is specified. The available patcode pattern match values are listed in the MATCH pattern matching operator reference page in the Caché MVBasic Reference.
-
A patcode with parentheses matches the input value with an ICONV conversion type code. For example, (D) requires that the input value be a valid date, such as 2/28/2009 or 2009–02–28. The input value is validated, but not converted. If the input value does not pass patcode validation, an error message is displayed and the user is prompted again until a valid input (or no input) is specified. The available patcode conversion validation values are listed in the ICONV function reference page in the Caché MVBasic Reference.
Inline prompting can be used by itself or within another MV command or MVBasic statement. For example:
USER:<<input a command>>
input a command=
USER:SLEEP <<seconds>>
seconds=
The user input value can be a literal, or the name of a defined variable.
In the following MVBasic example, several << ... >> prompts are used:
USER:;PRINT "The quick <<color>> <<animal>> jumped over the <<adjective>> dog."
color=brown
animal=fox
adjective=lazy
The quick brown fox jumped over the lazy dog.
Note that a prompt value is requested once but can be used multiple times:
USER:;PRINT "The quick brown <<animal>> jumped over the lazy <<animal>>."
animal=fox
The quick brown fox jumped over the lazy fox.
To avoid this reuse of a prompt value, use the code value of A. This forces prompting of a previously defined prompt:
USER:;PRINT "A <<flower>> is a <<flower>> is a <<A,flower>>."
flower=rose
flower=tulip
A rose is a rose is a tulip.
See Also: CLEARPROMPTS
Ctrl-X
The Ctrl-X (Ctrl key + “X”) command clears the current command line, resetting the cursor to column 1. The letter X can be uppercase or lowercase.
ABORT
The ABORT command terminates the current process and returns to either the MV Shell or the EXECUTE command that invoked the process.
ABORT (expr (, expr) )
ABORT runs the ON.ABORT paragraph, if present.
ASSIGN
The ASSIGN command assigns an I/O configuration setting. The following assignments are supported:
ASSIGN form-queue TO LPTR n [-WAIT]
Assigns a form queue spool device to a LPTR device. The –WAIT keyword is a no-op. The form-queue can be specified either by name or by number. The default form queue has the name STANDARD, and a form queue number of 0. It can be specified as “STANDARD”, “0”, “F0”, “FN0”, or “FQ0”. The n device number variable can take an integer value between 0 and 255 (inclusive).
ASSIGN n TO SYSTEM(5)
Assigns a page number n for page headers and footers. The page number displayed with a HEADING is n-1; the next time HEADING is executed, the page number increments to n as the current page number. For further information, refer to the SYSTEM function in Caché MVBasic Reference.
ASSIGN termname TO SYSTEM(7)
Assigns a terminal type termname to the current process. For further information, refer to the CHOOSE.TERM command in this manual, and the SYSTEM function in Caché MVBasic Reference.
See Also: UNASSIGN
ATTACH.ACCOUNTS
The ATTACH.ACCOUNTS command searches all existing namespaces for MultiValue accounts and records them in the table of MV accounts.
ATTACH.ACCOUNTS
Specifying ATTACH.ACCOUNTS does not overwrite any existing MultiValue account information; it only adds account information for accounts that have not yet been recorded. It is run to make accounts copied or moved from a different system or Caché instance visible in the SYSTEM file. For details on the relationship between accounts and namespaces, and the naming conventions used for each, refer to “MV Accounts and Caché Namespaces” in Operational Differences between MultiValue and Caché.
See Also: CREATE.ACCOUNT
AUTOLOGOUT
The AUTOLOGOUT command sets and displays the time setting for automatic logout.
AUTOLOGOUT [minutes]
Specifying AUTOLOGOUT with no operand returns the current autologout setting: either “Automatic logout is set for x minutes” or “Automatic logout is disabled”. The default is “disabled”. AUTOLOGOUT with no operand returns the most recent setting; it does not return the number of minutes remaining.
Use the optional minutes argument to set an automatic logout time. Automatic logout can be set to a positive integer number of minutes. A fractional number of minutes is truncated to its integer portion. Setting minutes to 0, a fraction less than 1, or a negative number disables automatic logout.
BASIC
The BASIC command compiles one or more MVBasic programs stored in a file.
BASIC filename [itemspec] [(SXZ]
The filename specifies a file created using CREATE.FILE. The itemspec specifies one or more existing MVBasic programs within filename. (You can create an itemspec MVBasic program within filename using ED.) If the filename file doesn't exist BASIC generates a [201] error message. If the specified itemspec item doesn't exist BASIC generates a [202] error message.
When an itemspec item successfully compiles BASIC displays the item name and generates a [B0] message. When an itemspec item fails to compile BASIC displays the source code line where the error occurred and generates a [B100] message. If any compilation failed during the BASIC operation, BASIC generates a [258] error at the end of the compile with a message indicating how many source file items failed to compile.
The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection].
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file; the default is a data file. Specify accountname if the file is located in an account other than the current account. Specify datasection if the program to be compiled is stored in a named data section.
The itemspec specifies the item ID of each program to be compiled. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all MVBasic programs in the file should be compiled. If itemspec is omitted, BASIC uses the active select list as the source for the list of item IDs. If there is no active select list, BASIC issues a “Item Id:” user prompt.
As each item is compiled, BASIC updates the @RECORD special variable, a dynamic array consisting of the lines of the last itemspec successfully compiled.
The optional letter codes specify compilation options. You can specify one or more letter codes in any order. Letter codes must be preceded by an open parenthesis; a closing parenthesis is not required. Following compilation, S produces an active select list of all programs that failed to compile. The X and Z letter code options reduce the size of the compiled program; they should only be used when a compiled program exceeds maxsize. X removes the variable names; this means that the debugger cannot display variables, and the variable name is not reported if an <UNDEFINED> error occurs. Z removes the line table; this table is used to derive the source line number when there is an error to report. Without the line table, an error location cannot be determined.
After compiling a MVBasic program, you can execute it using the RUN command. You can catalog it in the VOC using the CATALOG command, after which it can be executed simply by invoking it as a verb.
See Also: ; (semicolon), CATALOG, MVI, RUN
BLOCK.PRINT
The BLOCK.PRINT command prints a text as large-format letters.
BLOCK.PRINT text
You can specify any printable character(s) as text, including a text containing blank spaces; no enclosing quotes are required. BLOCK.PRINT uses multiple “X” characters to print each character of text as a large block character. By default, it inserts a line break each time it encounters a space character or a string of space characters. An error message is returned if a string of characters is too long to print on one line.
A text does not require delimiters. The text, or a substring within text, can optionally be delimited by either single quotes (') or double quotes ("). These delimiter characters do not print; they specify that the text within the delimiters is to be printed exactly. Thus, to print a string containing one or more space characters as a single line, enclose the string in quote characters. For example: "one line". To include one or more quote characters as literals in the printed string, enclose the string with the other type of delimiter character. For example: "won't".
The BLOCK.PRINT command outputs to the current printer. The BLOCK.TERM command outputs to the current terminal. These commands are otherwise identical.
See Also: BLOCK.TERM
BLOCK.TERM
The BLOCK.TERM command displays a text as large-format letters.
BLOCK.TERM text
You can specify any printable character(s) as text, including a text containing blank spaces; no enclosing quotes are required. BLOCK.TERM uses multiple “X” characters to represent each character of text as a large block character. By default, it inserts a line break each time it encounters a space character or a string of space characters. BLOCK.TERM returns an error message if a string of characters is too long to display on one line; by default this maximum string length is 10 characters. The text can be of any length, provided no substring not containing a space character is greater than 10 characters.
A text does not require delimiters. The text, or a substring within text, can optionally be delimited by either single quotes (') or double quotes ("). These delimiter characters do not display; they specify that the text within the delimiters is to be displayed exactly. Thus, to display a string containing one or more space characters as a single line, enclose the string in quote characters. For example: "one line". To include one or more quote characters as literals in the displayed string, enclose the string with the other type of delimiter character. For example: "won't".
The BLOCK.TERM command outputs to the current terminal. The BLOCK.PRINT command outputs to the current printer. These commands are otherwise identical.
See Also: BLOCK.PRINT
BREAK
The BREAK command (and its variants) enable or disable terminal keys that can pause program execution.
BREAK [ON | OFF] BREAK.KEY.ON BREAK.KEY.OFF BREAK.KEY.ENABLE ENABLE.BREAK.KEY
When BREAK is enabled (ON), the Interrupt, Suspend, and Quit keys will cause program execution to be suspended. When BREAK is disabled (OFF) these keys have no effect on program execution. BREAK is enabled by default. The same operation is performed by the MVBasic BREAK statement.
Issuing any of these statements increments or decrements a counter. Thus multiple BREAK OFF statements (of any type) must be reversed by an equal number of BREAK ON statements.
In jBASE emulation, these statements simply enable or disable (toggle) without maintaining a counter.
See Also: MVBasic BREAK statement.
BSELECT
The BSELECT command generates a select list of non-null items that satisfy the query criteria.
BSELECT [DICT] filename [field1 [field2 ...] [dict [dict2 ...] | ALL] [query] [TO listnum] [(FPYZ]
BSELECT and SELECT are identical, except that BSELECT does not select null items; SELECT selects all items including null items. BSELECT copies non-null items selected from filename to a select list. If filename is not an existing file, BSELECT generates a [200] error. If filename is an empty file, BSELECT generates a [401] error and no select list is returned.
The optional DICT keyword specifies that filename is accessing a dictionary file; otherwise, the filename is assumed to be accessing a data file. If there are multiple defined data sections (data files), you can specify filename as filename,datasection. BSELECT can specify any valid Caché MultiValue SQL (CMQL) query.
The optional field arguments permit you to specify which DICT entries to select. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. If you omit the field argument, all DICT entries in filename are selected, or all DICT entries are selected that pass the condition tests in query. If no items pass the query condition test, BSELECT generates a [401] error and no select list is returned.
The optional dict arguments permit you to specify which DICT entries to select for each field. You can specify one or more dict entry names separated by blank spaces. DICT entry names are not enclosed with quote characters. If you omit the dict argument, only the @ID (VOC) dictionary entry for each field is selected. If you specify ALL, all the dict attribute values for each field are selected.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
You can use the TO clause to specify a numeric select list. Valid listnum values are 0 through 10. By default, BSELECT uses select list 0. An invalid listnum generates a [819] error.
The following are supported letter code options:
-
(F suppresses “not on file” message generation. Because select lists are implemented as SQL joins that only return rows that are in both the select list and the file, Caché MultiValue compares each item in the list with the file; items that don’t match are added to the error list, unless suppressed using this option.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the BSELECT operation.
Upon successful completion, BSELECT returns a message such as the following: 2 Items selected to list #0. The first successful BSELECT to any select list sets the boolean flag $MVV(210) to 1. $MVV(210) remains set to 1 until explicitly reset. The $MVV special variable is described in the Caché ObjectScript Reference.
See Also: CLEARSELECT, NSELECT, QSELECT, SEARCH, SELECT, SSELECT
BUILD.INDEX
The BUILD.INDEX command builds (populates) either an index for a specified file attribute, or indices for all of the attributes of the file.
BUILD.INDEX filename attribute | ALL | *
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist BUILD.INDEX returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the index to be built is stored in a named data section.
You can specify a single attribute, or a series of attributes, separated by blank spaces. You can use either the ALL keyword or the asterisk (*) to build all indices.
If the attribute is not specified, BUILD.INDEX returns a [211] message. If attribute is invalid, or there are no indices defined for this filename, BUILD.INDEX returns a [842] message. If the index has already been built, BUILD.INDEX overwrites the previous index data.
Before you can build an index, you must create the index for filename using CREATE.INDEX.
See Also: CREATE.INDEX, LIST.INDEX
CATALOG
The CATALOG command catalogs one or more compiled MVBasic programs, storing a pointer to each in the VOC as a verb.
CATALOG filename [itemspec] [(L | N | G | GA ]
CATALOG catalogs one or more compiled MVBasic programs in the VOC so that they can be executed by specifying just the item ID, the same as any other MultiValue command (verb). Before cataloging a program, you must compile it using the BASIC command. You can execute a compiled MVBasic program without cataloging it by using the RUN command. There are three ways to catalog a program: Local (L), Normal (N), or Global (G or GA). When you change a Local or Global cataloged MVBasic program you must recompile it; you do not have to re-catalog it.
If you CATALOG a compiled MVBasic file, the filename is listed in the VOC as a file (F1=F) and can be displayed using LISTF. The MVBasic itemspec programs are listed in the VOC as verbs (F1=V).
If the filename file doesn't exist CATALOG generates a [201] error message. If the specified itemspec item doesn't exist CATALOG generates a [41] error message. If the specified itemspec item has not been compiled CATALOG generates a [40] error message.
filename is the file to search for the itemspec MVBasic program(s). The filename is the name of an existing file, which is created as VOC F1=F entry. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify accountname if the file is located in an account other than the current account. Specify datasection if the program is stored in a named data section of the file.
itemspec specifies one or more compiled MVBasic programs by item ID. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all compiled MVBasic programs in the file should be cataloged. If itemspec is omitted, CATALOG uses the active select list as the source for the list of item IDs. If there is no active select list, CATALOG issues a “Item Id:” user prompt.
If specified, a letter code option must be prefaced by an open parenthesis. Only one letter code option may be specified. The available letter codes are: L = Local Catalog, N = Normal Catalog, G = Global Catalog, GA = Global Catalog with Account Name. The default is Local Catalog.
-
(L: Local Catalog adds an entry to the VOC and points to the program's object code. A Local Catalog operation will fail if program has already been cataloged with Normal Catalog.
-
(N: Normal Catalog adds an entry to the VOC and points to a copy of the program's object code. Normal Catalog allows users to continue to run a copy of the original code while you edit and test the program code itself. Therefore, changes made to the original code do not affect the cataloged copy until the object code is re-cataloged. Users can continue to run the cataloged copy of the original compiled code by:
-
Running it from the Terminal command line using the cataloged name reference to the copy of the code
-
Running it from MVBasic, issuing an EXECUTE, PERFORM, or CHAIN of the cataloged name
You can use ED to edit and BASIC to compile the original program without affecting users of the Normal Catalog version. You can use RUN to execute and debug the most recently compiled version.
You can edit, compile, and debug via Studio without affecting users of the Normal Catalog version. Note that although compile via Studio does a Local Catalog by default, it does not replace the Normal Catalog VOC entry. Instead, it provides the following message: WARNING : "PROG" already cataloged without L option - you must recatalog it to use updated code. If you use #PRAGMA ROUTINENAME, that name is used for the .mvi and .obj code, and that is what is used by Studio to run and debug. Studio does not debug the copy of the original code created by a Normal Catalog. Thus one disadvantage of using Normal Catalog is that Studio does not see the catalogued copy, and therefore cannot debug that code, unless you directly open the *.mvi routine in attribute 2 of the VOC entry for the program.
-
-
(G: Global Catalog adds an entry to the global catalog (not the VOC) and points to a copy of the program's object code in a location accessible for access from all accounts. Specifying Global Catalog removes all corresponding Local Catalog and Normal Catalog entries from the VOC.
-
(GA: Global Catalog with Account Name adds a global catalog entry prefaced with the account name delimited by asterisks. Thus using (GA to catalog the program MYPROG while in account USER would create the global catalog entry *USER*MYPROG. Using (GA does not delete any earlier global catalog entry created using (G, nor does it remove Local Catalog and Normal Catalog entries from the VOC.
See Also: BASIC, DECATALOG, PRINT.CATALOG
CEMU
The CEMU command changes the emulation of the current account.
CEMU [emulation]
Specifying CEMU with no operand returns the current emulation. For example, “Emulation for account 'USER' is 'CACHE'.”
Specifying CEMU with an operand sets the current emulation for the current account, and returns a message. The available emulation values are: Cache, D3, IN2, INFORMATION, jBASE, MVBase, PICK, PIOpen, Prime, R83, POWER95, Reality, UDPICK (UniData running in PICK mode), Ultimate, UniData, and UniVerse. The emulation argument is not case-sensitive. Both “Prime” and “Information” emulation values set an emulation of “INFORMATION.” An emulation value of “Default” sets an emulation of “CACHE”. An invalid emulation value returns an 812 error.
CEMU sets emulation for the current account (namespace) only. CEMU cannot set emulation for the SYSPROG account. This account is always in CACHE emulation. Attempting to change SYSPROG emulation returns an [815] error message.
All Caché accounts are initialized to an emulation of Cache. However, once you have set the emulation for an account, this emulation is persistent. It is retained after the process that sets it terminates, and applies to all future processes accessing that account until explicitly changed. Restarting Caché does not revert the emulation setting.
You can determine the current emulation from MVBasic as an integer value. You can return the integer value for the current emulation using the SYSTEM(1001) and SYSTEM(1051) functions, as described in the Caché MultiValue Basic Reference. You can also specify emulation within MVBasic by using the $OPTIONS command, as described in the Caché MultiValue Basic Reference.
For further details, refer to the CEMU section of the Operational Differences between MultiValue and Caché manual.
See Also: CREATE.ACCOUNT, LOGTO
CENTURY.PIVOT
The CENTURY.PIVOT command specifies how two-digit year values are interpreted process-wide.
CENTURY.PIVOT [year]
Upon MV Shell initialization, the MV Shell displays a [150] message indicating the default two-digit year date range. By default, a two-digit year is interpreted as being in the range 1900 to 1999. Specifying CENTURY.PIVOT with no operand returns the current date range for two-digit years.
You can use CENTURY.PIVOT to set any hundred-year range for two-digit years. To set this date range, specify a four-digit year as the beginning year of the century range. This four-digit year must be between 1841 and 9900, inclusive. A [152] message is generated indicating the new two-digit year date range. An invalid year value generates an [801] error. Once set, a two-digit year date range applies to the current process for the duration of the current process, or until set again. It applies to all accounts (namespaces). It continues to apply for the current process across quitting and re-invoking of the MultiValue Shell.
CHECK.DICT
The CHECK.DICT command checks for a field in a file's DICT file.
CHECK.DICT filename [itemspec]
CHECK.DICT checks one or more item names in the filename DICT file.
The filename can be specified using filespec syntax, as follows:
[accountname,]filename[,datasection]
CHECK.DICT always references the DICT file.
itemspec is DICT item, or a list of DICT items to be checked. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all items in the DICT file should be checked. If itemspec is omitted, CHECK.DICT uses the active select list as the source of DICT item names to check.
As each item is accessed, CHECK.DICT updates the @RECORD special variable.
If all of the specified items are present, CHECK.DICT completes without a message. If specified items are not present, CHECK.DICT returns a [202] message for each item not found in DICT.
If you omit the itemspec argument with no active select list, CHECK.DICT prompts you for it with the Item Id: prompt. At this prompt you can specify multiple items separated by blank spaces.
You can use LIST DICT filename to list all of the fields in the DICT file.
See Also: COMPILE.DICT, LIST
CHECK.PROC
The CHECK.PROC command checks that a PROC can be successfully compiled.
CHECK.PROC filename [itemspec]
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist CHECK.PROC returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the PROC to be checked is stored in a named data section.
itemspec is the name of a PROC, or a list of PROCs to be checked. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all PROCs in the file should be checked. If itemspec is omitted, CHECK.PROC uses the active select list as the source of PROC names to check.
As each item is accessed, CHECK.PROC updates the @RECORD special variable.
CHECK.PROC checks one or more named PROCs in a file. If a named PROC can be compiled, CHECK.PROC compiles it. If named PROC cannot be compiled, CHECK.PROC returns an error message.
CHOOSE.TERM
The CHOOSE.TERM command allows you to choose a terminal type. It displays a list of supported terminal types, then prompts you to specify the desired terminal type.
CHOOSE.TERM
After listing all the supported terminal types, CHOOSE.TERM prompts you to select a terminal type by either specifying its name (Term Name), its number in the listing, or (in some cases) a Short Name (a single uppercase letter). You can specify a Term Name with any combination of letter case: if all letters are specified in lowercase the terminal type is set as specified; if one or more letters are specified in uppercase the terminal type is set in all uppercase. To exit without changing the current terminal type, press Enter at the prompt.
You can determine your current terminal type by calling the MVBasic SYSTEM(7) function or the TERM command. The TERM command can also be used to choose a terminal type and/or to change certain terminal and printer parameters. For further details, refer to the Terminal Output chapter of the Caché MV Terminal Independence manual, and the CHOOSE.TERM section of the Operational Differences between MultiValue and Caché manual.
See Also: COMPILE.TERM, TERM
CLEAR.CMQL.CACHE
The CLEAR.CMQL.CACHE command clears the query cache for the current account.
CLEAR.CMQL.CACHE [(I]
This command should only be used during code analysis to ensure that the query cache has been cleared. It should not be used as part of normal MultiValue execution. This command should never be executed when the current account is being actively used.
Issuing CLEAR.CMQL.CACHE displays a warning message and an acceptance prompt. To execute CLEAR.CMQL.CACHE, input “Y” at the prompt; to cancel CLEAR.CMQL.CACHE input “N” or just press Return.
The optional (I letter code causes CLEAR.CMQL.CACHE to clear the ITYPE cache as well. After using CLEAR.CMQL.CACHE (I you must recompile classes for files with indices based on I-types. Failure to do so results in index corruption.
CLEAR.FILE
The CLEAR.FILE command clears all data from a file.
CLEAR.FILE filename
The filename is the name of an existing file, which is created as a Caché global (^filename). The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if you wish to clear only the data stored in a named data section.
If the filename is not specified, CLEAR.FILE returns a [200] message. If the filename is not valid, CLEAR.FILE returns a [201] message. If the filename is valid, CLEAR.FILE returns a [433] message indicating that the file has been cleared, even if there was no data in the file. If the file was indexed, CLEAR.FILE also returns a [1] message “indexes purged”.
See Also: DELETE
CLEAR.LOCKS
The CLEAR.LOCKS command clears locks that are held by the current process.
CLEAR.LOCK [lock]
Use the optional lock argument to specify a specific lock. The default (with no argument) releases all locks held by the process.
CLEAR.LOCKS releases process locks only. It does not release system locks, readu locks, file locks, or any other lock type. Use the Management Portal to release all types of locks.
Locks are established using the MVBasic LOCK command or by opening a sequential file. When establishing a lock, you can name it with a numeric value or with a quoted string name. List all current locks using LIST.LOCKS. Process locks appear in the LIST.LOCKS output as LOCK name. When clearing a lock, lock must correspond to the lock name. Lock names are case-sensitive. When specifying lock, quote characters are optional.
If the lock specified by lock is not a current lock, CLEAR.LOCKS performs no operation and completes without issuing an error.
See Also: LIST.LOCKS, MVBasic LOCK, MVBasic UNLOCK
CLEARDATA
The CLEARDATA command clears the data stack.
CLEARDATA
CLEARPROMPTS
The CLEARPROMPTS command clears the value established for an inline prompt.
CLEARPROMPTS
Once a value has been input for an inline prompt, that value is used for every instance of that prompt, unless a CLEARPROMPTS command is issued to clear the inline prompt value.
See Also: << ... >> (inline prompting)
CLEARSELECT
The CLEARSELECT command clears the contents of the specified select list.
CLEARSELECT {listnum | ALL}
CLEARSELECT clears the specified numbered select list, or clears all numbered select list by specifying the ALL keyword. A select list is specified as an integer from 0 through 10. This command is identical to the CLEARSELECT Caché MVBasic Command.
See Also: BSELECT, NSELECT, QSELECT, SEARCH, SELECT, SSELECT
CLR
The CLR command clears the screen and sets the cursor to the first line.
CLR
The CLR and CS commands are synonyms.
See Also: CS
COMO
The COMO command copies terminal output to a record in the &COMO& file.
COMO ON record [HUSH] COMO OFF COMO LIST COMO DELETE record | * COMO SPOOL record
If you specify COMO with no arguments, it returns a series of prompts requesting an option keyword and the record name.
COMO ON creates the specified record in the &COMO& file. Caché stores the &COMO& file using the ^COMO global. The optional HUSH keyword suppresses terminal display. COMO DELETE deletes the specified &COMO& file record. COMO DELETE * deletes all the &COMO& file records.
You can use LIST &COMO& to list the records in the &COMO& file.
See Also: LIST
COMPILE.DICT
The COMPILE.DICT command compiles I-descriptors in dictionary records.
COMPILE.DICT filename [itemspec]
The filename can be specified using filespec syntax, as follows:
[accountname,]filename[,datasection]
COMPILE.DICT always references the DICT file.
itemspec is DICT item, or a list of DICT items to be compiled. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all items in the DICT file should be compiled. If itemspec is omitted, COMPILE.DICT uses the active select list as the source of DICT item names to compile.
As each item is accessed, COMPILE.DICT updates the @RECORD special variable.
See Also: CHECK.DICT, ICOMP
COMPILE.TERM
The COMPILE.TERM command compiles terminal definitions.
COMPILE.TERM [[filename [item-list] | *] [(TV] ]
COMPILE.TERM, with no arguments, compiles all the items in the %MV.TERMDEFS file. COMPILE.TERM filename compiles all the items in the filename file. COMPILE.TERM * compiles all the items in the %MV.TERMDEFS file and adds/replaces the results in the %MV.TERMCMP file. It does not delete existing items from TERMCMP. If you want to eliminate some entries from TERMCMP (for example, to eliminate them from the CHOOSE.TERM listing) you should manually DELETE them from TERMCMP (and optionally from TERMDEFS).
The (T letter code option performs a tree search on filename; this assumes that filename is a directory in UNIX®/UniVerse format. For example: COMPILE.TERM //C:/terminfo (T. Note the use of the // prefix to directly reference a directory. The (V letter code option performs the compile in verbose mode.
For further details, refer to the Terminal Definition chapter of the Caché MV Terminal Independence manual.
See Also: CHOOSE.TERM, TERM
CONTROL.CHARS
The CONTROL.CHARS command sets input filtering of control characters.
CONTROL.CHARS [(F[S] | (N[S]]
CONTROL.CHARS with no option returns the current control character filtering setting (ON or OFF).
-
The (F letter code option filters out control characters from the data received by the MVBasic INPUT statement. This returns the status string “CONTROL filtering is ON”. CONTROL.CHARS (F activates input filtering for the process; the MVBasic INPUTCTRL ON statement activates input filtering for the current program.
-
The (N letter code option deactivates filtering of control characters. This returns the status string “CONTROL filtering is OFF”. CONTROL.CHARS (N deactivates input filtering for the process; the MVBasic INPUTCTRL OFF statement deactivates input filtering for the current program.
-
The (S letter code option suppresses the status string display when activating or deactivating input filtering of control characters.
COPY
The COPY command copies items from file to file. It has two distinct syntax forms: non-interactive and interactive:
Non-interactive format:
COPY FROM sourcefile [TO targetfile] {item1[,newname1] [item2[,newname2] [...]] | ALL} [DELETING | OVERWRITING | UPDATING | SQUAWK]
COPY copies the specified items from sourcefile to targetfile. You must specify one or more items, or specify the ALL keyword, which copies all items in sourcefile. If you omit the TO clause, COPY copies the item(s) from sourcefile to sourcefile. Both sourcefile and targetfile can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. If there are multiple defined data sections, you can specify sourcefile and/or targetfile as filename,datasection. File names and item names are case-sensitive.
You can specify one or more items to copy, separating the items with a blank space. You can specify a new name for the copied item, associating the original sourcefile name and the new targetfile name with a comma.
As each item is accessed, COPY updates the @RECORD special variable.
You can specify one or more of the following keyword options. Keywords must be specified in all uppercase letters. The DELETING keyword specifies that the original item in sourcefile is deleted after it is copied. The OVERWRITING keyword specifies that the copy occurs even if the named item exists in targetfile; the existing item with that name is overwritten. The UPDATING keyword is the same as the OVERWRITING keyword. The SQUAWK keyword displays the names of the files and the settings of the keyword options when performing the copy operation.
If the specified sourcefile or targetfile is not valid, COPY returns a [201] message. If the specified item is not valid, COPY returns a [202] message. If the specified item already exists in file and OVERWRITING is not specified, COPY returns a [415] message.
Interactive format:
COPY sourcefile [item1 [item2 [item-n]][(D | O | U | S] TO:[(destinationfile ]newname1[ newname2[ ...]]
If you omit the item(s), COPY prompts you with Item ID:. It then prompts you for the destination file with TO:. You can either:
-
Specify an item list,
-
Specify a destination file (preceded by an apostrophe (') and an item list, or
-
Press Enter to copy the items to the Terminal display.
The D, O, U, and S options correspond to the keywords DELETING, OVERWRITING, UPDATING, and SQUAWK. If you specify a destinationfile but no item list, the original names are used. If you specify fewer destination names than source names, COPY attempts to use the original names for the extra source items. If more destination item names than source item names are specified, the extras are ignored.
See Also: COPY.FILE, COPYI, COPYP
COPY.FILE
The COPY.FILE command copies a file.
COPY.FILE [FROM] sourcefile [TO targetfile] [(D]
COPY.FILE creates a new file (targetfile) and copies the contents of sourcefile to targetfile.
-
If you specify TO targetfile, COPY.FILE copies sourcefile to targetfile. COPY.FILE creates the targetfile, then copies the contents of sourcefile to targetfile.
-
If you specify TO and omit targetfile, COPY.FILE copies sourcefile to the VOC in the current account.
-
If you omit both TO and targetfile, COPY.FILE prompts you to specify a targetfile with a TO: prompt. To copy sourcefile and assign it a new name, specify targetfile at the prompt. To copy accountname,sourcefile from a different account to the current account, retaining the same file name, press Enter at the TO: prompt.
For all invocations of COPY.FILE the targetfile must not be an existing file. Both sourcefile and targetfile can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the file to be copied is stored in a named data section. Some emulations support single level files; if sourcefile is a single level file, COPY.FILE copies both the dictionary and data information. See CREATE.FILE concerning single level files.
COPY.FILE assigns the targetfile name to the targetfile @ID dictionary item, rather than copying the sourcefile @ID value.
The FROM keyword is optional.
The (D letter code option deletes the sourcefile after performing the copy operation. This is used for renaming a file.
If sourcefile contains an index reference, COPY.FILE does not copy this index reference to targetfile.
By default, COPY.FILE creates a target file regardless of whether the Attribute 2 ^filename and Attribute 3 ^DICT.filename globals are already in use. You can modify the COPY.FILE verb to prevent this. Edit COPY.FILE to add an Attribute 5 value of “m” (lowercase m). Now attempting to create a target file when one of these globals is already in use generates a [448] error.
See Also: COPY
COPY.LIST
The COPY.LIST command copies a saved select list from the &SAVEDLISTS& file.
COPY.LIST [filename [listname] ]
The optional filename is the destination file where the select list is to be copied. If you omit filename, COPY.LIST prompts you for the destination file name. The optional listname is the name of an existing select list; the default is select list 0. The listname select list is saved in the &SAVEDLISTS& file. Caché stores this file using the ^SAVEDLISTS global.
See Also: DELETE.LIST
COPYI
The COPYI command is the non-interactive form of the COPY command. The syntax is identical, except that the FROM keyword is optional.
See Also: COPY
COPYP
The COPYP command is the interactive form of the COPY command.
See Also: COPY
COS
The COS command causes the statement following it to be interpreted as an ObjectScript command.
COS commandline
COS issues an ObjectScript command without exiting the MultiValue Shell. The commandline can be any valid ObjectScript command line. A commandline cannot be specified as a variable, nor can it be enclosed in quotation marks.
If commandline changes the current namespace (for example, by issuing a ZNSPACE command), the Caché MultiValue Shell restores the initial namespace upon exiting ObjectScript.
COS should not be followed by the ObjectScript MV MultiValue Shell invocation command. Nested MultiValue Shell invocations may cause unexpected problems.
You can use SH to issue an operating system command without exiting the MultiValue Shell.
The COS command is functionally identical to the #, and [ commands.
COUNT
The COUNT command counts the items that satisfy an SQL query.
COUNT [DICT] filename [field1 [field2 ...]] [query] [(PYZ]
COUNT returns an integer count of the field items found in filename, or the items selected from filename by query. The optional DICT keyword causes the command to count the DICT entries in the filename dictionary file; otherwise, filename is assumed to be a data file.
COUNT filename returns the total number of items in filename.
COUNT filename with field arguments returns the total number of specified field items that are found in filename. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. Only items that are found in filename are counted; items not found in filename are displayed as a “not found” message.
COUNT filename query returns the number of items in filename that fulfill the specified criteria. For example, STAT VOC WITH F1="V" returns the count of verbs (V) in the VOC file. The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code options:
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the COUNT operation.
COUNT provides part of the functionality of the STAT command. STAT can return results from an AVG or ENUM CMQL clause; COUNT cannot return values for these CMQL clauses. The similar LIST command with the DET-SUPP keyword also returns the total number of filename items.
CREATE.ACCOUNT
The CREATE.ACCOUNT command creates an account (namespace).
CREATE.ACCOUNT account [emulation] [directory]
The account is the name to assign to the namespace and the account. An account name commonly consists of letters, numbers, and the percent (%), hyphen (-), and underscore (_) characters. (Other punctuation characters are allowed, but should be avoided.) Percent (%) should only be used as the first character; hyphen (-) and underscore (_) should not be used as the first character. Underscore (_) cannot be used as the last character.
The system creates a corresponding namespace, as follows:
-
Caché namespace names cannot begin with a number as the first character. If the account name begins with a number, Caché strips the leading number(s) from the account name to create the corresponding namespace name.
-
Caché reserves namespace names that begin with % . Therefore, if the account name begins with %, Caché strips the % from the account name to create the corresponding namespace name.
-
Caché namespace names cannot contain punctuation characters other than the hyphen (-) and underscore(_). If the account name contains other punctuation characters, Caché strips them from the account name to create the corresponding namespace name.
-
Caché converts the resulting name to all uppercase characters. Namespace names are not case-sensitive, but account names are case-sensitive.
If you have specified an account name with the same name as an existing namespace that has no corresponding account, or if you have specified an account name that differs from an existing account name only in capitalization or in characters removed during namespace conversion, the system creates a unique namespace name. It creates this unique namespace name by appending an underscore and a sequential number, starting with the “_1” suffix.
Note that the SYSPROG account corresponds to the %SYS namespace.
For details on the relationship between accounts and namespaces, and the naming conventions used for each, refer to “MV Accounts and Caché Namespaces” in Operational Differences between MultiValue and Caché.
If the specified account already exists, CREATE.ACCOUNT returns an [810] message. Upon successful completion, CREATE.ACCOUNT returns an [814] message.
The optional emulation argument specifies the MultiValue emulation type. The default is Cache.
The optional directory argument specifies the location in which to create the account database. Specify a fully-qualified pathname. The default is \Mgr\accountname in the Caché installation location.
Account creation and deletion requires %Admin_Manage privileges. This is normally associated with the SYSPROG account, which is the %SYS namespace. For information on the Caché security model, see the Caché Security Administration Guide. For specific information on roles and privileges, please consult the chapters on Roles and Privileges and Permissions.
See Also: ATTACH.ACCOUNTS, CEMU, DELETE.ACCOUNT, LOGTO
CREATE.BFILE
The CREATE.BFILE command creates a MultiValue Basic (MVBasic) source code file.
CREATE.BFILE [DATA | DICT] filename[,datasection] [ANODE | INODE]
The filename is the name of the Basic source code file, which is created as a Caché global (^filename). Caché global names are case-sensitive. Creating a file also creates a VOC entry for the file.
By default, CREATE.BFILE creates both a data file and a dictionary file; that is, a file with a dictionary (DICT) and a data section. The optional DICT and DATA keywords enable you to specify the creation of just a dictionary file or just a data file. Creating a dictionary also places a default record @ID in the dictionary.
Creating a data file creates a default data section. You can specify datasection if you wish to create a named data section. The datasection argument can only be specified for a data file; attempting to specify it for a dictionary file (DICT keyword) returns a [424] message.
By default, CREATE.BFILE creates a file of type INODE (item node); both the data section and DICT are of type INODE. You can override this default by specifying ANODE (attribute node). When you create both a data file and a dictionary file, the ANODE keyword only applies to the data section; the DICT is still created as type INODE. To create a DICT of type ANODE you must specify both the DICT and ANODE keywords.
CREATE.BFILE is a specific application of the more general CREATE.FILE command.
See Also: CREATE.FILE, DELETE.FILE
CREATE.FILE
The CREATE.FILE command creates a file.
CREATE.FILE [DATA | DICT] filename[,datasection] [ANODE | INODE] [DIR directory] [(RUX]
The filename is the name of the file to create. CREATE.FILE creates the file as a Caché globals (^filename and ^DICT.filename). Caché global names are case-sensitive. Creating a file also creates a VOC entry for the file. If filename already exists, CREATE.FILE generates a [413] error.
By default, CREATE.FILE creates both a data file and a dictionary file; that is, a file with a dictionary (DICT) and a data section. The optional DICT and DATA keywords enable you to specify the creation of just a dictionary file or just a data file. Creating a dictionary also places a default record @ID in the dictionary.
Creating a data file creates a default data section. You can specify datasection if you wish to create a named data section. The datasection argument can only be specified for a data file; attempting to specify it for a dictionary file (DICT keyword) returns a [424] message.
By default, CREATE.FILE creates a file of type INODE (item node); both the data section and DICT are of type INODE. You can override this default by specifying ANODE (attribute node). When you create both a data file and a dictionary file, the ANODE keyword only applies to the data section; the DICT is still created as type INODE. To create a DICT of type ANODE you must specify both the DICT and ANODE keywords.
The DIR keyword specifies that the data section is set to use the specified directory.
The (R letter code option allows you to create the file in an account other than your current account. If you specify (R, CREATE.FILE prompts you to specify an account name.
The (U letter code option specifies that item names added to the file are to be untranslated when recorded in the directory. Name translation converts punctuation characters into hexadecimal codes (for example an _ (underscore) in a name is represented by 5F). By default, item names are translated.
The (X letter code option specifies that item names added to the file will include the three-character extension .mvb. Item names with this extension are parsed as MVBasic program files. A file created with this letter code option has a VOC entry Attribute 6 value of "B" and "X".
You can create an &SAVELISTS& or &HOLD& file as an ANODE type file (attribute of an item node), as follows:
USER:DELETE.FILE &SAVEDLISTS&
USER:CREATE.FILE &SAVEDLISTS& ANODE
You can create an &SAVELISTS& file as a DIR type file in an account, as follows:
USER:DELETE.FILE &SAVEDLISTS&
USER:CREATE.FILE &SAVEDLISTS& DIR SAVEDLISTS
Caché stores the &SAVEDLISTS& file using the ^SAVEDLISTS global. If the specified filename already exists, CREATE.FILE returns a [413] message.
By default, CREATE.FILE creates a file regardless of whether the Attribute 2 ^filename and Attribute 3 ^DICT.filename globals are already in use. You can modify the CREATE.FILE verb to prevent this. Edit CREATE.FILE to add an Attribute 5 value of “m” (lowercase m). Now attempting to create a file when one of these globals is already in use generates a [448] error.
Emulation
In D3, IN2, jBASE, MVBase, Pick, Reality, R83, POWER95, and Ultimate emulations, the command CREATE.FILE DICT filename creates a single level file. This is a file in which the dictionary section and the data section are the same.
You can delete a single level file using either DELETE.FILE filename or DELETE.FILE DICT filename. You cannot delete a single level file using DELETE.FILE DATA filename.
See Also: CATALOG, CLEAR.FILE, CREATE.BFILE, DELETE.FILE
CREATE.INDEX
The CREATE.INDEX command creates an index on a file.
CREATE.INDEX filename indexfield [indexfield2 [...]]
The filename is the name of an existing file, which is created as a Caché global (^filename). The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the created index is to be stored in a named data section. The filename must be an INODE file; you cannot create an index on a directory file or an ANODE file.
You can use indexfield parameters to specify one field or more than one field to index; If you specify multiple fields, a separate index is created on each. When CREATE.INDEX creates an index it returns an [866] message. If indexfield does not exist, it returns a [202] error. If indexfield cannot be indexed, it returns a [5] invalid format error. If indexfield has already been indexed, an ERROR #5805: ID key not unique error is generated.
The indexfield is the itemid of an item in the dictionary of filename. It can be any length up to the maximum subscript size (because it is used as a subscript in the global). Creating the index creates both a class property and an index name entry in the associated Caché class. The property is named by converting indexfield to a case-sensitive name by omitting punctuation and using an uppercase letter to indicate where the punctuation was removed. For example, the indexfield START.DATE would correspond to the property name StartDate. The index name is created by appending the string “index” to the indexfield property name, then truncating the resulting name at 31 characters. Therefore, an indexfield name must be unique within the first 26 characters.
When creating an index for a MultiValue file, it is strongly recommended that every unique attribute have a corresponding class property. Any field/attribute that does not have a corresponding class property will become empty when the %Save() method is invoked. (Attributes that are mere synonyms do not require a corresponding class property.)
CREATE.INDEX assigns SqlString(150) collation to both the index and the created indexfield property. However, if the property already exists, CREATE.INDEX assigns the index the same collation type as the indexfield property.
CREATE.INDEX creates a class with a property named ItemId, which describes the item id of the original MultiValue file. You can change the names of other properties in the generated class (assuming that you also change the name anywhere that the property is referenced by other properties, indices, or methods) but the ItemId property must be named ItemId. Otherwise subsequent CREATE.INDEX commands will fail and leave the class in an uncompileable state.
All properties created using CREATE.INDEX contain an MVAUTO parameter which is assigned the “I” letter code. For further MVAUTO details, refer to the PROTOCLASS chapter of this manual.
If the specified indexfield is composed entirely of virtual fields, CREATE.INDEX automatically creates an additional property called dummyAttribute, so that the resulting class has at least one real (storage) attribute. If CREATE.INDEX adds real attributes later, dummyAttribute is automatically deleted. If you manually add real attributes later, you must manually delete dummyAttribute and associated storage.
You do not need to use CREATE.INDEX to add indices to a class. You can define indexes by either using CREATE.INDEX or by manually defining indexes by editing the class definition for the file using Studio. But if you intend to use the indexes with MVBasic statements and functions (for example INDICES(), SELECTINDEX, BSCAN, OPENINDEX, and SELECT with the ATKEY clause) you must create them using the format that CREATE.INDEX generates. CREATE.INDEX does not create a new index if there is already an index with the same MVNAME class property attribute as the specified DICT item. If you manually define indexes in a class, it is preferable to avoid the use of CREATE.INDEX and DELETE.INDEX on that file to avoid any unintended deletions.
When you create an index, the system creates a MultiValue index global with the following format:
^I.filename("indexD1"," ABC","NAME")="ABC"
The first node is the index name, here indexD1, created by appending the string “index” to the property name D1. The result is truncated at 31 characters.
The second node is the index key, here with a prefixed space to maintain the SqlString collation that MultiValue expects. This index key is truncated at 150 characters.
The third node is the itemid of the item being indexed. This node's data is a copy of the index key, without collation modification or truncation. This is the value that is returned by MVBasic indexing statements. This itemid can be any length up to the maximum Caché global subscript size.
If you create an index on a file that contains data, you must populate the index using BUILD.INDEX. If you create an index on a file that is currently open, you must close and reopen the file for MultiValue to be aware of the index. This close/reopen is necessary to activate operations such as automatically updating the index when you perform a WRITE. These index activation steps are required for Caché MultiValue, UniVerse emulation, and jBASE emulation.
For further details, refer to the CREATE.INDEX section of the Operational Differences between MultiValue and Caché manual.
See Also: BUILD.INDEX, DELETE.INDEX, LIST.INDEX, the PROTOCLASS chapter of this manual.
CREATE.TRIGGER
The CREATE.TRIGGER command creates a trigger that calls a subroutine when an event of a specified type occurs.
CREATE.TRIGGER filename event subroutine [(AOT]
The filename is the name of an existing file. The trigger is specific to events occurring to this file. The event is the operation that invokes (pulls) the trigger. The trigger can be designed to be invoked before or after the execution of a variety of MVBasic commands. It can be one of the following: *, POSTOPEN, PREREAD, PREINSERT, PREUPDATE, PREWRITE, PREDELETE, PRECLEAR (or PRECLEARFILE), POSTREAD, POSTINSERT, POSTUPDATE, POSTWRITE, POSTDELETE, POSTCLEAR (or POSTCLEARFILE). To invoke the trigger upon any of the event types, specify an asterisk (*) as the event value.
The trigger code that is executed when the trigger is pulled is located in subroutine, which is an MVBasic subroutine.
CREATE.TRIGGER supports the following letter code options:
-
(A allows the trigger to alter the record created or updated by the event operation before the record is saved. This is a trigger execution option.
-
(O allows CREATE.TRIGGER to overwrite an existing definition of this trigger (if one exists). This option has no effect on trigger execution.
-
(T allows a pre-event trigger to terminate (abort) the event operation before it occurs. This is a trigger execution option.
Caché MultiValue also supports UNIX-style option syntax: a hyphen followed by the option as a lowercase letter, as shown in the following example:
CREATE.TRIGGER -a TestFile POSTREAD TriggerSub
Specifying an invalid filename returns a [201] message. Specifying a subroutine that has not yet been cataloged returns a [825] message.
The subroutine syntax is as follows:
SUBROUTINE triggersub(filename,eventnum,prerc,flags,recordkey,record,userrc)
Within the trigger handler subroutine the event value is passed as an integer code, not a keyword. The eventnum integer codes that correspond to event keywords are as follows: POSTOPEN=1, PREREAD=2, POSTREAD=3, PREDELETE=4, POSTDELETE=5, PRECLEAR=6, POSTCLEAR=7, PREWRITE=8, POSTWRITE=9, PREINSERT=10, POSTINSERT=11, PREUPDATE=12, POSTUPDATE=13. Note that an INSERT or UPDATE event is also processed as a corresponding WRITE event; thus the user can handle the event as an INSERT or UPDATE, as a WRITE, or both.
prerc is the status return code for the action performed by the subroutine. If the event is a PRE event, the prerc is always 0; if the event is a POST event, prerc is 0 if the action was successful, non-zero if the action failed. flags is a no-op. recordkey is the item-id of the record being written or deleted; recordkey is null for an OPEN or CLEAR operation. record is the record currently being written; record is null for OPEN, DELETE, and CLEAR operations; record is null for PREREAD, assigned a value for POSTREAD. userrc is a user-defined status return code used only with the (T option. If (T is specified, a non-zero value for userrc causes a PRE event trigger to terminate (abort) the event operation. A negative integer userrc aborts the event operation without invoking the event handler; a positive integer userrc aborts the event operation and is passed as an error code to the error handler.
When an MVBasic READV statement is executed on a file with a POSTREAD trigger, the entire contents of the file record being read are passed to the trigger routine, not just the value of the field specified in READV.
CREATE.TRIGGER creates a trigger wrapper routine, which it names MVTW followed by the file name. If the file name is greater than 22 characters, CREATE.TRIGGER truncates it to 22 characters then adds the checksum integer for the full file name (see the ObjectScript $ZCRC function).
Note that Caché MultiValue triggers are completely separate from Caché SQL triggers. An SQL update will not fire a MultiValue trigger; a MultiValue update will not fire an SQL trigger.
Caché stores pointers to trigger code in the data file header. When a file is opened, that information is stored in the file pointer. If a trigger is added or deleted while the file is open, the system attempts to follow the trigger definitions that existed when the file was opened. This could result in a new trigger not firing, or an attempt to fire a deleted trigger failing and rejecting the WRITE. Therefore, triggers should not be maintained while the corresponding data file is open.
See Also: DELETE.TRIGGER, LIST.TRIGGER
CS
The CS command clears the screen and sets the cursor to the first line.
CS
The CS and CLR commands are synonyms.
See Also: CLR
CT
The CT command displays one or more records on the terminal screen.
CT filename [itemspec] [(P]
The filename is the name of an existing file, which is created as a Caché global (^filename). The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. If there are multiple defined data sections, you can specify filename as filename,datasection.
itemspec is the name of a record, or a list of records, to display. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all records in the file should be displayed. If itemspec is omitted, CT uses the active select list as the source of record names to display. If you omit the itemspec argument and there is no active select list, CT prompts you for items with the Item Id: prompt. At this prompt you can specify multiple field items, separated by blank spaces.
As each item is accessed, CT updates the @RECORD special variable.
The (P letter code option redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
See Also: LIST.ITEM
DATE
The DATE command returns the current local date and time.
DATE [(P]
For example: “Tuesday, October 23, 2007 02:55pm”, The actual date and time format is governed by the DATE.FORMAT command.
Caché MultiValue determines local time and date as follows:
-
It determines the current Coordinated Universal Time (UTC) from the system clock.
-
It adjusts UTC to the local time zone by using the value of the Caché special variable $ZTIMEZONE.
-
It applies local time variant settings (such as Daylight Saving Time) for that time zone from the host operating system.
The optional (P letter code option redirects output to the STANDARD print queue. You can use LISTPEQS to view the print queue.
See Also: DATE.FORMAT
DATE.FORMAT
The DATE.FORMAT command specifies the format used for displaying dates.
DATE.FORMAT [ON | OFF] [(I | (D] DATE.FORMAT INFORM
The optional ON keyword specifies international date order; for example: “Tuesday, 23 October 2007 02:55pm”, The optional OFF keyword specifies USA date order; for example: “Tuesday, October 23, 2007 02:55pm”, The default is ON. The (I and (D letter code options are equivalent to the ON and OFF arguments; the opening parenthesis is mandatory. Specify either ON or OFF or (I or (D, not both.
The INFORM option sets @SYSTEM.RETURN.CODE to the current date format setting: 0 (USA date order) or 1 (international date order).
For further details, refer to the DATE.FORMAT section of the Operational Differences between MultiValue and Caché manual.
See Also: DATE
DECATALOG
The DECATALOG command removes one or more cataloged programs from the VOC.
DECATALOG filename [itemspec] [(AGLNV]
DECATALOG may be run against the VOC or against a file of MVBasic source code. When run against the VOC, it deletes the specified VOC item, as well as any copies generated for normal catalog. If run against a source file, it deletes any catalog pointers for the specified file, as well as normal and global catalog copies. If you specify the A option, it also deletes the compilation object code.
filename is the file to search for the MVBasic program. The filename is the name of an existing file, which is created as a Caché global (^filename). The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify accountname if the file is located in an account other than the current account. Specify datasection if the cataloged program is stored in a named data section of the file.
itemspec is the name of the program (or programs) to decatalog. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all programs in the file should be decataloged. If itemspec is omitted, DECATALOG uses the active select list as the source of program names. If there is no active select list, DECATALOG issues a “Item Id:” user prompt. Upon successful completion DECATALOG lists the item IDs of the MVBasic programs decataloged.
If the filename file doesn't exist DECATALOG generates a [201] error message. If you specify an MVBasic file as filename and the specified itemspec item doesn't exist in that file DECATALOG generates a [202] error message. If you specify VOC as filename and the specified itemspec item isn’t currently catalogued in the VOC, DECATALOG generates a [202] error message. However, if the specified itemspec item has already been decataloged from an MVBasic file, DECATALOG completes without error.
If specified, a letter code option must be prefaced by an open parenthesis. The available letter codes are: (A = delete all, (G = Global Catalog, (L = Local Catalog, (N = Normal Catalog, and (V = verbose mode. If you specify the (G letter code, DECATALOG looks first in the global catalog for the specified itemspec programName, and deletes it if found. If not found, DECATALOG then looks in the global catalog for *currentaccount*programName and deletes it. For further details on G, L, and N letter code options, refer to the CATALOG command. The default is Local Catalog.
See Also: CATALOG
DELETE
The DELETE command deletes one or more items from a file.
DELETE filename [itemspec]
DELETE deletes the source code for one or more items. It does not delete the item’s compiled object code or remove the item’s catalog listing. Therefore, it is possible to execute a MVBasic program after you have deleted it.
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist DELETE returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify accountname if the file is located in an account other than the current account. Specify datasection if the item to be deleted is stored in a named data section.
itemspec specifies an item, or a list of items, to delete. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all items in the file should be deleted. If itemspec is omitted, DELETE uses the active select list as the source of item names to delete. If there is no active select list, DELETE issues a “Item Id:” user prompt.
If item is not present in the file, DELETE generates a [202] error message. If no items are deleted [430] is returned. If one item is deleted [431] is returned. If more than one item is deleted [432] is returned.
See Also: CLEAR.FILE, DELETE.FILE
DELETE.ACCOUNT
The DELETE.ACCOUNT command deletes an account (namespace) and all of the MultiValue files within it.
DELETE.ACCOUNT account
account is an existing MultiValue account name, which has been assigned to a corresponding Caché namespace. DELETE.ACCOUNT deletes all of the MultiValue globals and routines found in account, and, if the namespace is empty, deletes account. DELETE.ACCOUNT does not delete globals or routines in the namespace that were not created by MultiValue operations. If the account is not associated with a namespace (for example, a synonym account) an error message is returned.
This is a restricted command. You must be logged in to the SYSPROG account to delete an account; use the LOGTO command to log in to SYSPROG. You cannot delete the SYSPROG account, which is the %SYS namespace. Attempting to do so returns a [196] error message.
Account creation and deletion requires %Admin_Manage privileges. This is normally associated with the SYSPROG account (the %SYS namespace). For information on the Caché security model, see the Caché Security Administration Guide. For specific information on roles and privileges, please consult the chapters on Roles and Privileges and Permissions.
See Also: CREATE.ACCOUNT, LOGTO
DELETE.FILE
The DELETE.FILE command deletes a file and its VOC entry.
DELETE.FILE [DATA | DICT] [accountname,]filename[,datasection]
The filename is the name of an existing file, which was created as a Caché global (^filename) by CREATE.FILE or CREATE.BFILE. The file may consist of a dictionary (DICT) and a data section, or be only a data file or only a dictionary file. By default, DELETE.FILE deletes both the dictionary and the data section, and deletes the corresponding VOC entry.
The optional DICT and DATA keywords enable you delete just the dictionary (DICT) or just the data (DATA) section. These keywords also update the corresponding VOC entry. Unlike most file commands, the default is to delete both DICT and DATA.
By default, DELETE.FILE deletes the data section regardless of whether it is the default data section or a named data section. If you specify the DATA keyword, you must specify datasection to delete a named data section. If you specify datasection, DELETE.FILE only deletes the file if it has a corresponding named data section. Otherwise it returns a [206] error. To explicitly delete a default data section, specify filename,filename. You cannot specify both the DICT keyword and a datasection; doing so returns a [424] error.
You can use accountname to delete a file in an account other than the current account.
If filename is a single level file, you can delete it using either DELETE.FILE filename or DELETE.FILE DICT filename. You cannot delete a single level file using DELETE.FILE DATA filename. Refer to CREATE.FILE for further details.
See Also: CLEAR.FILE, CREATE.BFILE, CREATE.FILE, DELETE
DELETE.INDEX
The DELETE.INDEX command deletes one or more indexes on a file.
DELETE.INDEX filename {indexfield [indexfield2] [...] | * | ALL}
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist DELETE.INDEX returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the index to be deleted is stored in a named data section.
The indexfield is the name of a field used as a secondary index key. Specifying indexfield deletes the index named indexindexfield. DELETE.INDEX matches indexfield by searching the following (in this order): an index of that name; a property having the MVNAME parameter of that name; a property of that name. If the indexfield field cannot be matched or has not been indexed, DELETE.INDEX returns a [212] error message.
You can specify multiple indexfield indexes separated by blank spaces. You can delete all indexes for filename by specifying either an asterisk (*) or the ALL keyword. If you do not specify either indexfield, *, or ALL, DELETE.INDEX returns a [211] error message.
You can define indexes either by using CREATE.INDEX or by manually defining them in the class definition for the file. DELETE.INDEX can delete indexes by indexfield name, MVNAME, or property name. However, if you manually define indexes in a class, it is preferable to avoid the use of DELETE.INDEX on that file to avoid any unintended deletions.
If you delete an index on a file that is currently open, you must close and reopen the file for MultiValue to be aware of the index deletion. This close/reopen is required for Caché MultiValue, UniVerse emulation, and jBASE emulation.
For further details, refer to the CREATE.INDEX section of the Operational Differences between MultiValue and Caché manual.
See Also: CREATE.INDEX, LIST.INDEX
DELETE.LIST
The DELETE.LIST command deletes a select list from the &SAVEDLISTS& file.
DELETE.LIST listname | *
The listname is the name of an existing select list in &SAVEDLISTS&. The asterisk (*) argument deletes all select lists in &SAVEDLISTS&. Caché stores the &SAVEDLISTS& file using the ^SAVEDLISTS global.
See Also: COPY.LIST
DELETE.TRIGGER
The DELETE.TRIGGER command deletes a specified type of trigger from a file. It removes the trigger specification, not the trigger subroutine itself.
DELETE.TRIGGER filename event
The filename is the name of an existing file. The event is one of the following: *, POSTOPEN, PREREAD, PREINSERT, PREUPDATE, PREWRITE, PREDELETE, PRECLEAR, POSTREAD, POSTINSERT, POSTUPDATE, POSTWRITE, POSTDELETE, POSTCLEAR. To delete all triggers of any type, specify an asterisk (*) as the event value.
Specifying a valid filename and event returns a [828] message, indicating that the trigger has been deleted, even if the specified trigger does not exist. Specifying an invalid filename returns a [201] message. Specifying an invalid event returns a [824] message.
Caché stores pointers to trigger code in the data file header. When a file is opened, that information is stored in the file pointer. If a trigger is added or deleted while the file is open, the system attempts to follow the trigger definitions that existed when the file was opened. This usually results in a new trigger not firing..
See Also: CREATE.TRIGGER
DISPLAY
The DISPLAY command displays a line of text on the terminal screen.
DISPLAY [text]
The text is displayed exactly as specified. If text is enclosed with delimiters, these delimiters are displayed as part of the text. No parsing of expressions or conversion of numbers to canonical form is performed. If text is omitted, this command displays the empty string (a blank line).
DOS
On Windows systems, the DOS command executes a Windows DOS command.
DOS [commandline] DOS -c "commandline"
The DOS command enters the DOS command prompt environment without exiting the MultiValue Shell. Results are displayed to the MultiValue Shell. No additional windows are opened.
DOS with no argument opens an interactive command prompt from which you can issue multiple DOS commands. To exit this command prompt and return to the MultiValue Shell, issue the Windows EXIT command.
DOS commandline issues a Windows command as a background process. The commandline can be any valid Windows command line. A commandline cannot be specified as a variable, nor can it be enclosed in quotation marks. A commandline cannot exceed 248 characters in length. Upon completion it returns to the MultiValue Shell prompt.
The DOS -c "commandline" alternate syntax is equivalent to DOS commandline. This syntax is provided for UniVerse compatibility. The double quotes enclosing the commandline are mandatory.
The SH command is similar to DOS, but can also be issued in non-Windows environments. On Windows systems, the DOS and SH commands are synonyms.
On Windows systems you can use DOS set (or SH set) to display a list of environment variables. To display individual environment variables, you can use the MVBasic GETENV() function.
ED
The ED command allows you to edit a record in a file.
ED filename itemspec
ED is the MultiValue line editor. Caché MultiValue supports the ED and JED editors.
The filename is the name of the file to edit, which is created as a Caché global (^filename). If the specified filename is not valid, ED returns a [201] message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the program to be edited is stored in a named data section of the file.
itemspec specifies a record, or a list of records, to edit. If you specify multiple records, ED starts with the first item you specified. When you exit editing of that item, ED accesses the next item in the specified order. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all records in the file should be edited. If itemspec is omitted, ED uses the active select list as the source of record names to edit.
If item is an existing record, ED positions the current line pointer to the beginning of this record. If item is not an existing record, ED creates the specified record.
When ED creates or accesses an item it updates the @RECORD special variable.
The ED command provides a prompt for editing the current record. You can issue a variety of subcommands at the ED prompt. For a list of these subcommands, specify HELP at the ED prompt. For a list of the attributes of the specified record, specify ? at the ED prompt.
The following is a list of the ED subcommands supported by Caché:
-nnn Decrement current line pointer. +nnn Increment current line pointer. ? Display information about the record. ^ Toggle the up-arrow display mode. < Set marker for the FROM lines. > Set marker for the THROUGH lines. ! command Execute a MV shell command. # command Execute a COS shell command. nnn Set current line pointer. A text Append text to end of line. B Set current line pointer to Bottom of record. B string Break line at position of string. BLOCK Toggle the BLOCK verification. C Repeat change/replace. C/from/to/[Gnn] Change string 'from' with 'to'. COPY Copy a BLOCK of lines. D[nn] Delete one or more lines of text. DE[nn] Delete one or more lines of text. DELETE Delete the record from the file. DROP Drop (delete) a BLOCK of lines. EX[KO] Exit editing this record. FD[KO] Delete the record from the file. F[[col] string] Find a string at a specified column. FI[K] File record and exit editing this record. FILE File record and exit editing this record. FORMAT [n[m]] Format BASIC code, tab stop n , initial level m. FS File record and continue editing this record. G[nnn] Go to line nnn, or next line. G< Go to beginning of the current BLOCK. G> Go to end of the current BLOCK. HELP Display help screen. HEX Toggle HEX input/output mode. I[string] Insert mode or insert string at current line pointer. IB[string] Insert before mode or insert string before current line. L Repeat locate (or list one line if no previous locate). L string Locate next occurrence of string. Lnnn List the next nnn lines. Lnnn string Locate all strings in the next nnn lines. LOAD [file] id Load lines of code from another item. MOVE Move a BLOCK of lines. OOPS Undo the previous command. P[n] Execute prestore command n. P[n] Cmd1[<ESC>Cmd2] Set prestore command n. PP[nn] Page Print for nn lines. Q Exit editing this record. QUIT Exit editing this record. R Repeat replace. R newtext Replace entire line with 'newtext'. R/from/to/[Gnn] Replace string 'from' with 'to'. SIZE Display information about size of record. TB n[,n...] Set tab stop position. T Set current line pointer to Top of record. U[nn] Move up nn lines. UNDO Undo the previous command. UNLOAD [file] id Save lines of code to another item. X Exit editing this record and return to command line. XEQ command Execute a MV shell command.
Additional notes on subcommands:
-
DE: When you delete a line of code, the current line pointer moves upward. Following a line delete, ED displays the current line. As this current line pointer behavior is not consistent across all MultiValue systems, exercise caution when performing repeated line deletions.
-
F: This subcommand finds the first instance of the specified string occurring at the specified col (column number). Note that there is no space between F and the column number (for example, F4 bscan). If col is omitted, the default is column number 1. If col and string are omitted, the previous F command is repeated.
-
FIBCR: This subcommand performs a series of operations. It (FI) files the item, (B) compiles the Basic source, (C) catalogs the object code, and finally (R) runs the command. If any one of these steps fails, the subsequent steps are not attempted.
-
HEX: A mode toggle to turn on or off display of text in hexadecimal. HEX mode only affects character display and the I (insert) subcommand; it does not affect other subcommands.
-
I: To insert a blank line, specify the I subcommand followed by a blank space. To insert a hexadecimal value, go into HEX mode. To insert an @VM character (CHAR(253)) specify Ctrl-]. To insert an @SM character (CHAR(252)) specify Ctrl-\.
-
I and R: You can use the ^ (caret) code operator in an insert (I) or replace (R) subcommand to specify a single character by its integer code (values 000 through 255). This is commonly used for non-printable control code characters. This can be used to specify a MultiValue delimiter, such as ^253 for a value mark. However, you cannot specify a ^254, because this specifies a field mark. This use of ^ is disabled by default, and must be enabled.
-
P: The Prestore subcommand enables you to assign a single-digit integer to a series of one or more commands. The format is P# command1<ESC>command2<ESC>command3 and so forth. The # is the assigned single-digit integer value, followed by an associated command. Additional commands can be added by separating the commands with an Escape character (<ESC>). This Escape character typed using ED is echoed (displayed) as "[".
An Escape character typed using ED is echoed (displayed) as "[".
You can use the Up and Down arrow keys to scroll through the ED subcommands history for the current editing session.
To abort ED and release all locks, use Ctrl-C. Any time you exit ED, it clears select list 0.
ED is a simple line editor, a subset of the line editors supplied with other MultiValue systems. For more complex editing, the user should use the Studio.
The ED and EDIT commands are synonyms.
See Also: CREATE.FILE, EDIT, EDIT.LIST, JED
EDIT
The EDIT command allows you to edit a record in a file.
EDIT filename itemspec
The EDIT and ED commands are synonyms.
See Also: ED
EDIT.LIST
The EDIT.LIST command allows you to edit a select list in &SAVEDLISTS&.
EDIT.LIST [listname]
EDIT.LIST allows you to create or modify a select list, using the Caché MultiValue command line editor (ED) prompts. EDIT.LIST is the same as ED &SAVEDLISTS& recID, where recID is the record ID of a saved list. If you do not specify a listname, you are prompted to supply one. Caché stores the &SAVEDLISTS& file using the ^SAVEDLISTS global.
See Also: ED
ENABLE.BREAK.KEY
The ENABLE.BREAK.KEY and BREAK ON commands are functionally identical.
FORM.LIST
The FORM.LIST command allows you to create a select list from elements stored in a record.
FORM.LIST [filename] [recID] TO [listnum]
FORM.LIST take the record identified by recID from filename, and uses it to create a numbered select list listnum. If you omit filename or recID you are prompted to supply one. Select lists are numbered 0 through 10; if the TO listnum argument is omitted, it defaults to select list 0.
See Also: GET.LIST
GET.LIST
The GET.LIST command copies the specified named select list into a numbered select list.
GET.LIST listname [TO n]
The listname argument specifies a named select list. The optional TO n argument is a select list number in the range 0 through 10 (inclusive); if omitted, select list 0 is the default.
If n is out of range, GET.LIST returns a [209] message.
GET.LIST is the inverse of SAVE.LIST. When a select list is saved it becomes unavailable to the MVBasic READNEXT command. To make a select list available again, use GET.LIST.
To copy Select List 0 to another numbered select list, use the PQ.SELECT command.
See Also: PQ.SELECT, SAVE.LIST
HUSH
The HUSH command suppresses terminal screen display. It suppresses all terminal display, including displaying the terminal prompt.
HUSH [ON | OFF]
Specifying HUSH with no operand toggles display suppression. HUSH ON suppresses display. HUSH OFF re-enables display.
The KEYS command temporarily overrides the HUSH. However, when KEYS times out, it returns to the prior HUSH mode. This may be mistaken for a hang state.
The HUSH and P commands are synonyms.
ICOMP
The ICOMP command compiles the I-type dictionary definitions in the specified file.
ICOMP [DATA] filename [itemspec]
ICOMP compiles the I-type dictionary definitions in filename. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
ICOMP by default references the DICT file. If you wish to compile I-types in the data portion of a file, specify the optional DATA keyword. This is most commonly used when compiling the VOC. The default is to compile in the dictionary portion.
itemspec is the name of an I-type item, or a list of items, to compile. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all I-type items in the file should be compiled. If itemspec is omitted, ICOMP uses the active select list as the source of I-type item names.
As each item is accessed, ICOMP updates the @RECORD special variable.
See Also: COMPILE.DICT, ICOMP.ALL
ICOMP.ALL
The ICOMP.ALL command compiles all the I-type dictionary definitions in one or more accounts.
ICOMP.ALL [accountname] [(AV]
ICOMP.ALL with no arguments compiles all the I-type dictionary definitions in the current account (namespace). ICOMP.ALL with the optional accountname argument compiles all the I-type dictionary definitions in the specified account (namespace). ICOMP.ALL with the (A letter code option compiles all the I-type dictionary definitions in all accounts (namespaces). It lists the accounts as it performs the compile. If you specify both accountname and the (A option, the accountname is ignored and all accounts are compiled. The (V letter code option returns verbose output while the compile operation executes.
ICOMP.ALL continues to compile I-types despite errors; it reports successful compiles and errors as they occur. Upon successful compile ICOMP.ALL generates a [7140] message specifying how many I-types compiled without error. If errors occurred during the compile of an I-type file, it generates a [7141] error message, listing the number of I-types compiled, the number of errors, and the file containing the I-types. If a dictionary item contains a syntax error, ICOMP.ALL generates a [7107] error message.
See Also: ICOMP
JED
The JED command allows you to edit a record in a file.
JED filename [item]
The JED command provides a full-screen editor similar to the editor supplied with jBASE. Caché MultiValue supports the ED and JED editors.
ED is the preferred editor for Caché MultiValue. JED is provided for compatibility only.
The filename is the name of the file to edit, which is created as a Caché global (^filename). If the specified filename is not valid, JED returns a [201] message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the program to be edited is stored in a named data section of the file.
If item is an existing record, JED positions the current line pointer to the beginning of this record. If item is not an existing record, JED creates the specified record. If item is omitted, JED prompts you for the item name.
When JED creates or accesses an item it updates the @RECORD special variable.
See Also: ED
JOBS
The JOBS command list all running phantom processes initiated by the current process.
JOBS
JOBS lists all running processes initiated by the current process; LIST.JOB lists all running processes. You can use the PHANTOM command to initiate a phantom process.
KEYS
The KEYS command sets the terminal into a mode in which each keyboard input character is displayed, along with its hexadecimal and ASCII base-10 equivalents. Compound keys (for example, the F1 key) return their component characters, one line per character. The KEYS command is designed to display all characters, including those that would normally terminate input. For this reason, the only way to exit KEYS mode is by timing out. This mode terminates automatically after 10 seconds of inactivity.
KEYS
The KEYS mode overrides the HUSH mode. However, when KEYS times out, it returns to the prior HUSH mode. This may be mistaken for a hang state.
For further details, refer to the Terminal Input chapter of the Caché MV Terminal Independence manual.
LIST
The LIST command returns a list of items that satisfy the query criteria.
LIST [DICT] filename [field1 [field2 ...]] [dict [dict2 ...] | ALL] [query] [(CDEFHINPYZ]
LIST returns a formatted display listing the items selected from a file. At the end of the listing the total number of items listed is returned. LIST is a Caché MultiValue SQL (CMQL) query command.
The optional DICT keyword causes the command to access the DICT entries in the filename dictionary file; otherwise, filename is assumed to be a data file. If there are multiple defined data sections (data files), you can specify filename as filename,datasection. The DICT keyword and field arguments are mutually exclusive.
The optional field arguments permit you to specify which data fields to list. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. Item IDs correspond to the @ID (VOC) dictionary entry value. If you omit the field argument, all fields in filename are listed. By default, LIST lists field items in the order that you specify them. By default, the SORT command lists field items in ascending collation sequence.
The optional dict arguments permit you to specify which DICT entries to list for each field. You can specify one or more dict entry names separated by blank spaces. DICT entry names are not enclosed with quote characters. If you omit the dict argument, only the @ID (VOC) dictionary entry for each field is listed.
If you specify ALL, all the dict attribute values for each field are listed; this is similar to LIST.ITEM. In all cases, the @ID (VOC) dictionary entry is automatically listed by default.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(C or COL-HDR-SUPP suppresses both the default page header and the column headers. COL.HDR.SUPP (note two P’s) is a synonym for COL-HDR-SUPP.
-
(D or DET-SUPP suppresses detail listings. DET.SUP is a synonym for DET-SUPP.
-
(E prevents the listing of data in vertical format when listing more than five dict items. Listing remains in horizontal format, regardless of width. This is the opposite of VERT.
-
(F suppresses “not on file” message generation. Because select lists are implemented as SQL joins that only return rows that are in both the select list and the file, Caché MultiValue compares each item in the list with the file; items that don’t match are added to the error list, unless suppressed using this option.
-
(H or HDR-SUPP suppresses the default page header. It does not suppress a page header specified using the HEADING clause. HDR.SUP and SUPP are synonyms for HDR-SUPP.
-
(I or ID-SUPP suppresses listing the @ID field. ID-SUP and ID.SUP are synonyms for ID-SUPP.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LIST operation.
-
field COL.HDG name substitutes the specified name for the default field name. Delimit name with double quotes or backslash characters. DISPLAY.NAME is a synonym for COL.HDG.
-
COL-SUPP suppresses the column headers. COL.SUP is a synonym for COL-SUPP.
-
DBL-SPC displays data listed in horizontal format as double-spaced. The default is single-spaced. DBL.SPC is a synonym for DBL-SPC.
-
NI-SUPP suppresses the total item count at the end of the listing. NI.SUP and COUNT.SUP are synonyms for NI-SUPP.
-
VERT displays listed data in vertical format. The default is to list data in horizontal format when listing five or fewer dict items, and vertical format when listing more than five dict items. VERTICALLY is a synonym for VERT.
After listing each full page of items, LIST issues a prompt to the user to display the next page, unless you specified (N. To terminate a listing before reaching its end, specify Q at the display prompt. At the end of the listing, LIST specifies the total number of items listed, unless you specify NI-SUPP to suppress this total count.
See Also: COUNT, CT, LIST.ITEM, LIST.LABEL, LISTDICT LISTF, SELECT, SORT, STAT
LIST.INDEX
The LIST.INDEX command lists the indices defined for the specified file.
LIST.INDEX filename [index | ALL] (D
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist LIST.INDEX returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the index to be listed is stored in a named data section.
If the specified filename has no defined indices, LIST.INDEX returns an [842] error message.
You can list a specific index, or list all indices defined for the specified file. Note that LIST.INDEX lists indices of all types, including bitmapped indices. The Caché MVBasic index commands do not handle bitmapped indices.
The (D letter code option lists details about each index.
Note that LIST.INDEX has a VOC Attribute 3 value of "M", indicating that it is a Caché class method. See the %MV.Verbs.ListIndex()Opens in a new tab method in the InterSystems Class Reference.
See Also: CREATE.INDEX
LIST.ITEM
The LIST.ITEM command lists fields with their attributes.
LIST.ITEM [DICT] filename [field1 [field2 ...]] [query] [(DFHNPYZ]
LIST.ITEM can return field attributes from all of the fields of a file, for one or more specified fields, or for fields selected by a query. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. The attributes of an item are presented as numbered lines. If the field is an MVBasic program, the attributes are the numbered lines of the program.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order.
The following are supported letter code and keyword options:
-
(D or DET-SUPP suppresses detail listings. DET.SUP is a synonym for DET-SUPP.
-
(F suppresses “not on file” message generation. Because select lists are implemented as SQL joins that only return rows that are in both the select list and the file, Caché MultiValue compares each item in the list with the file; items that don’t match are added to the error list, unless suppressed using this option.
-
(H or HDR-SUPP suppresses the default page header. It does not suppress a page header specified using the HEADING clause. HDR.SUP and SUPP are synonyms for HDR-SUPP.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LIST.ITEM operation.
-
NI-SUPP suppresses the total item count at the end of the listing. NI.SUP and COUNT.SUP are synonyms for NI-SUPP.
After listing each full page of items, LIST.ITEM issues a prompt to the user to input a character to display the next page, unless you specified (N. This prompted character is not echoed on the list display, regardless of the MultiValue emulation. To terminate a listing before reaching its end, specify Q at the display prompt. At the end of the listing, LIST.ITEM specifies the total number of items listed, unless you specify NI-SUPP to suppress this total count.
LIST.ITEM returns fields and their attributes in the order presented. To return fields in alphabetical order, use SORT.ITEM.
See Also: LIST, SELECT, SORT.ITEM
LIST.JOB
The LIST.JOB command displays a table listing all running phantom processes.
LIST.JOB
LIST.JOB lists all running processes; JOBS lists all running processes initiated by the current process.
See Also: JOBS
LIST.LABEL
The LIST.LABEL command list values returned from a file in a display format that you specify. One use of this command is to format data for mailing labels.
LIST.LABEL [DICT] filename [field1 [field2 ...]] [query] [(DFNPYZ]
LIST.LABEL can either format all fields in the file, the specified fields from the file, or the fields from a file selected using a Caché MultiValue SQL (CMQL) query. LIST.LABEL prompts you to specify a display format with the following prompt: COUNT, ROWS, SKIP, INDENT, SIZE, SPACE {,C}?. You respond to this prompt with a comma-separated series of integers that describe the display format. The simplest prompt response is 1,1, which means one item per line (COUNT), and one line space per line (ROWS). Format 1,1 is the same format as the LIST command. More complex display formats are described below.
By default, LIST.LABEL does not display a page header or footer. You can specify a page header using the HEADING clause. You can specify a page footer using the FOOTING clause.
The optional DICT keyword causes the command to access the DICT entries in the filename dictionary file; otherwise, filename is assumed to be a data file. If there are multiple defined data sections (data files), you can specify filename as filename,datasection.
The optional field arguments permit you to specify which fields to list. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. If you omit the field argument all fields in the file are listed.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(D or DET-SUPP suppresses detail listings. DET.SUP is a synonym for DET-SUPP.
-
(F suppresses “not on file” message generation. Because select lists are implemented as SQL joins that only return rows that are in both the select list and the file, Caché MultiValue compares each item in the list with the file; items that don’t match are added to the error list, unless suppressed using this option.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LIST.LABEL operation.
After listing each full page of items, LIST.LABEL issues a prompt to the user to input a character to display the next page, unless you specified (N. This prompted character is not echoed on the list display, regardless of the MultiValue emulation. To terminate a listing before reaching its end, specify Q at the display prompt.
The following are the prompt values used to specify display format:
COUNT | Number of fields per row, specified as an integer. This value is mandatory, the minimum value is 1. |
ROWS | Number of rows per “label” specified as an integer. This value is mandatory, the minimum value is 1. Commonly this is equivalent to vertical line spacing. |
SKIP | Optional — Number of blank lines between “labels” specified as an integer. Commonly this is equivalent to vertical line spacing. The default is 0. |
INDENT | Optional — Left indent, in character spaces, specified as an integer. The default is 0. |
SIZE | Optional — If COUNT>1, specifies how many character spaces to allocate for each item on the line, specified as an integer. If SIZE is larger than an actual field value, blank spaces are appended to comprise the total SIZE; if SIZE is smaller than an actual field value, fields are concatenated and no blank spaces are appended. The default is 0. |
SPACE | Optional — If COUNT>1, specifies how many character spaces to allocate for each item on the line, specified as an integer. If SPACE is larger than an actual field value, blank spaces are appended to comprise the total SPACE; if SPACE is smaller than an actual field value, fields are concatenated and no blank spaces are appended. SIZE and SPACE are added together. The default is 0. |
C | Optional — The letter C code character. If COUNT>1, specifies do not print empty fields. The default is to print an empty field as SIZE+SPACE blank spaces. |
See Also: LIST, SORT.LABEL
LIST.LOCKS
The LIST.LOCKS command displays a table listing the current locks. It list both system locks and locks established by the current process.
LIST.LOCKS
For all locks, LIST.LOCKS lists the process ID of the process holding the lock and the lock type (X (exclusive) or S (shared)). Locks established using the MVBasic LOCK command are displayed as LOCK nnn. Locks established by opening a sequential file are displayed as FILE filename. Other locks display the lock global variable and its complete pathname.
See Also: CLEAR.LOCKS
LIST.TRIGGER
The LIST.TRIGGER command lists the triggers defined for the specified file.
LIST.TRIGGER filename
It lists each trigger in the following format: event = file subroutine. For example: PREREAD = BP TRTN.
See Also: CREATE.TRIGGER
LISTDICT
The LISTDICT command displays a table listing the file’s dictionary entries.
LISTDICT filename
LISTDICT displays the DICT entries in the filename dictionary file as a table. This is similar to LIST DICT filename, but differs in presentation format.
Note that LISTDICT has a VOC Attribute 3 value of "M", indicating that it is a Caché class method. See the %MV.Verbs.ListDict()Opens in a new tab method in the InterSystems Class Reference.
See Also: LIST
LISTF
The LISTF command lists the MultiValue files in the VOC.
LISTF [field [field2 ...]] [ALL] [query] [(CDEHNPYZ]
For each file in the VOC, LISTF lists the file name, the file type (F or Q), the corresponding data file global, and the corresponding dictionary file global. By default, LISTF begins its listing with the current date and time, and ends its listing with the total number of files listed.
If you CATALOG a compiled MVBasic file, that file appears in the LISTF listing as file type F. Note that file names are case-sensitive and listed in ASCII order (uppercase letters are listed before lowercase letters).
The optional field arguments permit you to specify which file fields to list. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. By default, fields are listed in ascending collation order. If you omit the field argument all file fields are listed. If you specify ALL, all the attribute values for each field are listed; this is similar to LIST.ITEM.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. Note that the first conditional clause cannot be specified as a WITH clause; it must be specified either as a WHEN clause, or with no conditional clause keyword. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(C or COL-HDR-SUPP suppresses both the default page header and the column headers. COL.HDR.SUPP (note two P’s) is a synonym for COL-HDR-SUPP.
-
(D or DET-SUPP suppresses detail listings. DET.SUP is a synonym for DET-SUPP.
-
(E prevents the listing of data in vertical format. Listing remains in horizontal format, regardless of width. This is the opposite of VERT.
-
(H or HDR-SUPP suppresses the default page header. It does not suppress a page header specified using the HEADING clause. HDR.SUP and SUPP are synonyms for HDR-SUPP.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LISTF operation.
-
field COL.HDG name substitutes the specified name for the default field name. Delimit name with double quotes or backslash characters. DISPLAY.NAME is a synonym for COL.HDG.
-
COL-SUPP suppresses the column headers. COL.SUP is a synonym for COL-SUPP.
-
DBL-SPC displays data listed in horizontal format as double-spaced. The default is single-spaced. DBL.SPC is a synonym for DBL-SPC.
-
NI-SUPP suppresses the total item count at the end of the listing. NI.SUP and COUNT.SUP are synonyms for NI-SUPP.
-
VERT displays listed data in vertical format. The default is to list data in horizontal format when listing five or fewer dict items, and vertical format when listing more than five dict items. VERTICALLY is a synonym for VERT.
After listing each full page of items, LISTF issues a prompt to the user to input a character to display the next page, unless you specified (N. This prompted character is not echoed on the list display, regardless of the MultiValue emulation. To terminate a listing before reaching its end, specify Q at the display prompt.
You can use SET.FILE to create a Q-type file.
See Also: LIST
LISTME
The LISTME command displays a table listing the current MultiValue user processes.
LISTME
For each user process, LISTME lists the process ID (pid), the port number, the date and time of initialization of the MV Shell, and the username. The current process is indicated by an asterisk preceding the pid number.
This listing is initiated by displaying a header, and concludes with a count of the number of items listed.
After listing each full page of items, LISTME issues a prompt to the user to input a character to display the next page. To terminate listing, input the letter Q at the display prompt. This prompted character is not echoed on the list display, regardless of the MultiValue emulation.
The LISTME command returns the same information as the LISTU and STATUS commands. However, LISTME can only list processes when invoked from the USER account. LISTU and STATUS list all active processes when invoked from any account.
See Also: LISTU, LOGOFF, STATUS, WHERE
LISTPA
The LISTPA command lists the paragraphs in the VOC.
LISTPA [field [field2 ...]] [ALL] [query] [(CDEINPYZ]
LISTPA is supported for the D3, IN2, jBASE, MVBase, PICK, R83, POWER95, Reality, and Ultimate emulations. Caché MultiValue and the INFORMATION, PIOpen, Prime, UniData, and UniVerse emulations return no data from this command.
For each paragraph field in the VOC, LISTPA lists @ID, F1, and F2. F1 is always “PA”. If no paragraphs exist (or this command is not supported in the current emulation), it returns a [401] message.
The optional field arguments permit you to specify which paragraph fields to list. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. By default, fields are listed in ascending collation order. If you omit the field argument all paragraph fields are listed. If field does not exist, or is not a paragraph field, a “not found” message is returned for that item.
If you specify ALL, all the attribute values for each field are listed. This is similar to LIST.ITEM.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. Note that the first conditional clause cannot be specified as a WITH clause; it must be specified either as a WHEN clause, or with no conditional clause keyword. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(C or COL-SUPP suppresses the column headers. COL.SUP is a synonym for COL-SUPP.
-
(D or DET-SUPP suppresses detail listings. DET.SUP is a synonym for DET-SUPP.
-
(E prevents the listing of data in vertical format. Listing remains in horizontal format, regardless of width. This is the opposite of VERT.
-
(I or ID-SUPP suppresses listing the @ID field. ID-SUP and ID.SUP are synonyms for ID-SUPP.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LISTPA operation.
-
field COL.HDG name substitutes the specified name for the default field name. Delimit name with double quotes or backslash characters. DISPLAY.NAME is a synonym for COL.HDG.
-
DBL-SPC displays data listed in horizontal format as double-spaced. The default is single-spaced. DBL.SPC is a synonym for DBL-SPC.
-
NI-SUPP suppresses the total item count at the end of the listing. NI.SUP and COUNT.SUP are synonyms for NI-SUPP.
-
VERT displays listed data in vertical format. The default is to list data in horizontal format when listing five or fewer dict items, and vertical format when listing more than five dict items. VERTICALLY is a synonym for VERT.
LISTPEQS
The LISTPEQS command displays a table listing the printer queue elements and their status.
LISTPEQS ["account"] [jobno[-jobno]] [(ACF]
The optional account argument allows you limit display to only the elements assigned to a specific account. account is case-sensitive, and must be specified as a quoted string. The optional jobno argument allows you to specify a single print job number, or a range of print jobs.
The (ACF options consist of one or more of these letter codes in any order, preceded by an open parenthesis. The letter codes have the following meaning: A=display only jobs created by the current account. C=do not display detailed information, just return the total number of queue elements and pages in use. F=sort the display by form queue number.
See Also: LISTPTR, SPOOL, SP.DELETE, SP-EDIT
LISTPH
The LISTPH command lists the phrases in the VOC.
LISTPH [field [field2 ...]] [ALL] [query] [(CDEINPYZ]
LISTPH is supported for the D3, IN2, jBASE, MVBase, PICK, R83, POWER95, Reality, and Ultimate emulations. Caché MultiValue and the INFORMATION, PIOpen, Prime, UniData, and UniVerse emulations return no data from this command.
For each phrase field in the VOC, LISTPH lists @ID, F1, and F2. F1 is always “PH”. If no phrases exist (or this command is not supported in the current emulation), it returns a [401] message.
The optional field arguments permit you to specify which phrase fields to list. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. By default, fields are listed in ascending collation order. If you omit the field argument all phrase fields are listed. If field does not exist, or is not a phrase field, a “not found” message is returned for that item.
If you specify ALL, all the attribute values for each field are listed. This is similar to LIST.ITEM.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. Note that the first conditional clause cannot be specified as a WITH clause; it must be specified either as a WHEN clause, or with no conditional clause keyword. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(C or COL-SUPP suppresses the column headers. COL.SUP is a synonym for COL-SUPP.
-
(D or DET-SUPP suppresses detail listings. DET.SUP is a synonym for DET-SUPP.
-
(E prevents the listing of data in vertical format. Listing remains in horizontal format, regardless of width. This is the opposite of VERT.
-
(I or ID-SUPP suppresses listing the @ID field. ID-SUP and ID.SUP are synonyms for ID-SUPP.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LISTPH operation.
-
field COL.HDG name substitutes the specified name for the default field name. Delimit name with double quotes or backslash characters. DISPLAY.NAME is a synonym for COL.HDG.
-
DBL-SPC displays data listed in horizontal format as double-spaced. The default is single-spaced. DBL.SPC is a synonym for DBL-SPC.
-
NI-SUPP suppresses the total item count at the end of the listing. NI.SUP and COUNT.SUP are synonyms for NI-SUPP.
-
VERT displays listed data in vertical format. The default is to list data in horizontal format when listing five or fewer dict items, and vertical format when listing more than five dict items. VERTICALLY is a synonym for VERT.
LISTPTR
The LISTPTR command displays a table listing the current printer assignments.
LISTPTR [jobno[-jobno]]
The optional jobno argument allows you to specify a single print job number, or a range of print jobs.
See Also: LISTPEQS
LISTS
The LISTS command lists the sentences in the VOC.
LISTS [field [field2 ...]] [ALL] [query] [(CDEINPYZ]
LISTS is supported for the D3, IN2, jBASE, MVBase, PICK, R83, POWER95, Reality, and Ultimate emulations. Caché MultiValue and the INFORMATION, PIOpen, Prime, UniData, and UniVerse emulations return no data from this command.
For each sentence field in the VOC, LISTS lists @ID, F1, and F2. F1 is always “S”. If no sentences exist (or this command is not supported in the current emulation), it returns a [401] message.
The optional field arguments permit you to specify which sentence fields to list. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. By default, fields are listed in ascending collation order. If you omit the field argument all sentence fields are listed. If field does not exist, or is not a sentence field, a “not found” message is returned for that item.
If you specify ALL, all the attribute values for each field are listed. This is similar to LIST.ITEM.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. Note that the first conditional clause cannot be specified as a WITH clause; it must be specified either as a WHEN clause, or with no conditional clause keyword. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(C or COL-SUPP suppresses the column headers. COL.SUP is a synonym for COL-SUPP.
-
(D or DET-SUPP suppresses detail listings. DET.SUP is a synonym for DET-SUPP.
-
(E prevents the listing of data in vertical format. Listing remains in horizontal format, regardless of width. This is the opposite of VERT.
-
(I or ID-SUPP suppresses listing the @ID field. ID-SUP and ID.SUP are synonyms for ID-SUPP.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LISTS operation.
-
field COL.HDG name substitutes the specified name for the default field name. Delimit name with double quotes or backslash characters. DISPLAY.NAME is a synonym for COL.HDG.
-
DBL-SPC displays data listed in horizontal format as double-spaced. The default is single-spaced. DBL.SPC is a synonym for DBL-SPC.
-
NI-SUPP suppresses the total item count at the end of the listing. NI.SUP and COUNT.SUP are synonyms for NI-SUPP.
-
VERT displays listed data in vertical format. The default is to list data in horizontal format when listing five or fewer dict items, and vertical format when listing more than five dict items. VERTICALLY is a synonym for VERT.
LISTU
The LISTU command lists the current MultiValue user processes.
LISTU
LISTU lists the current MultiValue user processes in port number order. For each user process, LISTU lists the process ID (pid), the port number, the date and time of initialization of the MV Shell, and the username. The current process is indicated by an asterisk preceding the pid number.
This listing is initiated by displaying a header, and concludes with a count of the number of items listed.
After listing each full page of items, LISTU issues a prompt to the user to input a character to display the next page. To terminate listing, input the letter Q at the display prompt. This prompted character is not echoed on the list display, regardless of the MultiValue emulation.
The LISTU and STATUS commands are functionally identical.
See Also: LISTME, LOGOFF, STATUS, WHERE
LOGOFF
The LOGOFF command logs off a current MultiValue user process. You can log off your own current process, or another active process.
LOGOFF portno
Specifying LOGOFF with a port number logs off the MV Shell on the specified user terminal process. When you issue a log off, the terminal process immediately exits the MV Shell and returns to the Caché mode prompt. If you specify an invalid portno, the LOGOFF command completes successfully, performing no operation.
To determine the portno of current user processes, use the WHO command, or the @PORTNO MVBasic system variable.
The LOGOFF and LOGOUT commands are similar.
See Also: LOGOUT, Q, QUIT, WHO
LOGOUT
The LOGOUT command logs off a current MultiValue user process. You can log off your own current process, or another active process.
LOGOUT [pid]
Specifying LOGOUT with no operand logs off the MV Shell on the current terminal process. (You can use the Q or QUIT command to perform the same operation.) Specifying LOGOUT pid logs off the MV Shell on the specified user terminal process. Specifying LOGOUT ALL logs off the MV Shell on all user terminal processes except the current terminal process.
When you issue a log off, the terminal process immediately exits the MV Shell and returns to the Caché mode prompt. If you specify an invalid pid, the LOGOUT command completes successfully, performing no operation.
To determine the pid of current user processes, use the LISTME command.
The LOGOUT and LOGOFF commands are similar.
See Also: LISTME, LOGOFF, Q, QUIT
LOGTO
The LOGTO command changes your MV Shell login to another account (namespace).
LOGTO account
LOGTO changes your current environment to a different account environment. The account must be an existing account/namespace. Each account has its own files, local variables, and emulation setting. The current account is shown as the command line prompt.
If the specified account is not valid (does not exist), LOGTO generates a [229] error. An account may be a Caché namespace; it does not have to be an account created using CREATE.ACCOUNT. The SYSPROG account corresponds to the %SYS namespace. If you are already in the specified account, no operation is performed.
LOGTO causes the MultiValue Shell to search the target account VOC in the following order: an item with the same name as the user, an item with the same name as account, or an item named “LOGIN”. The MultiValue Shell runs the first of these items that it encounters.
Changing to an account means entering the emulation environment established for that account. Refer to CEMU for details. If a &HOLD& file has been created in the old account, LOGTO create a &HOLD& file in the new account. For details on the relationship between accounts and namespaces, and the naming conventions used for each, refer to “MV Accounts and Caché Namespaces” in Operational Differences between MultiValue and Caché.
See Also: CEMU, CREATE.ACCOUNT, WHO
MESSAGE
The MESSAGE command sends a message text to the specified users or processes.
MESSAGE username [username] MESSAGE pid [pid]
Specify one or more usernames or process IDs (pid). Multiple arguments are separated by blank spaces. The MESSAGE command prompts you for a message text. Type the text then press ENTER.
MESSAGE sends the message to all specified users that are currently logged on. It displays “message sent” with username and pid for each valid recipient. It displays “not logged on” for each invalid recipient. usernames are not case-sensitive. Duplicate values are ignored.
See Also: LISTME, LISTU, STATUS, WHO
MVI
The MVI command locates the source code for a MVBasic routine.
MVI [MVB.]routine[.MVI] [linenumber]
MVI allows you to cross reference line numbers from MVBasic intermediate source code (MVI code) to the original MVBasic source code (MVB code). MVI searches for MVB.routine, where routine is a hexadecimal module number assigned to the MVBasic routine when it is compiled. The MVB. prefix and .MVI suffix are both optional. The linenumber corresponds to a line in the MVI code; if you omit linenumber it defaults to line 1. If the specified routine is not located, you may be searching in the wrong account. For further details, refer to the MVI: MVI-To-MVB Cross-Reference section of the Operational Differences between MultiValue and Caché manual.
See Also: BASIC
MVIMPORT
The MVIMPORT command imports accounts from other MultiValue implementations to Caché MultiValue. This command is described in the MVIMPORT chapter of this manual.
NSELECT
The NSELECT command generates a select list of items in the supplied (or default) select list that are not in the file.
NSELECT filename [FROM n] [TO n]
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist NSELECT returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the select list is to be compared with the contents of a named data section.
You can use the FROM clause to specify an existing numeric select list. By combining the FROM and TO clauses you can specify a range of numbered select lists. By default, NSELECT uses select list 0. If there is no active select list, NSELECT returns a [240] message.
See Also: BSELECT, CLEARSELECT, QSELECT, SEARCH, SELECT, SSELECT
OFF
The OFF command logs off your current MultiValue user process.
OFF
Specifying OFF logs off the MV Shell on your user terminal process. When you issue an OFF, the terminal process immediately exits the MV Shell and returns to the Caché mode prompt.
The QUIT, and Q commands are synonyms. The OFF command is functionally identical.
See Also: LOGOFF, LOGOUT, Q, QUIT, WHO
P
The P command suppresses terminal screen display. It suppresses all terminal display, including displaying the terminal prompt.
P [ON | OFF]
Specifying P with no operand toggles display suppression. P ON suppresses display. P OFF re-enables display.
The KEYS command temporarily overrides the P. However, when KEYS times out, it returns to the prior P mode. This may be mistaken for a hang state.
The P and HUSH commands are synonyms.
PAGE.MESSAGE
The PAGE.MESSAGE command displays an end-of-page message on the screen when displaying multi-page output.
PAGE.MESSAGE [ON | OFF]
Specifying PAGE.MESSAGE with no operand returns the current setting. PAGE.MESSAGE ON displays the message “Press any key to continue” at the end of the page and pauses awaiting user response. PAGE.MESSAGE OFF does not display a message; it simply pauses at the end of the page awaiting user response. PAGE.MESSAGE ON is the Caché default. The default may differ in other MultiValue emulations.
PHANTOM
The PHANTOM command starts a phantom process in which to run the specified MultiValue command.
PHANTOM [BRIEF | SQUAWK] command
PHANTOM initiates a phantom (background) process. It does not validate the user-specified command. PHANTOM returns the process ID (pid) assigned to the phantom process. Normal terminal output does not appear on the screen. By default, command output is stored as a record in the &PH& file for the current account. In D3, IN2, jBASE, MVBase, R83, POWER95, Reality, and Ultimate emulations, this output is instead directed to the Spooler file.
The optional SQUAWK keyword causes PHANTOM to also display the record number of the record created in the &PH& file. In D3, IN2, jBASE, MVBase, R83, POWER95, Reality, and Ultimate emulations, SQUAWK returns the spooler job number.
The optional BRIEF keyword starts a background process and returns the process ID (pid), but causes no output to be generated.
PHANTOM is similar to the ZH and Z commands. Unlike PHANTOM, Z and ZH prompt for the account, password, and command to execute. Like PHANTOM, ZH directs command output to either the &PH& file or the Spooler file, depending on emulation. Z does not retain command output.
See Also: JOBS, LIST.JOB, Z, ZH
PQ.SELECT
The PQ.SELECT command copies the default select list (select list 0) into the specified numbered select list.
PQ.SELECT n
The n argument is a select list number in the range 1 through 10 (inclusive). If n is out of range, PQ.SELECT returns a [819] message. If the default select list is not active, PQ.SELECT returns a [240] message.
PQ.SELECT is used to make the contents of the default select list available to a MultiValue PROC, which can only reference numbered select lists. For further details refer to Caché MultiValue PROC Reference.
PQ.RESELECT
The PQ.RESELECT and PQ.SELECT commands are functionally identical.
PRINT.CATALOG
The PRINT.CATALOG command displays details of catalog pointers and their program references.
PRINT.CATALOG filename [itemspec]
The filename argument can be a compiled and catalogued MVBasic program file, or the VOC. The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist PRINT.CATALOG returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify accountname if the file is located in an account other than the current account. Specify datasection if the catalog information is stored in a named data section.
itemspec is the name of a item, or a list of items to display. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all items in the file should be displayed. If itemspec is omitted, PRINT.CATALOG uses the active select list as the source of item names. If there is no active select list, PRINT.CATALOG issues a “Item Id:” user prompt.
PRINT.CATALOG displays a message for each item cataloged. A local catalog item generates a [232] message. A global catalog item generates a [233] message. If an item does not exist in the file or is not catalogued, PRINT.CATALOG returns without issuing an error message.
PRINT.ERR
The PRINT.ERR command displays specified items from the ERRMSG file.
PRINT.ERR ERRMSG [itemspec]
PRINT.ERR returns the specified messages from the ERRMSG file. For example, PRINT.ERR ERRMSG 201 210 returns the message texts for errors [201] and [210], one message per line.
itemspec specifies one or more numeric error codes used to retrieve and display the corresponding error messages. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all messages in the ERRMSG file should be displayed. If itemspec is omitted, PRINT.ERR uses the active select list as the source of error codes. If you do not specify a msg and there is no active select list, PRINT.ERR prompts you for an item ID. If msg is not found in ERRMSG, PRINT.ERR returns a [202] “not on file” error.
As each item is accessed, PRINT.ERR updates the @RECORD special variable with the retrieved error message.
PTERM
The PTERM command sets and displays terminal options.
PTERM [LPTR channel] [DEVICE name] [DISPLAY] [option value]
By default, the terminal is the user terminal. The option argument is the name of an option; the value argument is a keyword setting for that option. Available option value pairs are CASE INVERT and CASE NOINVERT, CRMODE INLCR and CRMODE NOINLCR.
Q
The Q command quits the MultiValue Shell.
Q
Specifying Q causes the current terminal process to immediately exit the MV Shell and returns to the Caché mode prompt. To perform the same operation on other terminal processes, use the LOGOFF or LOGOUT commands.
The Q and QUIT commands are synonyms.
See Also: LOGOFF, LOGOUT, OFF, QUIT
QSELECT
The QSELECT command generates a select list of the specified items.
QSELECT filename [itemspec] [slist]
The filename is the name of an existing file which is used as the source for the select list data. If the file doesn't exist QSELECT returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the items to be selected are stored in a named data section.
itemspec is the name of a item, or a list of items to copy to the select list. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all items in the file should be copied to the select list. If itemspec is omitted, QSELECT uses the active select list as the source of item names.
As each item is accessed, QSELECT updates the @RECORD special variable.
The slist argument allows you to specify a numeric select list. By default, QSELECT outputs to select list 0.
See Also: BSELECT, CLEARSELECT, NSELECT, SEARCH, SELECT, SSELECT
QUIT
The QUIT command quits the MultiValue Shell.
QUIT
Specifying QUIT causes the current terminal process to immediately exit the MV Shell and returns to the Caché mode prompt. To perform the same operation on other terminal processes, use the LOGOFF or LOGOUT commands.
The QUIT and Q commands are synonyms.
See Also: LOGOFF, LOGOUT, OFF, Q
REFORMAT
The REFORMAT command copies one or more DICT entries from a file and reformats them into an inverted file.
REFORMAT [USING dictname | DICT] filename field1 [field2 [...]] [query] [(PYZ]
REFORMAT takes an input filename and prompts you to specify an output file. You must specify the name of an existing file at the File Name= prompt. If the specified input filename is not an existing file, it generates a [200] error. If the specified output file is not an existing file, it generates a [201] error.
The optional DICT keyword specifies that filename is accessing a dictionary file; otherwise, the filename is assumed to be accessing a data file. If there are multiple defined data sections (data files), you can specify filename as filename,datasection.
The field arguments permit you to specify which DICT entries to reformat to the output file. You must specify at least one field. You can specify multiple field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. If any one of the field items is not a defined DICT entry, REFORMAT generates a [7011] error for each invalid entry and no DICT entries are processed. Upon successful completion, REFORMAT generates a [180] message specifying the number of items processed.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the REFORMAT operation.
See Also: CREATE.FILE SREFORMAT
RUN
The RUN command runs an MVBasic program.
RUN filename item
The RUN command can execute an MVBasic program that has been compiled using the BASIC command. The MVBasic program does not need to be cataloged. Once an MVBasic program has been cataloged using CATALOG, it may be executed either by issuing a RUN command, or by simply invoking the item as a verb.
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist RUN returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify accountname if the file is located in an account other than the current account. Specify datasection if the program to be run is stored in a named data section of the file.
Before you can run an MVBasic program, you must first compile it using the BASIC command. If the specified item doesn't exist RUN generates a [41] error message. If the specified item has not been compiled RUN generates a [40] error message. If no item is specified RUN generates a [203] error message.
See Also: ; (semicolon), BASIC, MVI
SAVE.LIST
The SAVE.LIST command copies the specified numbered select list into a named select list.
SAVE.LIST [listname] [FROM n]
Use the optional listname argument to specify a named select list; if omitted, the select list name is taken from the process ID (pid) or the UDT_SAVEDLIST environment variable. The optional FROM n argument is a select list number in the range 0 through 10 (inclusive); if omitted, select list 0 is the default. Upon successful completion, SAVE.LIST returns a message such as the following: [247] 478 Items saved to list 'MYLIST'.
When a select list is saved it becomes unavailable to the MVBasic READNEXT command. To make a select list available again, use GET.LIST.
If n is not an active select list, SAVE.LIST returns a [240] error message. If n is out of range, SAVE.LIST returns a [209] error message.
SAVE.LIST is the inverse of GET.LIST. To copy Select List 0 to another numbered select list, use the PQ.SELECT command.
SEARCH
The SEARCH command searches item(s) for string(s) and copies those that match to a select list.
SEARCH filename [itemspec]
SEARCH searches an item or multiple items for one or more strings. When it finds a match, it copies the item to select list 0.
The filename is the name of an existing file, which is created as a Caché global (^filename). If the file doesn't exist SEARCH returns a [201] error message. The filename can be specified using filespec syntax, as follows:
[DICT | DATA] [accountname,]filename[,datasection]
The optional DICT and DATA keywords enable you to specify a dictionary file or a data file. The default is a data file. Specify datasection if the items to be searched are stored in a named data section.
itemspec is the name of a item, or a list of items to search for a specified string. An itemspec can be specified using the following syntax:
item [item2 [...]] | *
You may specify a single item or multiple items separated by spaces. An asterisk (*) specifies that all items in the file should be searched. If itemspec is omitted, SEARCH uses the active select list as the source of one or more items to search. If itemspec is omitted and there is no active select list, SEARCH prompts you for an item value. If a specified item is not valid, SEARCH returns a [202] message for that item.
As each item is accessed, SEARCH updates the @RECORD special variable.
SEARCH prompts you for strings to search for. You can specify one or more strings at successive prompts, then press Enter at a prompt to conclude string input.
See Also: BSELECT, CLEARSELECT, NSELECT, QSELECT, SELECT, SSELECT
SELECT
The SELECT command generates a select list of items that satisfy the query criteria.
SELECT [DICT] filename [field1 [field2 ...] [dict [dict2 ...] | ALL] [query] [TO listnum] [(FPYZ]
SELECT copies items selected from filename to a select list. If filename is not an existing file, SELECT generates a [200] error. If filename is an empty file, SELECT generates a [401] error and no select list is returned.
The optional DICT keyword specifies that filename is accessing a dictionary file; otherwise, the filename is assumed to be accessing a data file. If there are multiple defined data sections (data files), you can specify filename as filename,datasection. SELECT can specify any valid Caché MultiValue SQL (CMQL) query.
The optional field arguments permit you to specify which DICT entries to select. You can specify one or more field arguments separated by blank spaces. If a field argument is an item ID it must be enclosed with single quote characters. If you omit the field argument, all DICT entries in filename are selected, or all DICT entries are selected that pass the condition tests in query. If no items pass the query condition test, SELECT generates a [401] error and no select list is returned.
The optional dict arguments permit you to specify which DICT entries to select for each field. You can specify one or more dict entry names separated by blank spaces. DICT entry names are not enclosed with quote characters. If you omit the dict argument, only the @ID (VOC) dictionary entry for each field is selected. If you specify ALL, all the dict attribute values for each field are selected.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
You can use the TO clause to specify a numeric select list. Valid listnum values are 0 through 10. By default, SELECT uses select list 0.
The following are supported letter code options:
-
(F suppresses “not on file” message generation. Because select lists are implemented as SQL joins that only return rows that are in both the select list and the file, Caché MultiValue compares each item in the list with the file; items that don’t match are added to the error list, unless suppressed using this option.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the SELECT operation.
Upon successful completion, SELECT returns a message such as the following: 2 Items selected to list #0. The first successful SELECT to any select list sets the boolean flag $MVV(210) to 1. $MVV(210) remains set to 1 until explicitly reset. The $MVV special variable is described in the Caché ObjectScript Reference.
See Also: BSELECT, CLEARSELECT, LIST, NSELECT, QSELECT, SEARCH, SSELECT
SET.FILE
The SET.FILE command creates a type Q file.
SET.FILE [account [filename [qname]]
SET.FILE with no arguments creates a Q-pointer file in the VOC in the current account. By default, it leaves Line 2 of the Q-pointer blank, which indicates the current account. You can create multiple Q-pointer files in the VOC. To specify a Q-pointer file other than the default QFILE, you must specify the account and filename, as shown in the following example:
SET.FILE "USER" "VOC" "QFILETWO"
The optional account argument permits you to specify the name of an account (Line 2); the default is the current account. The optional filename argument permits you to specify the name of a file in account (Line 3); the default is VOC. The optional qname argument permits you to specify the name of the Q-pointer in filename; the default is QFILE.
You can use LISTF to list files with their file type (F or Q), the corresponding data file and dictionary file.
See Also: LISTF
SETPTR
The SETPTR command lists or sets the current printer settings.
SETPTR [chan,width,depth,topmargin,botmargin,mode,option[,option]]
SETPTR with no arguments lists the current printer settings. SETPTR with a comma-separated list of positional arguments is used to change one or more printer settings.
For further details, refer to SETPTR in the “Spooler Commands” chapter of The Caché MultiValue Spooler.
SETPTR.DEFAULT
The SETPTR.DEFAULT command takes the current print channel 0 settings and establishes them as the print channel 0 default settings.
SETPTR.DEFAULT [LIST] [DELETE] [(LD ]
SETPTR.DEFAULT must be run from the SYSPROG account. Before issuing SETPTR.DEFAULT you define the print channel 0 settings using SETPTR. SETPTR.DEFAULT makes these settings the print channel 0 defaults for all future SETPTR commands systemwide. If any printer settings have not been set, SETPTR.DEFAULT establishes a default SETPTR characteristic for that setting. SETPTR.DEFAULT has no effect on print channels other than print channel 0.
The LIST keyword or the (L letter code option displays the current defaults that have been set. You can run SETPTR.DEFAULT LIST or SETPTR.DEFAULT (L from any account.
The SETPTR.DEFAULT settings remain in effect across system reboots until you issue a SETPTR.DEFAULT DELETE or SETPTR.DEFAULT (D command. The DELETE keyword or the (D letter code option reverts all settings to the initial printer default settings.
For further details, refer to SETPTR in the “Spooler Commands” chapter of The Caché MultiValue Spooler.
SH
The SH command issues an operating system command.
SH [commandline] SH -c "commandline"
The SH command issues an operating system command without exiting the MultiValue Shell. Results are displayed to the MultiValue Shell. No additional windows are opened.
SH with no argument opens an interactive command prompt from which you can issue multiple operating system commands. To exit this command prompt, specify the quit command for the operating system. On Windows systems, this is EXIT.
SH commandline issues an operating system command as a background process. The commandline can be any valid command line for the current operating system. A commandline cannot exceed 248 characters in length. Upon completion it returns to the MultiValue Shell prompt.
The SH -c "commandline" alternate syntax is equivalent to SH commandline. This syntax is provided for UniVerse compatibility. The double quotes enclosing the commandline are mandatory.
You can use COS to issue an ObjectScript command without exiting the MultiValue Shell.
The SH command is supported on multiple operating system platforms. The DOS command is specific to Windows platforms. On Windows systems, the DOS and SH commands are synonyms.
On Windows systems you can use SH set (or DOS set) to display a list of environment variables. To display individual environment variables, you can use the MVBasic GETENV() function.
SLEEP
The SLEEP command suspends the process for the specified number of seconds, or until the specified time. It then returns to the MultiValue Shell prompt.
SLEEP seconds SLEEP time
You can specify seconds as an integer or a fraction.
You can specify time as local time in either 24-hour or 12-hour format. A 24-hour time is specified as hh:mm[:ss]. A 12-hour time is specified as hh:mm[:ss]{AM | PM}. In both formats, spaces are not permitted, leading zeros may be omitted, and the seconds component of the time is optional. The following are all valid 24-hour format time values: 02:34, 2:34:00, 14:34, 14:34:00. The following are all valid 12-hour format time values: 2:34PM, 02:34PM, 2:34:00PM. 2:34AM. Midnight can be represented by 24:00, 00:00, 12:00PM, 00:00PM, or 00:00AM. An invalid time argument generates a [6193] error.
Caché MultiValue determines local time as follows:
-
It determines the current Coordinated Universal Time (UTC) from the system clock.
-
It adjusts UTC to the local time zone by using the value of the Caché special variable $ZTIMEZONE.
-
It applies local time variant settings (such as Daylight Saving Time) for that time zone from the host operating system.
SORT
The SORT command generates a sorted list of fields that satisfy the query criteria.
SORT [DICT] filename [field1 [field2 ...]] [dict [dict2 ...] | ALL] [query] [BY field | BY-DSND field | BY-EXP field | BY-EXP-DSND field] [(CDEFHINPYZ]
SORT returns a sorted display of the fields specified in field and/or selected by query. SORT is otherwise identical to the LIST command. Refer to the LIST command for further details.
Caché MultiValue defaults to sorting using BY logic: sorting items by their @ID values as single-valued elements in ascending collation sequence. Other MultiValue emulations default to BY-EXP logic.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
You can use the CMQL BY clause to sort by a field other than @ID, and/or sort in descending order, rather than ascending order. The BY keyword sorts the field values in ascending order (the default). The BY-DSND keyword sorts the field values in descending order. The BY-EXP keyword explodes the multivalue levels of field into a data row and sorting these values in ascending order. The BY-EXP-DSND keyword explodes the multivalue levels of field and sorts the values in descending order.
SORT.ITEM
LIST.ITEM [DICT] filename [field1 [field2 ...]] [query] [(DFHNPYZ]
SORT.ITEM is the same as LIST.ITEM, except that it sorts the field names as single values in ascending collation sequence before listing them. Caché MultiValue defaults to sorting using BY logic: sorting fields by their @ID values as single-valued elements in ascending collation sequence. Other MultiValue emulations default to BY-EXP logic. You can specify a different sort order using the CMQL BY clause. See LIST.ITEM for additional details.
See Also: LIST.ITEM
SORT.LABEL
SORT.LABEL [DICT] filename [field1 [field2 ...]] [query] [(DFNPYZ]
SORT.LABEL is the same as LIST.LABEL, except that it sorts the values in ascending collation sequence before formatting them for display. See LIST.LABEL for details.
See Also: LIST.LABEL
SORT.LIST
The SORT.LIST command sorts a saved select list in the &SAVEDLISTS& file.
SORT.LIST [filename [listname] ]
The optional filename is the destination file where the sorted select list is to be stored. If you omit filename, SORT.LIST prompts you for the list ID. The optional listname is the name of an existing select list in &SAVEDLISTS&; the default is select list 0. Caché stores the &SAVEDLISTS& file using the ^SAVEDLISTS global.
See Also: COPY.LIST, EDIT.LIST
SP.x Commands
Caché MultiValue supports 39 commands that control the Spooler. The names of these commands begin with either “SP-” or “SP.” Caché supports both variant forms: the hyphen form and the dot form. For example, SP-ASSIGN and SP.ASSIGN are different names for the same command. In most cases, these two forms are synonymous. The one exception is SP-EDIT and SP.EDIT, which provide different syntax options.
The following spooler commands are supported: SP.ASSIGN, SP.AUX, SP.CLEAR, SP.CLOSE, SP.CONDUCT, SP.CONTROL, SP.COPIES, SP.COPY, SP.CREATE, SP.DELETE, SP.DEVICE, SP.DISPLAY, SP-EDIT, SP.EDIT, SP.EJECT, SP.FORM, SP.FQDELETE, SP.GLOBAL, SP.JOBS, SP.KILL, SP.LOOK, SP.MOVEQ, SP.NEWTAB, SP.OPEN, SP.OPTS, SP.PAGESIZE, SP.POSTAMBLE, SP.PREAMBLE, SP.PURGEQ, SP.RESUME, SP.SHOW, SP.SKIP, SP.START, SP.STATUS, SP.STOP, SP.SUSPEND, SP.SWITCH, SP.TESTPAGE, SP.VERBOSE.
For further information on these commands, refer to the “Spooler Commands” chapter of The Caché MultiValue Spooler.
SPOOL
The SPOOL command controls the spooling of files for printing. It has three forms: send a file to the spooler for printing; list the files pending on the spooler queue; delete a print job from the spooler queue.
SPOOL filename itemID [-NOHEAD] [-O] SPOOL -LIST [formname] SPOOL -CANCEL joblist
SPOOL filename itemID takes a MultiValue item and prints it to the currently assigned printer (the default is print queue 0). The optional –NOHEAD keyword suppresses banners defined by SETPTR for the currently assigned printer.
SPOOL -LIST lists all the jobs on the spooler table. The optional formname argument allows you to filter to a single form queue name. The form queue can be specified either by name or by number. The default form queue has the name STANDARD, and a form queue number of 0. It can be specified as “STANDARD”, “0”, “F0”, “FN0”, or “FQ0”.
SPOOL -CANCEL deletes one or more pending print jobs. The joblist argument allows you to specify any number of individual print job numbers (separated by blank spaces), as shown in the following example: SPOOL -CANCEL 66 68 71. You can also delete a range of print jobs, as shown in the following example: SPOOL -CANCEL 66-70.
The -O option performs no operation and is ignored. It is accepted in syntax for compatibility with UniData code.
For further details and examples, refer to The Caché MV Spooler manual.
See Also: SP.DELETE
SREFORMAT
The SREFORMAT command copies one or more fields from a file and reformats them into a sorted inverted file.
SREFORMAT [USING dictname | DICT] filename field1 [field2 [...]] [query] [(PYZ]
The SREFORMAT sorts the records returned in ascending collation sequence. In all other respects it is identical to the REFORMAT command.
See Also: REFORMAT
SSELECT
The SSELECT command generates a sorted select list of items that satisfy the query criteria.
SSELECT [DICT] filename [field1 [field2 ...] [dict [dict2 ...] | ALL] [query] [TO listnum] [(FPYZ]
The SSELECT sorts the records selected in ascending collation sequence. In all other respects it is identical to the SELECT command.
See Also: SELECT
STACK
The STACK command changes the behavior of the MultiValue Shell command line recall stack.
STACK [option [option]]
STACK with no argument returns the current MV Shell recall stack settings.
The following STACK options are supported. You can specify multiple options in any order, separating options with spaces.
MAX nn — Sets the maximum number of entries in the recall stack to nn. The default is 99.
DUP ON | OFF — Allows duplicate commands in the recall stack. The default is DUP OFF.
CLEAR — Clears the current recall stack in the current MV Shell.
RECALL START | END — Positions the cursor to either the start or the end of a recalled command. The default is RECALL END.
BY type — Specifies how the MV Shell provides persistence of command recall during logon, logoff, and logto. The available type values are AUTHORIZATION, COS, IP, LOGNAME, NAME, NONE, PORT, USER, and ROUTINE name. The default is BY COS.
When STACK BY AUTHORIZATION is specified, the commands are stored in the terminal command line stack indexed by the Caché username. This is the same value contained in the @AUTHORIZATION system variable. When STACK BY USER is specified, the commands are stored in the terminal command line stack indexed by the operating system username. This is the same value contained in the @USER system variable. STACK BY LOGNAME is a synonym for STACK BY USER.
When STACK BY ROUTINE name is specified, an ObjectScript routine or a MV subroutine is invoked at MV Shell logon and logoff. It is up to that routine to save and restore the stack in whatever way it sees fit. The syntax of name determines whether an ObjectScript routine or a MV subroutine is invoked. If name contains a ^ character, Caché assumes the routine is a standard ObjectScript routine. For example, SHELL^MYFUNCS would be procedure SHELL in the ObjectScript module MYFUNCS. If name does not contain a ^ character, Caché assumes the routine is a MV subroutine. For example MYSHELL indicates that Caché should call the MV subroutine MYSHELL.
STACKCOMMON
The STACKCOMMON command specifies whether the MVBasic PERFORM statement stacks unnamed COMMON variable areas.
STACKCOMMON STACKCOMMON ON STACKCOMMON OFF
STACKCOMMON with no argument returns the current setting. STACKCOMMON ON causes each PERFORM to NEW the unnamed COMMON variables area before calling a routine. STACKCOMMON OFF (the default) causes the unnamed COMMON variables area to be preserved across multiple PERFORM routine calls.
See Also: The MVBasic COMMON and PERFORM statements.
STAT
The STAT command returns the total, average, and count for a numeric attribute.
STAT [DICT] filename [dict [dict2 ...] | ALL] [query] [(CHINPYZ]
STAT with a dict argument returns the total of the values for that attribute, the average value for that attribute, and the count of values that fulfill the query criteria.
The optional DICT keyword causes the command to total, average, and count the specified DICT entries in the filename dictionary file; otherwise, filename is assumed to be a data file.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(C or COL-HDR-SUPP suppresses both the default page header and the column headers. COL.HDR.SUPP (note two P’s) is a synonym for COL-HDR-SUPP.
-
(H or HDR-SUPP suppresses the default page header. It does not suppress a page header specified using the HEADING clause. HDR.SUP and SUPP are synonyms for HDR-SUPP.
-
(I or ID-SUPP suppresses listing the @ID field. ID-SUP and ID.SUP are synonyms for ID-SUPP.
-
NI-SUPP suppresses the total item count at the end of the listing. NI.SUP and COUNT.SUP are synonyms for NI-SUPP.
-
(N or NOPAGE suppresses the page break prompt. NO.PAGE is a synonym for NOPAGE.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the STAT operation.
The following example returns the total, average, and count (ENUM) for the specified attribute:
STAT VOC F5
The VOC contains 26 F5 values that begin with the number 2. STAT returns a F5 total of 52 (26 x 2), an AVG F5 of .108786611 (52 / 478), and an ENUM F5 of 478.
The following example returns the same statistics on F5 values that fulfill thequery criteria, in this case, the criteria that every F5 has a non-null value:
STAT VOC F5 WITH F5
STAT returns a F5 total of 52 (26 x 2), an AVG F5 of 1.06122449 (52 / 49), and an ENUM F5 of 49.
STAT results can be returned individually using the COUNT and SUM commands or the AVG, ENUM, and TOTAL CMQL clauses.
STATUS
The STATUS command displays a table listing the current MultiValue user processes.
STATUS
For each user process, STATUS lists the process ID (pid), the port number, the date and time of initialization of the MV Shell, and the username. The current process is indicated by an asterisk preceding the pid number. If a current terminal process is not running the MultiValue Shell, STATUS does not displayed it.
This listing is initiated by displaying a header, and concludes with a count of the number of items listed.
After listing each full page of items, STATUS issues a prompt to the user to input a character to display the next page. To terminate listing, input the letter Q at the display prompt. This prompted character is not echoed on the list display, regardless of the MultiValue emulation.
The STATUS and LISTU commands are functionally identical. The LISTME command returns identical information, but only lists processes when in the USER account. To list the current account name and currently executing command for each terminal process, use the WHERE command.
See Also: LISTME, LISTU, LOGOFF, WHERE
SUM
The SUM command sums the values of items that satisfy an SQL query.
SUM [DICT] filename {field1 [field2 ...] | ALL} [query] [(CHIPYZ]
SUM returns a sum for each specified field item in filename, or the items selected from filename by query. It returns a [423] message for each field: Total of field is : n. After returning one or more [423] messages, it returns a [438] message giving the count of the items summed. This is shown in the following example:
USER:SUM VOC F1 F5
[423] Total of F1 is : 0
[423] Total of F5 is : 54
[438] 366 Items summed.
You must either specify one or more field arguments separated by blank spaces, or specify ALL to return totals for all fields.
The optional DICT keyword causes the command to sum the DICT entries in the filename dictionary file; otherwise, filename is assumed to be a data file.
The optional query component can contain one or more Caché MultiValue SQL (CMQL) query clauses. These CMQL clauses can be specified in any order; the order of application of CMQL clauses is independent of the specified order. For further details on CMQL clauses, refer to Caché MultiValue Query Language (CMQL) Reference.
The following are supported letter code and keyword options:
-
(C or COL-HDR-SUPP suppresses both the default page header and the column headers. COL.HDR.SUPP (note two P’s) is a synonym for COL-HDR-SUPP.
-
COUNT.SUP suppresses the [438] x Items summed message.
-
(H or HDR-SUPP suppresses the default page header. It does not suppress a page header specified using the HEADING clause. HDR.SUP and SUPP are synonyms for HDR-SUPP.
-
(I or ID-SUPP suppresses listing the @ID field. ID-SUP and ID.SUP are synonyms for ID-SUPP.
-
NI.SUP suppresses the [438] x Items summed message.
-
(P redirects all output to the STANDARD print queue. The LPTR clause performs the same operation. You can use LISTPEQS to view the print queue.
-
(Y displays query metadata.
-
(Z displays the CMQL Query Execution Plan before performing the LIST operation.
When adding field values, SUM uses the leading numeric portion of a string; for example, 2CPM is processed as 2. If a field value does not begin with a number, it is treated as 0. SUM does not check for duplicate names; if you specify a field item twice, it will be summed twice.
See Also: COUNT, LIST, SELECT, STAT
TABS
The TABS command sets tab stops.
TABS n[,n[,n]]
TABS can be used to set any number of tab stops at specified character positions. Multiple n arguments can be separated by commas or spaces. TABS overwrites any previous tabs settings. To remove all tabs, specify TABS with no arguments. If no tabs are set, the tab key advances by a single space.
TANDEM
The TANDEM command allows one MultiValue user to connect to the terminal of another MultiValue user, sharing terminal input and output.
TANDEM [ON | OFF | SYSPROG] [(N | (F | (S] TANDEM port
A tandem session consists of a master and a slave terminal. A tandem session begins with the slave terminal.
The slave terminal uses the ON keyword to specify availability to receive a tandem slave request. The slave terminal uses the OFF keyword to end availability to receive a tandem slave request or to end the current tandem session. The (N and (F letter code options are synonyms for ON and OFF; specify either ON or OFF or (N or (F, not both.
Once the slave terminal has specified TANDEM ON (or TANDEM (N), the master terminal can use the port argument to specify the terminal they wish to establish as a tandem slave. (You can use the LISTME or LISTU commands to list the port numbers of current terminal sessions.)
Once established, the tandem session initiates when the slave terminal next presses the ENTER key.
By default, the master terminal and slave terminal can be running in any MV account. You can, however, restrict use of TANDEM to a master terminal running in the %SYS namespace (the SYSPROG account). To do so, the slave terminal must specify its availability using either TANDEM ON (S or TANDEM SYSPROG. This restrict tandem requests to master terminal running in the SYSPROG account.
The master terminal initially enters the tandem session in view-only mode. To quit the session in view-only mode, type “Q”. To change the mode, type one of the following: Esc-F puts the master in feed mode; Esc-V puts the master in view-only mode; Esc-M puts both master and slave in message mode; Esc-X causes the master to exit the tandem session.
For further details, refer to the TANDEM section of the Operational Differences between MultiValue and Caché manual.