Caché MultiValue Query Language (CMQL) Reference
CMQL Query Logging
Creating a log of CMQL queries.
You can create a log of executed CMQL queries. CMQL logging is intended as a diagnostic aid for use when porting MultiValue queries. It should not be used as part of a production application.
The CMQL query log is created by writing subscript entries to the Caché global ^CMQLlog. This log is activated by setting ^CMQLlog = 1 and deactivated by setting ^CMQLlog = 0. Note that global names are case-sensitive.
The operations that are listed in the CMQL log are invocations of CMQL commands
, regardless of whether the command completes successfully.
Activating CMQL Logging from Caché MultiValue
To activate CMQL logging from the Caché MultiValue Shell, use the COS
, or [
commands, which permit you to issue an ObjectScript command from within MultiValue:
Setting ^CMQLlog=1 activates the logging of queries for the current account (namespace). All CMQL queries are logged, including queries that fail to execute due to an error. This logging remains in effect for all users of the current account (namespace) until ^CMQLlog is explicitly reset to 0 or the global is KILLed. CMQL logging persists across Caché restart.
Setting ^CMQLlog=0 deactivates the logging of queries for the current account (namespace). This means that queries issued when ^CMQLlog is set to zero are not logged in ^CMQLlog. Setting ^CMQLlog=0 does not delete the existing contents of ^CMQLlog. Queries that have been logged in ^CMQLlog remain listed in the log until you issue a KILL ^CMQLlog
command. Setting ^CMQLlog=0 also does not suspend CMQL routine numbering. Caché MultiValue assigns a sequential integer routine number to every CMQL query issued, whether or not that CMQL query is logged. Issuing a KILL ^CMQLlog
does not reset this CMQL routine number counter.
You can use the ObjectScript ZWRITE
command to view the CMQL query log. The following example displays ^CMQLlog from within the MultiValue Shell:
USER: COS ZWRITE ^CMQLlog
^CMQLlog(66,1)="LIST VOC WITH @ID LIKE Q..."
^CMQLlog(67,1)="SELECT VOC TO 4"
The first line returned shows the activation status of ^CMQLlog. In this case, CMQL logging is active for the USER account.
Each query in the CMQL log is represented by four lines. The first ^CMQLlog subscript is the CMQL routine number counter (in this case, routines 66 and 67). The second ^CMQLlog subscript is the log line number (1 through 4) for that query.
Log line 1: Contains the text of the query as a quoted string. Note that double quotation marks within the query string are duplicated (""item"") to indicate a literal quotation mark rather than the end of the query string.
Log line 2: If executing the query directly, contains an empty string. If executing the query using the MVBasic EXECUTE
command, contains the execute stack entry, a string such as $lb("+1^MVBASIC6108.mvi +2")
, where 6108 is the pid number.
Log line 3: Contains execution information about the query, specified as a dynamic array. Items are separated by value marks (@VM):
The first item is the error or completion message number. On error, returns the error code number. On success, returns one of the following: 401=LISTPA, LISTPH, LISTS successful, 403=SORT.ITEM successful, 404=SELECT, SSELECT, BSELECT successful, 405=LIST, LISTF, LIST.ITEM, SORT successful; 407=COUNT successful; 438=SUM successful; empty string=LIST.LABEL, SORT.LABEL, STAT successful.
The second item is the number of records selected by the query upon success. If an error occurred, the second item may contain error information.
The third item is the select list selected to.
If a query returns multiple messages, the information for each message is presented in the log line 3 dynamic array, with messages separated by field marks (@FM), with the success message items listed first. One example of this is a LIST.ITEM command that specifies some records in the file and some records that are not in the file. Each item not in the file returns its own field. This is shown in the following example:
^CMQLlog(9,1)="LIST.ITEM VOC 'A' 'FRED' 'BASIC'"
Log line 4: Contains the process ID (pid) of the process executing the query.