rcdmqimg (record media image)
Write the image of an object or group of objects to the log for media recovery.
Purpose
Use the rcdmqimg command to write an image of an object, or group of objects, to the log for use in media recovery. This command can be used only when using linear logging. See Types of logging for more information about linear logging. Use the associated command rcrmqobj to re-create the object from the image.
Before IBM MQ Version 9.1.0, or when using LogManagement=Manual, the command does not run automatically as it must be run in accordance with, and as determined by, the usage of each individual customer of IBM MQ.
After IBM MQ Version 9.1.0, when using LogManagement=Automatic or Archive, the queue manager automatically records media images, however rcdmqimg can also be run manually as well, if required.
Running rcdmqimg moves the log sequence number (LSN) forwards and frees up old log files for archival or deletion.
When determining when and how often to run rcdmqimg, consider these factors:
- Disk space
- If disk space is limited, regular running of rcdmqimg releases log files for archive or deletion.
- Impact on normal system performance
- rcdmqimg activity can take a long time if the queues on the system are deep. At this time, other system usage is slower and disk utilization increases because data is being copied from the queue files to the logs. Therefore, the ideal time to run rcdmqimg is when the queues are empty and the system is not being heavily used.
You use this command with an active queue manager. Further activity on the queue manager is logged so that, although the image becomes out of date, the log records reflect any changes to the object.
Syntax
Required parameters
- GenericObjName
- The name of the object to record. This parameter can have a trailing asterisk to record that any objects with names matching the portion of the name before the asterisk.
This parameter is required unless we are recording a queue manager object or the channel synchronization file. Any object name you specify for the channel synchronization file is ignored.
- -t ObjectType
- The types of object for which to record images. Valid object types are:
Object Type Description all and * All the object types; ALL for objtype and * for GenericObjName authinfo Authentication information object, for use with TLS channel security channel or chl Channels clntconn or clcn Client connection channels catalog or ctlg An object catalog listener or lstr Listeners namelist or nl Namelists process or prcs Processes queue or q All types of queue qalias or qa Alias queues qlocal or ql Local queues qmodel or qm Model queues qremote or qr Remote queues qmgr Queue manager object service or srvc Service syncfile Channel synchronization file. topic or top Topics
Note: When using IBM MQ for UNIX systems, we must prevent the shell from interpreting the meaning of special characters, for example, an asterisk (*). How you do this depends on the shell we are using, but might involve the use of single quotation marks ('), double quotation marks ("), or a backslash (\).
Optional parameters
- -m QMgrName
- The name of the queue manager for which to record images. If we omit this parameter, the command operates on the default queue manager.
- -z
- Suppresses error messages.
- -l
- Writes messages containing the names of the oldest log files required to restart the queue manager and to perform media recovery. The messages are written to the error log and the standard error destination. (If you specify both the -z and -l parameters, the messages are sent to the error log, but not to the standard error destination.)
When issuing a sequence of rcdmqimg commands, include the -l parameter only on the last command in the sequence, so that the log file information is gathered only once.
Return codes
| Return code | Description |
|---|---|
| 0 | Successful operation |
| 26 | Queue manager running as a standby instance. |
| 28 | Object not media recoverable. |
| 36 | Invalid arguments supplied |
| 40 | Queue manager not available |
| 49 | Queue manager stopping |
| 58 | Inconsistent use of installations detected |
| 68 | Media recovery not supported |
| 69 | Storage not available |
| 71 | Unexpected error |
| 72 | Queue manager name error |
| 119 | User not authorized |
| 128 | No objects processed |
| 131 | Resource problem |
| 132 | Object damaged |
| 135 | Temporary object cannot be recorded |
When are log extents deleted
Log extents are only deleted when the queue manager determines that they can be deleted. Note that log extents are not deleted immediately after recording the media image.
For example, if the starting media extent is 04, the queue manager does not delete this extent until the extent number moves forward, and the queue manager might or might not delete extents 01 to 04.
The logger event messages, and the IBM MQ queue manager error logs, show the log extents required for queue manager restart and media recovery.
Examples
The following command records an image of the queue manager object saturn.queue.manager in the log.rcdmqimg -t qmgr -m saturn.queue.manager
Related commands
| Command | Description |
|---|---|
| rcrmqobj | Re-create a queue manager object |