The onlog utility

The onlog utility displays the contents of a logical-log file, either on disk or on backup.

onlog: Display Logical-Log Contents

The onlog output is useful in debugging situations when you want to track a specific transaction or see what changes have been made to a specific tblspace. (For information about interpreting the logical-log file contents, see Interpreting Logical-Log Records.)

Any user can run all of the onlog options except the -l option. Only user informix on UNIX™ or a member of the Informix-Admin group on Windows™ can run the -l option.

If the database server is in offline mode when you execute onlog, only the files on disk are read. If the database server is in quiescent or online mode, onlog also reads the logical-log records stored in the logical-log buffers in shared memory (after all records on disk have been read).

When the database server reads a logical-log file with status U from disk while in online mode, the database server denies all access to the logical-log files, effectively stopping database activity for all sessions. (For more information, see onstat -l command: Print physical and logical log information.) For this reason, it is recommended that you wait until the files have been backed up and then read the contents of the logical-log files from backup.

The onlog utility does not have a functionally equivalent SQL administration API command string.

onlog Syntax

>>-onlog--+-------------------------+--+----------------------+-->
          |                     (1) |  '- -pw-+------------+--'
          '-|  -FILE option   |-----'         '--filename--'

                                (2)                                 3)   
>--| Log-Record Read Filters  |-----| Log-Record Display Filters |------>

>--+-----+--+-----------+--------------------------------------><
   '- -q-'  +- -V-------+   
            '- -version-'

Note: The -pw option is required only when the Storage space encryption feature is enabled, stash file is in use, and the server is off-line. Supply an optional path to a file containing the keystore password, otherwise onlog will prompt for a password before displaying the requested log(s).


Element	Purpose	Key Considerations
-q	Suppresses the initial header and the one-line header that appears every 18 records by default	None.
-V	Displays the software version number and the serial number	See Obtaining utility version information.
-version	Displays the build version, host, OS, number and date, as well as the GLS version	See Obtaining utility version information.

You direct onlog to read the following portions of the logical log as it searches for records to display:

Records stored on disk
Records stored on backup media
Records from the specified logical-log file

By default, onlog displays the logical-log record header, which describes the transaction number and the record type. The record type identifies the type of operation performed.

In addition to the header, you can use the read filters to direct onlog to display the following information:

Logical-log record header and data (including copies of simple large objects stored in a dbspace or tblspace)
Copies of blobpages from blobspaces
They are copied from the logical-log backup only. They are not available from disk.

You can display every logical-log record header, or you can specify output based on the following criteria:

Records associated with a specific table
Records initiated by a specific user
Records associated with a specific transaction

If onlog detects an error in the log file, such as an unrecognizable log type, it displays the entire log page in hexadecimal format and terminates.

Log-Record Read Filters

The onlog utility uses the pathnames that are stored in the root dbspace reserved pages to locate the logical-log files. If you use ON-Bar to back up the logical logs, onlog asks the storage manager to retrieve the appropriate logical-log records from the backup media.

Syntax

|--+----------------------+------------------------------------->
   '- -d--device--+-----+-'   
                  '- -b-'     

   .-------------------------------------------.   
   V                                           |   
>----+---------------------------------------+-+----------------|
     '- -n--starting_uniqid - ending_uniquid-'


Element	Purpose	Key Considerations
-b	Displays logical-log records associated with blobspace blobpages	The database server stores these records on the logical-log backup media as part of blobspace logging.
-d device	Names the pathname of the storage device where the desired logical-log backup is mounted	If you use ontape, the device that you name must be the same as the pathname of the device assigned to the configuration parameter LTAPEDEV. If the -d option is not used, onlog reads the logical-log files stored on disk, starting with the logical-log file with the lowest logid. If you use ON-Bar to back up logical logs, use the onbar -P command to view the contents of a logical-log file. For pathname syntax, see your operating-system documentation.
-n starting_uniqid-ending_uniqid	Directs onlog to read all the logical-log records contained in the log file that you specified from starting uniqid to the ending uniqid.	The starting_uniqid and the ending_uniqid are the unique ID numbers of the logical log. To determine the uniqid of a particular logical-log file, use the onstat -l command. If you do not use the -n option, onlog reads all the logical-log files that are available (either on disk or on tape). For information about the onstat utility, see Monitor the database server status.

Log-Record Display Filters

Syntax

   .------------------------------------------.   
   V                                          |   
|----+--------------------------------------+-+-----------------|
     |     (1)                              |     
     +- -l----------------------------------+     
     |                   (1)                |     
     +- -t--tblspace_num--------------------+     
     |               (1)                    |     
     +- -u--username------------------------+     
     |                     (1)              |     
     +- -x--transaction_id------------------+     
     |                                  (1) |     
     '- -c--compression_dictionary_file-----'


Element	Purpose	Key Considerations
-l	Displays the long listing of the logical-log record.	The long listing of a log record includes a complex hexadecimal and ASCII dump of the entire log record. The listing is not intended for casual use.
-ttblspace_num	Displays records associated with the tblspace that you specify.	Unsigned integer. Number, greater than 0, must be in the partnum column of the systables system catalog table. Specify this value as either an integer or hexadecimal value. (If you do not use a 0x prefix, the value is interpreted as an integer.) To determine the tblspace number of a particular tblspace, query the systables system catalog table as described in Tblspace Numbers.
-u username	Displays records for a specific user.	User name must be an existing login name. User name must conform to operating-system-specific rules for login name.
-x transaction_id	Displays only records associated with the transaction that you specify.	Value must be an unsigned integer between 0 and TRANSACTIONS - 1, inclusive. You should need to use the -x option only in the unlikely case that an error is generated during a rollforward. When this situation occurs, the database server sends a message to the message log that includes the transaction ID of the offending transaction. You can use this transaction ID with the -x option of onlog to investigate the cause of the error.
-c `compression`_ `dictionary_file`	Uses the compression dictionary to expand compressed data and display uncompressed data.	If the onlog command contains the -l option and the -c option and there are compressed images in the log records, the onlog utility uses the compression dictionary to expand all expandable images in the log records. A compressed image is expandable only if there is a valid compression dictionary for that log record in the compression dictionary file. If -c is not specified or the compression dictionary file does not contain a valid compression dictionary for the compressed image, the onlog utility will display the row image in its compressed format.

If you do not have a compression dictionary file, you can use an UNLOAD statement to unload the compression dictionary, which is contained in the syscompdicts_full table in the sysmaster database, to a compression dictionary file, as follows:

UNLOAD TO 'compression_dictionary_file'
   SELECT * FROM sysmaster:syscompdicts_full;

If you do not specify any options, onlog displays a short listing of all the records in the log. You can combine options with any other options to produce more selective filters. For example, if you use both the -u and -x options, onlog displays only the activities that the specified user initiated during the specified transaction. If you use both the -u and -t options, onlog displays only the activities initiated by the specified user and associated with the specified tblspace.