CMQL Query Logging

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:

USER: COS SET ^CMQLlog=1

For further details on these commands, refer to the Caché MultiValue Commands Reference.

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.

Viewing the CMQL Log

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=1
^CMQLlog(66,1)="LIST VOC WITH @ID LIKE Q..."
^CMQLlog(66,2)=""
^CMQLlog(66,3)="405ý3ýýþ"
^CMQLlog(66,4)=3432
^CMQLlog(67,1)="SELECT VOC TO 4"
^CMQLlog(67,2)=""
^CMQLlog(67,3)="404ý480ý4ýþ"
^CMQLlog(67,4)=5996

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'"
  ^CMQLlog(9,2)=""
  ^CMQLlog(9,3)="405ý2ýýþ780ýFREDýýþ"
  ^CMQLlog(9,4)=6108
  

• Log line 4: Contains the process ID (pid) of the process executing the query.