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) | '-| -FILE option |-----' (2) (3) >--| Log-Record Read Filters |------| Log-Record Display Filters |------> >--+-----+--+-----------+-------------------------------------->< '- -q-' +- -V-------+ '- -version-'
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. |
- 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.
- 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.
- 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. See the IBM Informix Backup and Restore Guide. 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-----'
- Only one occurrence of this item allowed
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_ |
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.