MultiValue Commands

# 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

; 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>

See Also: BASIC, RUN

[ 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

<<[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:

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

ABORT (expr (, expr) )

ABORT runs the ON.ABORT paragraph, if present.

 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)

ASSIGN termname TO SYSTEM(7)

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 [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 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 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 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 [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 [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 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 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 [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 [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 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 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

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 [(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 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.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

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 {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 and CS commands are synonyms.

See Also: CS

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 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 [[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 [(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 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[ ...]] 

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 [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

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.

See Also: #, [, SH

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.

See Also: LIST, SELECT, STAT

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:

1. 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.

2. 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.

3. 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.

4. 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.

See Also: ATTACH.ACCOUNTS, CEMU, DELETE.ACCOUNT, LOGTO

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 [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.

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.

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"

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)

CS

The CS and CLR commands are synonyms.

See Also: CLR

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 [(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 [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 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 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 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.

See Also: CREATE.ACCOUNT, LOGTO

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 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 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 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.

See Also: CREATE.TRIGGER

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 [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.

See Also: COS, SH

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 filename itemspec

The EDIT and ED commands are synonyms.

See Also: ED

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

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 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 [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.

See Also: DISPLAY, P

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 [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 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.

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

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.

See Also: LIST.JOB, PHANTOM

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 [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 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 [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

LIST.JOB lists all running processes; JOBS lists all running processes initiated by the current process.

See Also: JOBS

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:

See Also: LIST, SORT.LABEL

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 filename

It lists each trigger in the following format: event = file subroutine. For example: PREREAD = BP TRTN.

See Also: CREATE.TRIGGER

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 [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

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 [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.

See Also: LISTPH, LISTS

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 [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.

See Also: LISTPA, LISTS

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 [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.

See Also: LISTPA, LISTPH

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 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 [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 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 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 [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

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

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 [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.

See Also: DISPLAY, HUSH

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 [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 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.

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.

See Also: CATALOG, DECATALOG

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 [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

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 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

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 [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 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 [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.

See Also: GET.LIST, PQ.SELECT

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 [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 [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 [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 [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 [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.

See Also: COS, DOS

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 [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.

See Also: COUNT, LIST, SELECT

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 [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 [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

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 [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 [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 [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 
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 [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.

See Also: COUNT, SUM

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 [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 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 [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.

See Also: LISTME, LISTU

TERM [name] 
TERM [#1, #2, #3, #4, #5, #6, #7, #8, #9, #10]

TERM with no argument returns the current terminal and printer settings.

TERM name sets the terminal type to name. The default terminal type is CACHE. You can display the current terminal type using the MVBasic SYSTEM (7) function. You can display the available terminal types using the CHOOSE.TERM command. CHOOSE.TERM can also be used to set the terminal type. You can specify 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. You can optionally specify name using a Short Name (a single uppercase letter), as shown in the CHOOSE.TERM listing. When setting just the name value, it may be preceded or followed by any number of commas; thus TERM name and TERM ,,,,,,,,name are synonymous.

TERM with one or more numeric arguments sets terminal and printer display characteristics using positional argument values. You many specify any subset of settings by including leading commas for unspecified values. Trailing commas are not required. For example, TERM ,,,,,,100 sets the seventh argument: Printer page width. The unspecified arguments retain their previous values.

The ten positional arguments are as follows:

Note that positional arguments 3, 4, 6, and 10 are currently not modifiable.

If you specify an out-of-range value, TERM returns a [290] message. If you specify an illegal value, TERM returns a [202] message.

For further details, refer to the Terminal Output chapter of the Caché MV Terminal Independence manual.

See Also: CHOOSE.TERM, COMPILE.TERM, SETPTR

TIME [command]

TIME with no argument returns the current local time and date. For example: “13:23:26 24 MAR 2008”. This date and time format is not affected by the DATE.FORMAT command. You can use the DATE command to return the current date and time.

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.

TIME command returns the elapsed execution time (in fractional seconds) for the specified MultiValue command. This is particularly valuable for timing CMQL queries. TIME command does not include time spent waiting for an inline prompt (<<...>>). TIME command does include time spent waiting for user response to display the next page, regardless of whether PAGE.MESSAGE is set to display or omit the “Press any key to continue” page prompt.

For further details, refer to the TIME section of the Operational Differences between MultiValue and Caché manual.

See Also: DATE

TRACE [ON | OFF]

When TRACE is on, the invocation of a MultiValue command or a MVBasic statement returns the START date/time (in internal format) before execution and the END date/time upon completion, along with the elapsed execution time in fractional seconds.

To activate this debug behavior for subsequent commands, invoke TRACE ON. To inactivate this behavior, invoke TRACE OFF. TRACE with no argument returns the current trace status (on or off).

You can use TIME command to return the elapsed execution time (in fractional seconds) for a single specified MultiValue command.

See Also: TIME

TRAP-EXCEPTIONS [ON | OFF]

When TRAP-EXCEPTIONS is on, it causes uncaught exceptions to be written to the MultiValue log file, located at Cache/mgr/mv.log. Then the program ends with an MV [EXCEPTION] error message. If the mv.log file grows larger than 5MB (or the size limit of cconsole.log) Caché automatically renames it with the current date suffix as mv.old_YYYYMMDD and initiates a new mv.log file. If mv.old_YYYYMMDD for the current date already exists, Caché appends an integer count suffix mv.old_YYYYMMDD_n to create a unique file name. Refer to the %SYS.Task.PurgeErrorsAndLogs()Opens in a new tab method.

When TRAP-EXCEPTIONS is off (the default), an uncaught error writes a Caché error message and terminates the MultiValue execution stack.

TRAP-EXCEPTIONS with no argument returns its current status (on or off).

You can also use the %SYS.System.WriteToMVLog()Opens in a new tab method to write to the mv.log file.

 UNASSIGN form-queue

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”.

See Also: ASSIGN

WHERE [startval[-endval]] [(DV]

By default, WHERE lists all running MultiValue processes, including phantom processes. By using the optional startval and endval arguments you can restrict the list of processes returned to a single process or a specified range of processes (inclusive). No spaces are permitted in the startval-endval range; for example, WHERE 1872-2049 is valid, but WHERE 1872 - 2049 is not valid.

By default, WHERE sorts the list of running MultiValue processes by port number, using startval and endval to specify a range of port numbers. The (D letter code option specifies sorting by Caché process ID (pid) number, using startval and endval to specify a range of pid numbers.

The (V letter code option specifies verbose mode, supplying more information about each process. You can specify either or both letter code option in any order.

For each terminal process running the MultiValue Shell, WHERE lists the port number, the device ID (including the pid), the current account name and current namespace name (these are often the same), and the currently executing MultiValue command. The SYSPROG account corresponds to the %SYS namespace.

The active process is indicated by an asterisk preceding the port number. Its current command is always “WHERE”. Other terminal processes indicate the currently executing command (for example, KEYS or SLEEP); if no MultiValue command is executing, they return “MVShell” as the current command. If a current terminal process is not running the MultiValue Shell, WHERE does not displayed it.

See Also: LISTU, STATUS

WHO [portnum]

WHO with no argument returns the string portnum account from name for the current process. WHO portnum returns the same string for the process corresponding to the specified port number. If no active MultiValue process corresponds to portnum, WHO returns the empty string. You can use LISTU to list all active MultiValue processes with their port and process ID (pid) numbers.

You can use STATUS to find the process ID (pid) corresponding to the terminal port number. The account name usually identical to the Caché namespace name. However, note that namespace names are not case-sensitive, but account names are case-sensitive. The SYSPROG account corresponds to the %SYS namespace. An account is created using the CREATE.ACCOUNT command.

See Also: LISTU, LOGTO, STATUS, WHERE

Z [command]

If you specify Z with no argument, it prompts you for account name, password, and command to execute. The account name is usually the same as the Caché namespace name. The password is ignored. The command is any valid MultiValue command.

The Z command does not retain output from the invoked MultiValue command.

Z initiates a phantom (background) process. It does not validate the user-specified command. Z returns to the MultiValue Shell with a message specifying the process ID (pid) used for the phantom process.

The PHANTOM and ZH commands perform similar operations. Both, however, retain and direct command output. PHANTOM is not interactive; it does not prompt for the command to execute. ZH prompts for account name, password, and command to execute.

See Also: PHANTOM, ZH

ZH [command]

If you specify ZH with no argument, it prompts you for account name, password, and command to execute. The account name is usually the same as the Caché namespace name. The password is ignored. The command is any valid MultiValue command.

Normal terminal output does not appear on the screen. By default, command output is stored as a record in the &PH& file. In PICK and some other emulations, this output is instead directed to the Spooler file.

ZH initiates a phantom (background) process. It does not validate the user-specified command. If, for example, output from a CEMU command is directed to &PH&, ZH displays a message such as: CEMU_39690_15409 record has been created in the '&PH&' file. If ZH is unable to open the &PH& file (usually because the account name is invalid), it returns a [201] error, and no phantom process is initiated. If the current emulation directs output to Spooler, ZH displays the message Output to spooler. In all emulations, successful execution of ZH then displays the process ID (pid) assigned to the phantom process.

The PHANTOM and Z commands perform similar operations. PHANTOM is not interactive; it does not prompt for the command to execute. Z prompts for account name, password, and command to execute, but does not retain command output.

See Also: PHANTOM, Z