+

Search Tips   |   Advanced Search


MQ v7.5 Administration reference

  1. How to read railroad diagrams
  2. WebSphere MQ Control commands
  3. Use control commands
  4. Use control commands on Windows systems
  5. Use control commands on UNIX and Linux systems
  6. The control commands
  7. addmqinf
  8. amqmdain
  9. amqmfsck (file system check)
  10. crtmqcvx
  11. crtmqenv
  12. crtmqinst
  13. crtmqm
  14. dltmqinst
  15. dltmqm
  16. dmpmqaut
  17. dmpmqcfg
  18. dmpmqlog
  19. dspmq
  20. dspmqaut
  21. dspmqcsv
  22. dspmqfls
  23. dspmqinf
  24. dspmqinst
  25. dspmqrte
  26. dspmqspl
  27. dspmqtrc
  28. dspmqtrn
  29. dspmqver
  30. endmqcsv
  31. endmqlsr
  32. endmqdnm
  33. endmqm
  34. endmqsvc (end IBM WebSphere MQ service)
  35. endmqtrc
  36. migmbbrk
  37. MQExplorer (launch WebSphere MQ Explorer)
  38. mqrc (MQ return code)
  39. rcdmqimg
  40. rcrmqobj
  41. rmvmqinf
  42. rsvmqtrn
  43. runmqchi
  44. runmqchl
  45. runmqdlq
  46. runmqdnm
  47. runmqlsr
  48. runmqras
  49. runmqsc
  50. runmqtmc
  51. runmqtrm
  52. runswchl
  53. setmqaut
  54. Authorizations for MQI calls
  55. Authorizations for context
  56. Authorizations for commands
  57. Authorizations for generic operations
  58. setmqcrl
  59. setmqenv
  60. setmqinst
  61. setmqm
  62. setmqspl
  63. setmqprd
  64. setmqscp
  65. strmqcfg
  66. strmqcsv
  67. strmqsvc (Start IBM WebSphere MQ service)
  68. strmqm
  69. strmqtrc
  70. Comparing command sets
  71. Queue manager commands
  72. Command server commands
  73. Authority commands
  74. Cluster commands
  75. Authentication information commands
  76. Channel commands
  77. Listener commands
  78. Namelist commands
  79. Process commands
  80. Queue commands
  81. Service commands
  82. Other commands
  83. Managing keys and certificates
  84. Preparing to use the runmqckm and runmqakm commands
  85. runmqckm, and runmqakm commands
  86. Commands for a CMS key database only
  87. Command for CMS or PKCS #12 key databases
  88. Commands for cryptographic device operations
  89. runmqckm and runmqakm options
  90. runmqakm error codes
  91. MQSC reference
  92. Generic values and characters with special meanings
  93. Building command scripts
  94. Use commands on z/OS
  95. The MQSC commands
  96. ALTER AUTHINFO
  97. ALTER BUFFPOOL
  98. ALTER CFSTRUCT
  99. ALTER CHANNEL
  100. Sender channel
  101. Server channel
  102. Receiver channel
  103. Requester channel
  104. Client-connection channel
  105. Server-connection channel
  106. Cluster-sender channel
  107. Cluster-receiver channel
  108. ALTER CHANNEL (MQTT)
  109. ALTER COMMINFO
  110. ALTER LISTENER
  111. ALTER NAMELIST
  112. ALTER PROCESS
  113. ALTER PSID
  114. ALTER QMGR
  115. ALTER queues
  116. ALTER QALIAS
  117. ALTER QLOCAL
  118. ALTER QMODEL
  119. ALTER QREMOTE
  120. ALTER SECURITY
  121. ALTER SERVICE
  122. ALTER SMDS
  123. ALTER STGCLASS
  124. ALTER SUB
  125. ALTER TOPIC
  126. ALTER TRACE
  127. ARCHIVE LOG
  128. BACKUP CFSTRUCT
  129. CLEAR QLOCAL
  130. CLEAR TOPICSTR
  131. DEFINE AUTHINFO
  132. DEFINE BUFFPOOL
  133. DEFINE CFSTRUCT
  134. DEFINE CHANNEL
  135. Sender channel
  136. Server channel
  137. Receiver channel
  138. Requester channel
  139. Client-connection channel
  140. Server-connection channel
  141. Cluster-sender channel
  142. Cluster-receiver channel
  143. DEFINE CHANNEL (MQTT)
  144. DEFINE COMMINFO
  145. DEFINE LISTENER
  146. DEFINE LOG
  147. DEFINE MAXSMSGS
  148. DEFINE NAMELIST
  149. DEFINE PROCESS
  150. DEFINE PSID
  151. DEFINE queues
  152. DEFINE QALIAS
  153. DEFINE QLOCAL
  154. DEFINE QMODEL
  155. DEFINE QREMOTE
  156. DEFINE SERVICE
  157. DEFINE STGCLASS
  158. DEFINE SUB
  159. DEFINE TOPIC
  160. DELETE AUTHINFO
  161. DELETE AUTHREC
  162. DELETE BUFFPOOL
  163. DELETE CFSTRUCT
  164. DELETE CHANNEL
  165. DELETE CHANNEL (MQTT)
  166. DELETE COMMINFO
  167. DELETE LISTENER
  168. DELETE NAMELIST
  169. DELETE PROCESS
  170. DELETE PSID
  171. DELETE queues
  172. DELETE QALIAS
  173. DELETE QLOCAL
  174. DELETE QMODEL
  175. DELETE QREMOTE
  176. DELETE SERVICE
  177. DELETE SUB
  178. DELETE STGCLASS
  179. DELETE TOPIC
  180. DISPLAY ARCHIVE
  181. DISPLAY AUTHINFO
  182. DISPLAY AUTHREC
  183. DISPLAY AUTHSERV
  184. DISPLAY CFSTATUS
  185. DISPLAY CFSTRUCT
  186. DISPLAY CHANNEL
  187. DISPLAY CHANNEL (MQTT)
  188. DISPLAY CHINIT
  189. DISPLAY CHLAUTH
  190. Generic IP addresses
  191. DISPLAY CHSTATUS
  192. DISPLAY CHSTATUS (MQTT)
  193. DISPLAY CLUSQMGR
  194. DISPLAY CMDSERV
  195. DISPLAY COMMINFO
  196. DISPLAY CONN
  197. DISPLAY ENTAUTH
  198. DISPLAY GROUP
  199. DISPLAY LISTENER
  200. DISPLAY LOG
  201. DISPLAY LSSTATUS
  202. DISPLAY MAXSMSGS
  203. DISPLAY NAMELIST
  204. DISPLAY PROCESS
  205. DISPLAY PUBSUB
  206. DISPLAY QMGR
  207. DISPLAY QMSTATUS
  208. DISPLAY QSTATUS
  209. DISPLAY QUEUE
  210. DISPLAY SBSTATUS
  211. DISPLAY SECURITY
  212. DISPLAY SERVICE
  213. DISPLAY SMDS
  214. DISPLAY SMDSCONN
  215. DISPLAY STGCLASS
  216. DISPLAY SUB
  217. DISPLAY SVSTATUS
  218. DISPLAY SYSTEM
  219. DISPLAY THREAD
  220. DISPLAY TOPIC
  221. DISPLAY TPSTATUS
  222. DISPLAY TRACE
  223. DISPLAY USAGE
  224. MOVE QLOCAL
  225. PING CHANNEL
  226. PING QMGR
  227. PURGE CHANNEL
  228. RECOVER CFSTRUCT
  229. REFRESH CLUSTER
  230. REFRESH QMGR
  231. REFRESH SECURITY
  232. RESET CFSTRUCT
  233. RESET CHANNEL
  234. RESET CLUSTER
  235. RESET QMGR
  236. RESET QSTATS
  237. RESET SMDS
  238. RESET TPIPE
  239. RESOLVE CHANNEL
  240. RESOLVE INDOUBT
  241. RESUME QMGR
  242. RVERIFY SECURITY
  243. SET ARCHIVE
  244. SET AUTHREC
  245. SET CHLAUTH
  246. Generic IP addresses
  247. SET LOG
  248. SET SYSTEM
  249. START CHANNEL
  250. START CHANNEL (MQTT)
  251. START CHINIT
  252. START CMDSERV
  253. START LISTENER
  254. START QMGR
  255. START SERVICE
  256. START SMDSCONN
  257. START TRACE
  258. STOP CHANNEL
  259. STOP CHANNEL (MQTT)
  260. STOP CHINIT
  261. STOP CMDSERV
  262. STOP CONN
  263. STOP LISTENER
  264. STOP QMGR
  265. STOP SERVICE
  266. STOP SMDSCONN
  267. STOP TRACE
  268. SUSPEND QMGR
  269. Programmable command formats reference
  270. Definitions of the Programmable Command Formats
  271. How the definitions are shown
  272. PCF commands and responses in groups
  273. Backup CF Structure
  274. Change, Copy, and Create Authentication Information Object
  275. Change, Copy, and Create CF Structure
  276. Change, Copy, and Create Channel
  277. Change, Copy, and Create Channel (MQTT)
  278. Change, Copy, and Create Channel Listener
  279. Change, Copy, and Create Communication Information Object
  280. Change, Copy, and Create Namelist
  281. Change, Copy, and Create Process
  282. Change, Copy, and Create Queue
  283. Change Queue Manager
  284. Change Security
  285. Change SMDS
  286. Change, Copy, and Create Service
  287. Change, Copy, and Create Storage Class
  288. Change, Copy, and Create Subscription
  289. Change, Copy, and Create Topic
  290. Clear Queue
  291. Clear Topic String
  292. Delete Authentication Information Object
  293. Delete Authority Record
  294. Delete CF Structure
  295. Delete Channel
  296. Delete Channel (MQTT)
  297. Delete Channel Listener
  298. Delete Communication Information Object
  299. Delete Namelist
  300. Delete Process
  301. Delete Queue
  302. Delete Service
  303. Delete Storage Class
  304. Delete Subscription
  305. Delete Topic
  306. Escape
  307. Escape (Response)
  308. Inquire Archive
  309. Inquire Archive (Response)
  310. Inquire Authentication Information Object
  311. Inquire Authentication Information Object (Response)
  312. Inquire Authentication Information Object Names
  313. Inquire Authentication Information Object Names (Response)
  314. Inquire Authority Records
  315. Inquire Authority Records (Response)
  316. Inquire Authority Service
  317. Inquire Authority Service (Response)
  318. Inquire CF Structure
  319. Inquire CF Structure (Response)
  320. Inquire CF Structure Names
  321. Inquire CF Structure Names (Response)
  322. Inquire CF Structure Status
  323. Inquire CF Structure Status (Response)
  324. Inquire Channel
  325. Inquire Channel (MQTT)
  326. Inquire Channel (Response)
  327. Inquire Channel Authentication Records
  328. Inquire Channel Authentication Records (Response)
  329. Inquire Channel Initiator
  330. Inquire Channel Initiator (Response)
  331. Inquire Channel Listener
  332. Inquire Channel Listener (Response)
  333. Inquire Channel Listener Status
  334. Inquire Channel Listener Status (Response)
  335. Inquire Channel Names
  336. Inquire Channel Names (Response)
  337. Inquire Channel Status
  338. Inquire Channel Status (MQTT)
  339. Inquire Channel Status (Response)
  340. Inquire Channel Status (Response)
  341. Inquire Cluster Queue Manager
  342. Inquire Cluster Queue Manager (Response)
  343. Inquire Communication Information Object
  344. Inquire Communication Information Object (Response)
  345. Inquire Connection
  346. Inquire Connection (Response)
  347. Inquire Entity Authority
  348. Inquire Entity Authority (Response)
  349. Inquire Group
  350. Inquire Group (Response)
  351. Inquire Log
  352. Inquire Log (Response)
  353. Inquire Namelist
  354. Inquire Namelist (Response)
  355. Inquire Namelist Names
  356. Inquire Namelist Names (Response)
  357. Inquire Process
  358. Inquire Process (Response)
  359. Inquire Process Names
  360. Inquire Process Names (Response)
  361. Inquire Pub/Sub Status
  362. Inquire Pub/Sub Status (Response)
  363. Inquire Queue
  364. Inquire Queue (Response)
  365. Inquire Queue Manager
  366. Inquire Queue Manager (Response)
  367. Inquire Queue Manager Status
  368. Inquire Queue Manager Status (Response)
  369. Inquire Queue Names
  370. Inquire Queue Names (Response)
  371. Inquire Queue Status
  372. Inquire Queue Status (Response)
  373. Inquire Security
  374. Inquire Security (Response)
  375. Inquire Service
  376. Inquire Service (Response)
  377. Inquire Service Status
  378. Inquire Service Status (Response)
  379. DISPLAY SMDS
  380. Inquire SMDS (Response)
  381. Inquire SMDS Connection
  382. Inquire SMDS Connection (Response)
  383. Inquire Storage Class
  384. Inquire Storage Class (Response)
  385. Inquire Storage Class Names
  386. Inquire Storage Class Names (Response)
  387. Inquire Subscription
  388. Inquire Subscription (Response)
  389. Inquire Subscription Status
  390. Inquire Subscription Status (Response)
  391. Inquire System
  392. Inquire System (Response)
  393. Inquire Topic
  394. Inquire Topic (Response)
  395. Inquire Topic Names
  396. Inquire Topic Names (Response)
  397. Inquire Topic Status
  398. Inquire Topic Status (Response)
  399. Inquire Usage
  400. Inquire Usage (Response)
  401. Move Queue
  402. Ping Channel
  403. Ping Queue Manager
  404. Purge Channel
  405. Recover CF Structure
  406. Refresh Cluster
  407. Refresh Queue Manager
  408. Refresh Security
  409. Reset CF Structure
  410. Reset Channel
  411. Reset Cluster
  412. Reset Queue Manager
  413. Reset Queue Statistics
  414. Reset Queue Statistics (Response)
  415. Reset SMDS
  416. Resolve Channel
  417. Resume Queue Manager
  418. Resume Queue Manager Cluster
  419. Reverify Security
  420. Set Archive
  421. Set Authority Record
  422. Set Channel Authentication Record
  423. Set Log
  424. Set System
  425. Start Channel
  426. Start Channel (MQTT)
  427. Start Channel Initiator
  428. Start Channel Listener
  429. Start Service
  430. Start SMDS Connection
  431. Stop Channel
  432. Stop Channel (MQTT)
  433. Stop Channel Initiator
  434. Stop Channel Listener
  435. Stop Connection
  436. Stop Service
  437. Stop SMDS Connection
  438. Suspend Queue Manager
  439. Suspend Queue Manager Cluster
  440. Structures for commands and responses
  441. How the structures are shown
  442. Usage notes
  443. MQCFH - PCF header
  444. MQCFBF - PCF byte string filter parameter
  445. MQCFBS - PCF byte string parameter
  446. MQCFIF - PCF integer filter parameter
  447. MQCFIL - PCF integer list parameter
  448. MQCFIN - PCF integer parameter
  449. MQCFSF - PCF string filter parameter
  450. MQCFSL - PCF string list parameter
  451. MQCFST - PCF string parameter
  452. PCF example
  453. WebSphere MQ Administration Interface
  454. MQAI reference
  455. mqAddBag
  456. mqAddByteString
  457. mqAddByteStringFilter
  458. mqAddInquiry
  459. mqAddInteger
  460. mqAddInteger64
  461. mqAddIntegerFilter
  462. mqAddString
  463. mqAddStringFilter
  464. mqBagToBuffer
  465. mqBufferToBag
  466. mqClearBag
  467. mqCountItems
  468. mqCreateBag
  469. mqDeleteBag
  470. mqDeleteItem
  471. mqExecute
  472. mqGetBag
  473. mqInquireBag
  474. mqInquireByteString
  475. mqInquireByteStringFilter
  476. mqInquireInteger
  477. mqInquireInteger64
  478. mqInquireIntegerFilter
  479. mqInquireItemInfo
  480. mqInquireString
  481. mqInquireStringFilter
  482. mqPad
  483. mqPutBag
  484. mqSetByteString
  485. mqSetByteStringFilter
  486. mqSetInteger
  487. mqSetInteger64
  488. mqSetIntegerFilter
  489. mqSetString
  490. mqSetStringFilter
  491. mqTrim
  492. mqTruncateBag
  493. MQAI Selectors
  494. Indexing
  495. Data conversion
  496. Use of the message descriptor
  497. Example code


How to read railroad diagrams

Each railroad diagram begins with a double right arrow and ends with a right and left arrow pair. Lines beginning with a single right arrow are continuation lines. You read a railroad diagram from left to right and from top to bottom, following the direction of the arrows.

Other conventions used in railroad diagrams are:

How to read railroad diagrams

Convention Meaning

 
>>-A--B--C---------------------------------><


You must specify values A, B, and C. Required values are shown on the main line of a railroad diagram.
 >>-+---+-----------------------------------><
   '-A-'   


You may specify value A. Optional values are shown below the main line of a railroad diagram.
 >>-+-A-+-----------------------------------><
   +-B-+   
   '-C-'   
Values A, B, and C are alternatives, one of which you must specify.
 
>>-+---+-----------------------------------><
   +-A-+   
   +-B-+   
   '-C-'   
Values A, B, and C are alternatives, one of which you might specify.
 
   .-,-----.   
   V       |   
>>---+---+-+-------------------------------><
     +-A-+     
     +-B-+     
     '-C-'     
You might specify one or more of the values A, B, and C. Any required separator for multiple or repeated values (in this example, the comma (,)) is shown on the arrow.
 
   .-+---+-.   
   | '-,-' |   
   V       |   
>>---+---+-+-------------------------------><
     '-A-'     
You might specify value A multiple times. The separator in this example is optional.
 
   .-A-.   
>>-+---+-----------------------------------><
   +-B-+   
   '-C-'   
Values A, B, and C are alternatives, one of which you might specify. If you specify none of the values shown, the default A (the value shown above the main line) is used.
 >>-| Name |--------------------------------><

Name

|--A--+---+---------------------------------|
      '-B-'   


The railroad fragment Name is shown separately from the main railroad diagram.
Punctuation and uppercase values Specify exactly as shown.


WebSphere MQ Control commands

To issue control commands, the user ID must be a member of the mqm group.

When using control commands that operate on a queue manager, you must use the command from the installation associated with the queue manager you are working with.

On Windows, all control commands can be issued from a command line. Command names and their flags are not case-sensitive: you can enter them in uppercase, lowercase, or a combination of uppercase and lowercase. However, arguments to control commands (such as queue names) are case-sensitive.

In the syntax descriptions, the hyphen (-) is used as a flag indicator. You can use the forward slash (/) instead of the hyphen.

On UNIX and Linux systems, all WebSphere MQ control commands can be issued from a shell. All commands are case-sensitive.

A subset of the control commands can be issued using the WebSphere MQ Explorer.

See also:


Use control commands

Three categories of control commands:

Control commands can be divided into three categories...

Category Description
Queue manager Commands for creating, starting, stopping, and deleting queue managers and command servers
Channel Commands for starting and ending channels and channel initiators
Utility commands Utility commands include commands associated with:

  • Run MQSC commands
  • Conversion exits
  • Authority management
  • Record and recover media images of queue manager resources
  • Display and resolve transactions
  • Trigger monitors
  • Display the file names of WebSphere MQ objects

For more information, see WebSphere MQ Control commands


Use control commands on Windows systems

In WebSphere MQ for Windows, you enter control commands at a command prompt. In Windows environments, control commands and their flags are not case-sensitive, but arguments to those commands (such as queue names and queue-manager names) are case-sensitive. For example, in the command:

For more information, see WebSphere MQ control commands .


Use control commands on UNIX and Linux systems

In WebSphere MQ for UNIX and Linux systems, you enter control commands in a shell window.

In UNIX environments, control commands, including the command name itself, the flags, and any arguments, are case-sensitive. For example, in the command:

 crtmqm -u SYSTEM.DEAD.LETTER.QUEUE jupiter.queue.manager

Take care to type the commands exactly as you see them in the examples.

For more information about the crtmqm command, see crtmqm .

For more information on control commands, see WebSphere MQ Control commands


The control commands

This collection of topics provides reference information for each of the WebSphere MQ control commands. These control commands require that the ID is in the mqm group.


addmqinf

Add WebSphere MQ configuration information (Windows and UNIX platforms only).


Purpose

Use the addmqinf command to add information to the WebSphere MQ configuration data.

For example, use dspmqinf and addmqinf to copy configuration data from the system where a queue manager was created, to other systems where the same multi-instance queue manager is also to be started.


Syntax

   
                                    .-------------------------.   
             .- -s -QueueManager-.  V                         |   
>>-addmqinf -+-------------------+---- -v -  Attribute =  Value-+-><
             '- -s - StanzaType---'                                



Required parameters

-v Attribute=Value
The name and value of the stanza attributes to be placed in the stanza specified in the command.
Table 1 lists the QueueManager stanza attribute values. The queue manager stanza is the only stanza that is currently supported.

QueueManager stanza attributes

Attribute Value Required or optional
Name The name of the queue manager.

You must provide a different name from any other queue manager stanza on the system.

Required
Prefix The directory path under which this queue manager data directory is stored by default.

You can use Prefix to modify the location of the queue manager data directories. The value of Directory is automatically appended to this path.

Required
Directory The name of the queue manager data directory.

Sometimes the name must be provided (as in Example ), because it is different from the queue manager name. Copy the directory name from the value returned by dspmqinf.

The rules for transforming queue manager names into directory names are described in Understanding WebSphere MQ file names .

Required
DataPath The directory path where the queue manager data files are placed. The value of Directory is not automatically appended to this path - you must provide the transformed queue manager name as part of DataPath.

If the DataPath attribute is omitted on UNIX, the queue manager data directory path is defined as Prefix / Directory .

UNIX: Optional
Windows: Required


Optional parameters

-s StanzaType
A stanza of the type StanzaType is added to the WebSphere MQ configuration.
The default value of StanzaType is QueueManager.
The only supported value of StanzaType is QueueManager.


Return codes

Return code Description
0 Successful operation
1 Queue manager location is invalid (either Prefix or DataPath)
39 Bad command-line parameters
45 Stanza already exists
46 Required configuration attribute is missing
58 Inconsistent use of installations detected
69 Storage is not available
71 Unexpected error
72 Queue manager name error
100 Log location is invalid


Example

 addmqinf -v DataPath=/MQHA/qmgrs/QM!NAME
  -v Prefix=/var/mqm
  -v Directory=QM!NAME
  -v Name=QM.NAME
Creates the following stanza in mqs.ini:

 QueueManager:
   Name=QM.NAME
   Prefix=/var/mqm
   Directory=QM!NAME
   DataPath=/MQHA/qmgrs/QM!NAME


Usage notes

Use dspmqinf with addmqinf to create an instance of a multi-instance queue manager on a different server.

To use this command you must be a WebSphere MQ administrator and a member of the mqm group.


amqmdain

amqmdain is used to configure or control some Windows specific administrative tasks.


Purpose

The amqmdain command applies to WebSphere MQ for Windows only.

Use amqmdain to perform some Windows specific administrative tasks.

Starting a queue manager with amqmdain is equivalent to using the strmqm command with the option -ss. amqmdain makes the queue manager run in a non-interactive session under a different user account. However, to ensure that all queue manager startup feedback is returned to the command line, use the strmqm -ss command rather than amqmdain.

You must use the amqmdain command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

To administer and define WebSphere MQ service and listener objects, use MQSC commands, PCF commands, or the WebSphere MQ Explorer.

The amqmdain command has been updated to modify either the .ini files or the registry as appropriate.


Syntax

   
>>-amqmdain----------------------------------------------------->

>--+- qmgr start - QMgrName--------------------------+----------><
   |                        .- -c .                 |   
   +- qmgr end - QMgrName--+-+-----+--+-------+-+----+   
   |                      | +- -w +  +- -s~ -+ |    |   
   |                      | +- -i +  '- -r --' |    |   
   |                      | '- -p '            |    |   
   |                      '- -x ---------------'    |   
   +- qmgr alter - QMgrName--+---------------------+-+   
   |                        +- -i - Initiation-----+ |   
   |                        '- -x - Multi-instance-' |   
   +- refresh --------------------------------------+   
   +- auto - QMgrName--------------------------------+   
   +- manual - QMgrName------------------------------+   
   +- status -+----------+--------------------------+   
   |          +- QMgrName-+                          |   
   |          '-all------'                          |   
   +- regsec ---------------------------------------+   
   +- spn - QMgrName--+-set---+----------------------+   
   |                 '-unset-'                      |   
   '- reg -+----------+-- RegParams------------------'   
           +- QMgrName-+                                 
           '- * ------'                                 



Keywords and parameters

All parameters are required unless the description states they are optional.

In every case, QMgrName is the name of the queue manager to which the command applies.

qmgr start QMgrName
Starts a queue manager.

This parameter can also be written in the form start QMgrName.

If you start your queue manager as a service and need the queue manager to continue to run after logoff, use strmqm -ss qmgr instead of amqmdain start qmgr.

qmgr end QMgrName
Ends a queue manager.

This parameter can also be written in the form end QMgrName.

For consistency across platforms, use endmqm qmgr instead of amqmdain end qmgr.

For fuller descriptions of the options, see endmqm .

-c
Controlled (or quiesced) shutdown.
-w
Wait shutdown.
-i
Immediate shut down.
-p
Pre-emptive shut down.
-r
Reconnect clients.
-s
Switch over to a standby queue manager instance.
-x
End the standby instance of the queue manager without ending the active instance.
qmgr alter QMgrName
Alters a queue manager.
-i Initiation
Specifies the initiation type. Possible values are:

Initiation parameters.

Parameter Parameter Description
auto Sets the queue manager to automatic startup (when the machine starts, or more precisely when the WebSphere MQ service starts). The syntax is:

 amqmdain qmgr alter QmgrName -i auto
interactive Sets the queue manager to manual startup that then runs under the logged on (interactive) user. The syntax is:

 amqmdain qmgr alter QmgrName -i interactive
service Sets the queue manager to manual startup that then runs as a service. The syntax is:

 amqmdain qmgr alter QmgrName -i service 

-x Multi-instance
Specifies if auto queue manager start by the WebSphere MQ service permits multiple instances. Equivalent to the -sax option on the crtmqm command. Also specifies if the amqmdain start qmgr command permits standby instances. Possible values are:

Multi-instance parameters.

Parameter Parameter Description
set Sets automatic queue manager startup to permit multiple instances. Issues strmqm -x. The set option is ignored for queue managers that are initiated interactively or as a manual service startup. The syntax of the command is:

 amqmdain qmgr alter QmgrName -x set 
unset Sets automatic queue manager startup to single instance. Issues strmqm. The unset option is ignored for queue managers that are initiated interactively or as a manual service startup. The syntax of the command is:

 amqmdain qmgr alter QmgrName -x unset

refresh
Refreshes or checks the status of a queue manager. You will not see anything returned on the screen after executing this command.
auto QMgrName
Sets a queue manager to automatic startup.
manual QMgrName
Sets a queue manager to manual startup.
status QMgrName | all
These parameters are optional.

Status parameters.

Parameter Parameter Description
If no parameter is supplied: Displays the status of the WebSphere MQ services.
If a QMgrName is supplied: Displays the status of the named queue manager.
If the parameter all is supplied: Displays the status of the WebSphere MQ services and all queue managers.

regsec
Ensures that the security permissions assigned to the Registry keys containing installation information are correct.
spn QMgrName set | unset
You can set or unset the service principal name for a queue manager.
reg QMgrName | * RegParams
Parameters QMgrName, and * are optional.

Reg parameters.

Parameter Parameter Description
If RegParams is specified alone: Modifies queue manager configuration information related to the default queue manager.
If QMgrName and RegParams are specified: Modifies queue manager configuration information related to the queue manager specified by QMgrName.
If * and RegParams are specified: Modifies WebSphere MQ configuration information.

The parameter, RegParams, specifies the stanzas to change, and the changes that are to be made. RegParams takes one of the following forms:

  • -c add -s stanza -v attribute=value
  • -c remove -s stanza -v [attribute|*]
  • -c display -s stanza -v [attribute|*]

If you are specifying queue manager configuration information, the valid values for stanza are:

 XAResourceManager\name
ApiExitLocal\name
Channels
ExitPath
InstanceData
Log
QueueManagerStartup
TCP
LU62
SPX
NetBios
Connection
QMErrorLog
Broker

ExitPropertiesLocal
SSL
If you are modifying WebSphere MQ configuration information, the valid values for stanza are:

 ApiExitCommon\name
ApiExitTemplate\name
ACPI
AllQueueManagers
Channels
DefaultQueueManager
LogDefaults
ExitProperties

The following are usage considerations:

  • amqmdain does not validate the values you specify for name, attribute, or value.
  • When you specify add, and an attribute exists, it is modified.
  • If a stanza does not exist, amqmdain creates it.
  • When you specify remove, you can use the value * to remove all attributes.
  • When you specify display, you can use the value * to display all attributes which have been defined. This value only displays the attributes which have been defined and not the complete list of valid attributes.
  • If you use remove to delete the only attribute in a stanza, the stanza itself is deleted.
  • Any modification you make to the Registry re-secures all WebSphere MQ Registry entries.


Examples

The following example adds an XAResourceManager to queue manager TEST. The commands issued are:

 amqmdain reg TEST -c add -s XAResourceManager\Sample -v SwitchFile=sf1
amqmdain reg TEST -c add -s XAResourceManager\Sample -v ThreadOfControl=THREAD
amqmdain reg TEST -c add -s XAResourceManager\Sample -v XAOpenString=openit
amqmdain reg TEST -c add -s XAResourceManager\Sample -v XACloseString=closeit
To display the values set by the commands above, use:

 amqmdain reg TEST -c display -s XAResourceManager\Sample -v *
The display would look something like the following:

 0784726, 5639-B43 (C) Copyright IBM Corp. 1994, 2002. ALL RIGHTS RESERVED.
Displaying registry value for Queue Manager 'TEST'
        Attribute = Name, Value = Sample
        Attribute = SwitchFile, Value = sf1
        Attribute = ThreadOfControl, Value = THREAD
        Attribute = XAOpenString, Value = openit
        Attribute = XACloseString, Value = closeit   
To remove the XAResourceManager from queue manager TEST, use:

 amqmdain reg TEST -c remove -s XAResourceManager\Sample -v *


Return codes

Return code Description
0 Command completed normally
-2 Syntax error
-3 Failed to initialize MFC
-6 Feature no longer supported
-7 Configuration failed
-9 Unexpected Registry error
-16 Failed to configure service principal name
-29 Inconsistent use of installations detected
62 The queue manager is associated with a different installation
71 Unexpected error
119 Permission denied ( Windows only)

Note:

  1. If the qmgr start QMgrName command is issued, all return codes that can be returned with strmqm , can be returned here also. For a list of these return codes, see strmqm .
  2. If the qmgr end QMgrName command is issued, all return codes that can be returned with endmqm , can be returned here also. For a list of these return codes, see endmqm .


amqmfsck (file system check)

amqmfsck checks whether a shared file system on UNIX and IBM i systems meets the requirements for storing the queue manager data of a multi-instance queue manager.


Purpose

The amqmfsck command applies only to UNIX and IBM i systems. You do not need to check the network drive on Windows. amqmfsck tests that a file system correctly handles concurrent writes to a file and the waiting for and releasing of locks.


Syntax

   
>>-amqmfsck--+-----+--+-----------------------------+-- DirectoryName-><
             '- -v-'  +- -a ------------------------+                  
                      +- -c ------------------------+                  
                      +- -f -+--------------------+-+                  
                      |      |      .-262144----. | |                  
                      |      '- -p -+- PageCount-+-' |                  
                      +- -i ------------------------+                  
                      +- -w ------------------------+                  
                      '- - x -----------------------'                  



Required parameters

DirectoryName
The name of the directory to check.


Optional parameters

-a
Perform the second phase of the data integrity test.
  • Run this on two machines at the same time. You must have formatted the test file using the -f option previously

-c
Test writing to a file in the directory concurrently.
-f
Perform the first phase of the data integrity test.
  • Formats a file in the directory in preparation for data integrity testing.

-i
Perform the third phase of the data integrity test.
  • Checks the integrity of the file after the failure to discover whether the test worked.

-p
Specifies the size of the test file used in the data integrity test in pages. .
  • The size is rounded up to the nearest multiple of 16 pages. The file is formatted with PageCount pages of 4 KB.
  • The optimum size of the file depends on the speed of the filesystem and the nature of the test you perform. If this parameter is omitted, the test file is 262144 pages, or 1 GB.
  • The size is automatically reduced so that the formatting completes in about 60 seconds even on a very slow filesystem.

-v
Verbose output.
-w
Test waiting for and releasing locks.
-x
Deletes any files created by amqmfsck during the testing of the directory.
  • Do not use this option until you have completed the testing, or if you need to change the number of pages used in the integrity test.


Usage

You must be a WebSphere MQ Administrator to run the command. You must have read/write access to the directory being checked.

The command returns an exit code of zero if the tests complete successfully.

The task, Verifying shared file system behavior , describes how to use amqmfsck to check the whether of a file system is suitable for multi-instance queue managers.


Interpreting your results

If the check fails, the file system is not capable of being used by WebSphere MQ queue managers. If the tests fail, choose verbose mode to help you to interpret the errors. The output from the verbose option helps you understand why the command failed, and if the problem can be solved by reconfiguring the file system.

Sometimes the failure might be an access control problem that can be fixed by changing directory ownership or permissions. Sometimes the failure can be fixed by reconfiguring the file system to behave in a different way. For example, some file systems have performance options that might need to be changed. It is also possible that the file system protocol does not support concurrency sufficiently robustly, and you must use a different file system. For example, you must use NFSv4 rather than NFSv3.

If the check succeeds, the command reports The tests on the directory completed successfully. If your environment is not listed as supported in the testing and support statement, this result does not necessarily mean that you can run WebSphere MQ multi-instance queue managers successfully. You must plan and run a variety of tests to satisfy yourself that you have covered all foreseeable circumstances. Some failures are intermittent, and there is a better chance of discovering them if you run the tests more than once.


crtmqcvx

Create data conversion code from data type structures.


Purpose

Use the crtmqcvx command to create a fragment of code that performs data conversion on data type structures. The command generates a C function that can be used in an exit to convert C structures.

The command reads an input file containing structures to be converted, and writes an output file containing code fragments to convert those structures.

For information about using this command, see Utility for creating conversion-exit code .


Syntax

   
>>-crtmqcvx-- SourceFile-- TargetFile----------------------------><



Required parameters

SourceFile
The input file containing the C structures to convert.
TargetFile
The output file containing the code fragments generated to convert the structures.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing


Examples

The following example shows the results of using the data conversion command against a source C structure. The command issued is:

 crtmqcvx source.tmp target.c

The input file, source.tmp, looks like this:

 
 /* This is a test C structure which can be converted by the */
 /* crtmqcvx utility                                         */
 
 struct my_structure
 {
     int    code;
     MQLONG value;
 };
 

The output file, target.c, produced by the command, looks like this:

 MQLONG Convertmy_structure(
              PMQDXP  pExitParms,
              PMQBYTE *in_cursor,
              PMQBYTE *out_cursor,
              PMQBYTE in_lastbyte,
              PMQBYTE out_lastbyte,
              MQHCONN hConn,
              MQLONG  opts,
              MQLONG  MsgEncoding,
              MQLONG  ReqEncoding,
              MQLONG  MsgCCSID,
              MQLONG  ReqCCSID,
              MQLONG  CompCode,
              MQLONG  Reason)
 {
     MQLONG ReturnCode = MQRC_NONE;
 
     ConvertLong(1); /* code */
 
     AlignLong();
     ConvertLong(1); /* value */
 
 Fail:
     return(ReturnCode);
 }
You can use these code fragments in your applications to convert data structures. However, if you do so, the fragment uses macros supplied in the header file amqsvmha.h.


crtmqenv

Create a list of environment variables for an installation of WebSphere MQ, on UNIX, Linux, and Windows.


Purpose

You can use the crtmqenv command to create a list of environment variables with the appropriate values for an installation of WebSphere MQ. The list of environment variables is displayed on the command line, and any variables that exist on the system have the WebSphere MQ values added to them. This command does not set the environment variables for you, but gives you the appropriate strings to set the variables yourself, for example, within your own scripts.

The environment variables set for you in a shell environment, you can use the setmqenv command instead of using the crtmqenv command.

You can specify which installation the environment is created for by specifying a queue manager name, an installation name, or an installation path. You can also create the environment for the installation that issues the crtmqenv command by issuing the command with the -s parameter.

This command lists the following environment variables, and their values, appropriate to your system:

On UNIX and Linux systems, if the -l or -k flag is specified, the LIBPATH environment variable is set on AIX, and the LD_LIBRARY_PATH environment variable is set on HP-UX, Linux, and Solaris.


Usage notes

The crtmqenv command removes all directories for all WebSphere MQ installations from the environment variables before adding new references to the installation for which you are setting up the environment. Therefore, if you want to set any additional environment variables that reference WebSphere MQ, set the variables after issuing the crtmqenv command. For example, if you want to add MQ_INSTALLATION_PATH/java/lib to LD_LIBRARY_PATH, you must do so after running crtmqenv.


Syntax

   
>>-crtmqenv--+- -m-- QMgrName---------+--+-----+--+-----------+--+-----+-><
             +- -n-- InstallationName-+  +- -k-+  '- -x - Mode-'  '- -i-'   
             +- -p-- InstallationPath-+  '- -l '                           
             +- -r-------------------+                                    
             '- -s-------------------'                                    



Required Parameters

-m QMgrName
Create the environment for the installation associated with the queue manager QMgrName.
-n InstallationName
Create the environment for the installation named InstallationName.
-p InstallationPath
Create the environment for the installation in the path InstallationPath.
-r
Remove all installations from the environment.
-s
Create the environment for the installation that issued the command.


Optional Parameters

-k
UNIX and Linux only.
Include the LD_LIBRARY_PATH , or LIBPATH, environment variable in the environment, adding the path to the WebSphere MQ libraries at the start of the current LD_LIBRARY_PATH, or LIBPATH, variable.
-l
UNIX and Linux only.
Include the LD_LIBRARY_PATH, or LIBPATH, environment variable in the environment, adding the path to the WebSphere MQ libraries at the end of the current LD_LIBRARY_PATH, or LIBPATH, variable.
-x Mode
Mode can take the value 32, or 64.
Create a 32-bit or 64-bit environment. If this parameter is not specified, the environment matches that of the queue manager or installation specified in the command.
Any attempt to display a 64-bit environment with a 32-bit installation fails.
-i
List only the additions to the environment.
When this parameter is specified, the environment variables set for previous installations remain in the environment variable path and must be manually removed.


Return codes

Return code Description
0 Command completed normally.
10 Command completed with unexpected results.
20 An error occurred during processing.


Examples

The following examples assume that a copy of WebSphere MQ is installed in /opt/mqm on a UNIX or Linux system.

  1. This command creates a list of environment variables for an installation installed in /opt/mqm:

     /opt/mqm/bin/crtmqenv -s
    
  2. This command creates a list of environment variables for an installation installed in /opt/mqm2, and includes the path to the installation at the end of the current value of the LD_LIBRARY_PATH variable:

     /opt/mqm/bin/crtmqenv -p /opt/mqm2 -l
    
  3. This command creates a list of environment variables for the queue manager QM1, in a 32-bit environment:

     /opt/mqm/bin/crtmqenv -m QM1 -x 32
    

The following example assumes that a copy of WebSphere MQ is installed in c:\Program Files\IBM\WebSphere MQ on a Windows system.

  1. This command creates a list of environment variables for an installation called installation1:

     "c:\Program Files\IBM\WebSphere MQ\crtmqenv" -n installation1
    


crtmqinst

Create installation entries in mqinst.ini on UNIX and Linux systems.


Purpose

File mqinst.ini contains information about all WebSphere MQ installations on a system. For more information about mqinst.ini, see Installation configuration file, mqinst.ini .

The first WebSphere MQ installation is automatically given an installation name of Installation1 because the crtmqinst command is not available until an installation of WebSphere MQ is on the system. Subsequent installations can have an installation name set before installation occurs, by using the crtmqinst command. The installation name cannot be changed after installation. For more information about installation names, see Choosing an installation name .


Syntax

   
>>-crtmqinst----+- -p - InstallationPath----------------------------+--+----------------------+---><
                +- -n - InstallationName----------------------------+  '- -d - DescriptiveText-'     
                |                                              (1) |                               
                +- -p - InstallationPath-- -n - InstallationName-----+                               
                |                                              (1) |                               
                '- -n-- InstallationName-- -p - InstallationPath-----'                               


Notes:

  1. When specified together, the installation name and installation path must refer to the same installation.


Parameters

-d
Text that describes the installation.

The text can be up to 64 single-byte characters, or 32 double-byte characters. The default value is all blanks. You must use quotation marks around the text if it contains spaces.

-n InstallationName
The name of the installation.

The name can contain up to 16 single-byte characters and must be a combination of alphabetic and numeric characters in the ranges a-z, A-Z, and 0-9. The installation name must be unique, regardless of whether uppercase or lowercase characters are used. For example, the names INSTALLATIONNAME and InstallationName are not unique. If you do not supply the installation name, the next available name in the series Installation1, Installation2... is used.

-p InstallationPath
The installation path. If you do not supply the installation path, /opt/mqm is used on UNIX and Linux systems, and /usr/mqm is used on AIX.


Return codes

Return code Description
0 Entry created without error
10 Invalid installation level
36 Invalid arguments supplied
37 Descriptive text was in error
45 Entry already exists
59 Invalid installation specified
71 Unexpected error
89 .ini file error
96 Could not lock .ini file
98 Insufficient authority to access .ini file
131 Resource problem


Example

  1. This command creates an entry with an installation name of myInstallation, an installation path of /opt/myInstallation, and a description My WebSphere MQ installation :

     crtmqinst -n MyInstallation -p /opt/myInstallation -d "My WebSphere MQ installation" 
    

Quotation marks are needed because the descriptive text contains spaces.


crtmqm

Create a queue manager.


Purpose

Use the crtmqm command to create a queue manager and define the default and system objects. The objects created by the crtmqm command are listed in System and default objects . When you have created a queue manager, use the strmqm command to start it.

The queue manager is automatically associated with the installation from which the crtmqm command was issued. To change the associated installation, use the setmqm command. Note that the Windows installer does not automatically add the user that performs the installation to the mqm group. For more details, see Authority to administer WebSphere MQ on UNIX, Linux and Windows systems .


Syntax

   
>>-crtmqm--+-----------------------------+--+-----------+------->
           |                         (1) |  '- -c - Text-'   
           '- -a [r]-- <access group>-----'                  

>--+-------------------------------+---------------------------->
   '- -d - DefaultTransmissionQueue-'   

                                .- -lc-.                      
>--+-------------------------+--+------+--+---------------+----->
   '- -h - MaximumHandleLimit-'  '- -ll-'  '- -ld - LogPath-'   

>--+--------------------+--+-----------------------+------------>
   '- -lf - LogFilePages-'  '- -lp - LogPrimaryFiles-'   

                                         .- -ss--.   
>--+-------------------------+--+-----+--+-------+-------------->
   '- -ls - LogSecondaryFiles-'  '- -q '  +- -sa--+   
                                         +- -sax-+   
                                         '- -si--'   

>--+----------------+--+-----------------------+---------------->
   '- -md - DataPath-'  '- -g - ApplicationGroup-'   

>--+--------------------+--+----------------------+------------->
   '- -t - IntervalValue-'  '- -u - DeadLetterQueue-'   

>--+---------------------------------+--+-----+-- QMgrName------><
   '- -x - MaximumUncommittedMessages-'  '- -z '             


Notes:

  1. Windows only


Required parameters

QMgrName
The name of the queue manager that you want to create. The name can contain up to 48 characters. This parameter must be the last item in the command.

Note: WebSphere MQ checks if the queue manager name exists. If the name already exists in the directory, then a suffix of .000,.001,.002, and so on, is added to the queue manager name. For example, if a queue manager QM1 is added to the directory and if QM1 already exists, then a queue manager with the name QM1.000 (suffix .000) is created.


Optional parameters

-a[r]access group
Use the access group parameter to specify a Windows security group, members of which will be granted full access to all queue manager data files. The group can either be a local or global group, depending on the syntax used.

Valid syntax for the group name is as follows:

  • LocalGroup
  • Domain name \ GlobalGroup name
  • GlobalGroup name@Domain name

You must define the additional access group before running the crtmqm command with the -a [r] option.

If you specify the group using -ar instead of --a , the local mqm group is not granted access to the queue manager data files. Use this option if the file system hosting the queue manager data files does not support access control entries for locally defined groups.

The group is typically a global security group, which is used to provide multi-instance queue managers with access to a shared queue manager data and logs folder. Use the additional security access group to set read and write permissions on the folder or to share containing queue manager data and log files.

The additional security access group is an alternative to using the local group named mqm to set permissions on the folder containing queue manager data and logs. Unlike the local group mqm, you can make the additional security access group a local or a global group. It must be a global group to set permissions on the shared folders that contain the data and log files used by multi-instance queue managers.

The Windows operating system checks the access permissions to read and write queue manager data and log files. It checks the permissions of the user ID that is running queue manager processes. The user ID that is checked depends on whether you started the queue manager as a service or you started it interactively. If you started the queue manager as a service, the user ID checked by the Windows system is the user ID you configured with the Prepare WebSphere MQ wizard. If you started the queue manager interactively, the user ID checked by the Windows system is the user ID that ran the strmqm command.

The user ID must be a member of the local mqm group to start the queue manager. If the user ID is a member of the additional security access group, the queue manager can read and write files that are given permissions by using the group.

Restriction: You can specify an additional security access group only on Windows operating system. If you specify an additional security access group on other operating systems, the crtmqm command returns an error.

-c Text
Descriptive text for this queue manager. You can use up to 64 characters; the default is all blanks.

If you include special characters, enclose the description in single quotation marks. The maximum number of characters is reduced if the system is using a double-byte character set (DBCS).

-d DefaultTransmissionQueue
The name of the local transmission queue where remote messages are put if a transmission queue is not explicitly defined for their destination. There is no default.
-g ApplicationGroup
The name of the group that contains members that are allowed to perform the following actions:

  • Run MQI applications
  • Update all IPCC resources
  • Change the contents of some queue manager directories

This option applies to WebSphere MQ for AIX, Solaris, HP-UX, and Linux.

The default value is -g all , which allows unrestricted access.

The -g ApplicationGroup value is recorded in the queue manager configuration file named, qm.ini.

The mqm user ID and the user running the command must belong to the specified Application Group. For further details of the operation of restricted mode, see Restricted mode .

-h MaximumHandleLimit
The maximum number of handles that an application can open at the same time.

Specify a value in the range 1 - 999999999. The default value is 256.

The next set of parameter descriptions relate to logging, which is described in Using the log for recovery .

Note: Choose the logging arrangements with care, because some cannot be changed after they are committed.

-lc
Use circular logging. This method is the default logging method.
-ld LogPath
The directory used to store log files. The default directory to store log paths is defined when you install WebSphere MQ.

If the volume containing the log file directory supports file security, the log file directory must have access permissions. The permissions allow the user IDs, under whose authority the queue manager runs, read and write access to the directory and its subdirectories. When you install WebSphere MQ, you grant permissions to the user IDs and to the mqm group on the default log directory. If you set the LogPath parameter to write the log file to a different directory, you must grant the user IDs permission to read and write to the directory. The user ID and permissions for UNIX and Linux are different from those for the Windows system:

UNIX and Linux

The directory and its subdirectories must be owned by the user mqm in the group mqm.

If the log file is shared between different instances of the queue manager, the security identifiers (sid) that are used must be the same for the different instances. You must have set the user mqm to the same sid on the different servers running instances of the queue manager. Likewise for the group mqm .

Windows

If the directory is accessed by only one instance of the queue manager, you must give read and write access permission to the directory for the following groups and users:

  • The local group mqm
  • The local group Administrators
  • The SYSTEM user ID

To give different instances of a queue manager access to the shared log directory, the queue manager must access the log directory using a global user. Give the global group, which contains the global user, read and write access permission to the log directory. The global group is the additional security access group specified in the -a parameter.

In WebSphere MQ for Windows systems, the default directory is C:\Program Files\IBM\WebSphere MQ\log (assuming that C is your data drive). If the volume supports file security, the SYSTEM ID, Administrators, and mqm group must be granted read/write access to the directory.

In WebSphere MQ for UNIX and Linux systems, the default directory is /var/mqm/log. User ID mqm and group mqm must have full authorities to the log files.

If you change the locations of these files, you must give these authorities yourself. If these authorities are set automatically, then the log files are in their default locations.

-lf LogFilePages
The log data is held in a series of files called log files. The log file size is specified in units of 4 KB pages.

In WebSphere MQ for UNIX and Linux systems, the default number of log file pages is 4096, giving a log file size of 16 MB. The minimum number of log file pages is 64 and the maximum is 65535.

In WebSphere MQ for Windows systems, the default number of log file pages is 4096, giving a log file size of 16 MB. The minimum number of log file pages is 32 and the maximum is 65535.

Note: The size of the log files for a queue manager specified during creation of that queue manager cannot be changed.

-llLinearLogging
Use linear logging.
-lp LogPrimaryFiles
The log files allocated when the queue manager is created.

On a Windows system, the minimum number of primary log files you can have is 2 and the maximum is 254. On UNIX and Linux systems, the minimum number of primary log files you can have is 2 and the maximum is 510. The default is 3.

On a Windows system, the total number of primary and secondary log files must not exceed 255 and must not be less than 3. On UNIX and Linux systems the total number of primary and secondary log files must not exceed 511 and must not be less than 3.

Operating system limits can reduce the maximum log size.

The value is examined when the queue manager is created or started. You can change it after the queue manager has been created. However, a change in the value is not effective until the queue manager is restarted, and the effect might not be immediate.

For more information about primary log files, see What logs look like .

To calculate the size of the primary log files, see Calculating the size of the log .

-ls LogSecondaryFiles
The log files allocated when the primary files are exhausted.

On a Windows system, the minimum number of secondary log files you can have is 1 and the maximum is 253. On UNIX and Linux systems, the minimum number of secondary log files you can have is 2 and the maximum is 509. The default is 2.

On a Windows system, the total number of secondary and secondary log files must not exceed 255 and must not be less than 3. On UNIX and Linux systems the total number of primary and secondary log files must not exceed 511 and must not be less than 3.

Operating system limits can reduce the maximum log size.

The value is examined when the queue manager is started. You can change this value, but changes do not become effective until the queue manager is restarted, and even then the effect might not be immediate.

For more information about the use of secondary log files, see What logs look like .

To calculate the size of the secondary log files, see Calculating the size of the log .

-md DataPath
The directory used to hold the data files for a queue manager.

In WebSphere MQ for Windows systems, the default is C:\Program Files\IBM\WebSphere MQ\qmgrs (assuming that C: is your data drive). If the volume supports file security, the SYSTEM ID, Administrators, and mqm group must be granted read/write access to the directory.

In WebSphere MQ for UNIX and Linux systems, the default is /var/mqm/qmgrs. User ID mqm and group mqm must have full authorities to the log files.

The DataPath parameter is provided to assist in the configuration of multi-instance queue managers. For example, on UNIX and Linux systems: if the /var/mqm directory is located on a local file system, use the DataPath parameter and the LogPath parameter to point to the shared file systems accessible to multiple queue managers.

Note: A queue manager created using DataPath parameter runs on versions of WebSphere MQ earlier than version 7.0.1, but the queue manager must be reconfigured to remove the DataPath parameter. You have two options to restore the queue manager to a pre-version 7.0.1 configuration and run without the DataPath parameter: If you are confident about editing queue manager configurations, you can manually configure the queue manager using the Prefix queue manager configuration parameter. Alternatively, complete the following steps to edit the queue manager:

  1. Stop the queue manager.
  2. Save the queue manager data and log directories.
  3. Delete the queue manager.
  4. Backout WebSphere MQ to the pre-v7.0.1 fix level.
  5. Create the queue manager with the same name.
  6. Replace the new queue manager data and log directories with the ones you saved.

-q
Makes this queue manager the default queue manager. The new queue manager replaces any existing default queue manager.

If you accidentally use this flag and you want to revert to an existing queue manager as the default queue manager, change the default queue manager as described in Making an existing queue manager the default .

-sa
Automatic queue manager startup. For Windows systems only.

The queue manager is configured to start automatically when the WebSphere MQ Service starts.

This is the default option if you create a queue manager from WebSphere MQ Explorer.

Queue managers created in WebSphere MQ releases earlier than Version 7 retain their existing startup type.

-sax
Automatic queue manager startup, permitting multiple instances. For Windows systems only.

The queue manager is configured to start automatically when the WebSphere MQ Service starts.

If an instance of the queue manager is not already running the queue manager starts, the instance becomes active, and standby instances are permitted elsewhere. If a queue manager instance that permits standbys is already active on a different server, the new instance becomes a standby instance.

Only one instance of a queue manager can run on a server.

Queue managers created in WebSphere MQ versions earlier than Version 7.0.1 retain their existing startup type.

-si
Interactive (manual) queue manager startup.

The queue manager is configured to start only when you manually request startup by using the strmqm command. The queue manager runs under the (interactive) user when that user is logged-on. Queue managers configured with interactive startup end when the user who started them logs off.

-ss
Service (manual) queue manager startup.

A queue manager configured to start only when manually requested by using the strmqm command. The queue manager then runs as a child process of the service when the WebSphere MQ Service starts. Queue managers configured with service startup continue to run even after the interactive user has logged off.

This is the default option if you create a queue manager from the command line.

-t IntervalValue
The trigger time interval in milliseconds for all queues controlled by this queue manager. This value specifies the length of time triggering is suspended, after the queue manager receives a trigger-generating message. That is, if the arrival of a message on a queue causes a trigger message to be put on the initiation queue, any message arriving on the same queue within the specified interval does not generate another trigger message.

You can use the trigger time interval to ensure that your application is allowed sufficient time to deal with a trigger condition before it is alerted to deal with another trigger condition on the same queue. You might choose to see all trigger events that happen; if so, set a low or zero value in this field.

Specify a value in the range 0 - 999999999. The default is 999999999 milliseconds; a time of more than 11 days. Allowing the default to be used effectively means that triggering is disabled after the first trigger message. However, an application can enable triggering again by servicing the queue using a command to alter the queue to reset the trigger attribute.

-u DeadLetterQueue
The name of the local queue that is to be used as the dead-letter (undelivered-message) queue. Messages are put on this queue if they cannot be routed to their correct destination.

The default is no dead-letter queue.

-x MaximumUncommittedMessages
The maximum number of uncommitted messages under any one sync point. The uncommitted messages are the sum of:

  • The number of messages that can be retrieved from queues
  • The number of messages that can be put on queues
  • Any trigger messages generated within this unit of work

This limit does not apply to messages that are retrieved or put outside a sync point.

Specify a value in the range 1 - 999999999. The default value is 10000 uncommitted messages.

-z
Suppresses error messages.

This flag is used within WebSphere MQ to suppress unwanted error messages. Do not use this flag when using a command line. Using this flag can result in a loss of information.


Return codes

Return code Description
0 Queue manager created
8 Queue manager exists
39 Invalid parameter specified
49 Queue manager stopping
58 Inconsistent use of installations detected
69 Storage unavailable
70 Queue space unavailable
71 Unexpected error
72 Queue manager name error
74 The WebSphere MQ service is not started.
100 Log location invalid
111 Queue manager created. However, there was a problem processing the default queue manager definition in the product configuration file. The default queue manager specification might be incorrect.
115 Invalid log size
119 Permission denied (Windows only)


Examples


Related commands

Command Description
strmqm Start queue manager
endmqm End queue manager
dltmqm Delete queue manager
setmqm Set associated installation


dltmqinst

Delete installation entries from mqinst.ini on UNIX and Linux systems.


Purpose

File mqinst.ini contains information about all WebSphere MQ installations on a system. For more information about mqinst.ini, see Installation configuration file, mqinst.ini .


Syntax

   
>>-dltmqinst----+- -p - InstallationPath----------------------------+---><
                +- -n - InstallationName----------------------------+     
                |                                              (1) |     
                +- -p - InstallationPath-- -n - InstallationName-----+     
                |                                              (1) |     
                '- -n - InstallationName-- -p - InstallationPath-----'     


Notes:

  1. When specified together, the installation name and installation path must refer to the same installation.


Parameters

-n InstallationName
The name of the installation.
-p InstallationPath
The installation path is the location where WebSphere MQ is installed.


Return codes

Return code Description
0 Entry deleted without error
5 Entry still active
36 Invalid arguments supplied
44 Entry does not exist
59 Invalid installation specified
71 Unexpected error
89 ini file error
96 Could not lock ini file
98 Insufficient authority to access ini file
131 Resource problem


Example

  1. This command deletes an entry with an installation name of myInstallation, and an installation path of /opt/myInstallation:

     dltmqinst -n MyInstallation -p /opt/myInstallation
    

Note: You can only use the dltmqinst command on another installation from the one it runs from. If you only have one WebSphere MQ installation, the command will not work.


dltmqm

Delete a queue manager.


Purpose

Use the dltmqm command to delete a specified queue manager and all objects associated with it. Before you can delete a queue manager, you must end it using the endmqm command.

You must use the dltmqm command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

In WebSphere MQ for Windows, it is an error to delete a queue manager when queue manager files are open. If you get this error, close the files and reissue the command.


Syntax

   
>>-dltmqm--+------+-- QMgrName----------------------------------><
           '- -z -'             



Required parameters

QMgrName
The name of the queue manager to delete.


Optional parameters

-z
Suppresses error messages.


Return codes

Return code Description
0 Queue manager deleted
3 Queue manager being created
5 Queue manager running
16 Queue manager does not exist
24 A process that was using the previous instance of the queue manager has not yet disconnected.
25 An error occurred while creating or checking the directory structure for the queue manager.
26 Queue manager running as a standby instance.
27 Queue manager could not obtain data lock.
29 Queue manager deleted, however there was a problem removing it from Active Directory.
33 An error occurred while deleting the directory structure for the queue manager.
49 Queue manager stopping
58 Inconsistent use of installations detected
62 The queue manager is associated with a different installation
69 Storage not available
71 Unexpected error
72 Queue manager name error
74 The WebSphere MQ service is not started.
100 Log location invalid.
112 Queue manager deleted. However, there was a problem processing the default queue manager definition in the product configuration file. The default queue manager specification might be incorrect.
119 Permission denied (Windows only).


Examples

  1. The following command deletes the queue manager saturn.queue.manager.

     dltmqm saturn.queue.manager
    
  2. The following command deletes the queue manager travel and also suppresses any messages caused by the command.

     dltmqm -z travel
    


Usage notes

In WebSphere MQ for Windows, it is an error to delete a queue manager when queue manager files are open. If you get this error, close the files and reissue the command.

Deleting a cluster queue manager does not remove it from the cluster. To check whether the queue manager you want to delete is part of a cluster, issue the command DIS CLUSQMGR(*). Then check whether this queue manager is listed in the output. If it is listed as a cluster queue manager you must remove the queue manager from the cluster before deleting it. See the related link for instructions.

If you do delete a cluster queue manager without first removing it from the cluster, the cluster continues to regard the deleted queue manager as a member of the cluster for at least 30 days. You can remove it from the cluster using the command RESET CLUSTER on a full repository queue manager. Re-creating a queue manager with an identical name and then trying to remove that queue manager from the cluster does not result in the cluster queue manager being removed from the cluster. This is because the newly created queue manager, although having the same name, does not have the same queue manager ID (QMID). Therefore it is treated as a different queue manager by the cluster.


Related commands

Command Description
crtmqm Create queue manager
strmqm Start queue manager
endmqm End queue manager


dmpmqaut

Dump a list of current authorizations for a range of WebSphere MQ object types and profiles.


Purpose

Use the dmpmqaut command to dump the current authorizations to a specified object.


Syntax

   
>>-dmpmqaut--+----------------+--+---------------+-------------->
             '- -m -- QMgrName-'  +- -n -- Profile-+   
                                 +- -l ----------+   
                                 '- -a ----------'   

>--+------------------+--+------------------------+------------->
   '- -t -- ObjectType-'  '- -s -- ServiceComponent-'   

>--+---------------------+--+------+---------------------------><
   +- -p -- PrincipalName-+  +- -e -+   
   '- -g -- GroupName-----'  '- -x -'   



Optional parameters

-m QMgrName
Dump authority records only for the queue manager specified. If you omit this parameter, only authority records for the default queue manager are dumped.
-n Profile
The name of the profile for which to dump authorizations. The profile name can be generic, using wildcard characters to specify a range of names as explained in Using OAM generic profiles on UNIX or Linux systems and Windows .
-l
Dump only the profile name and type. Use this option to generate a terse list of all defined profile names and types.
-a
Generate set authority commands.
-t ObjectType
The type of object for which to dump authorizations. Possible values are:

Value Description
authinfo An authentication information object, for use with Secure Sockets Layer (SSL) channel security
channel or chl A channel
clntconn or clcn A client connection channel
listener or lstr A listener
namelist or nl A namelist
process or prcs A process
queue or q A queue or queues matching the object name parameter
qmgr A queue manager
rqmname or rqmn A remote queue manager name
service or srvc A service
topic or top A topic

-s ServiceComponent
If installable authorization services are supported, specifies the name of the authorization service for which to dump authorizations. This parameter is optional; if you omit it, the authorization inquiry is made to the first installable component for the service.
-p PrincipalName
This parameter applies to WebSphere MQ for Windows only; UNIX systems keep only group authority records.

The name of a user for whom to dump authorizations to the specified object. The name of the principal can optionally include a domain name, specified in the following format:

 Userid@domain

For more information about including domain names on the name of a principal, see Principals and groups .

-g GroupName
The name of the user group for which to dump authorizations. You can specify only one name, which must be the name of an existing user group.

For WebSphere MQ for Windows only, the group name can optionally include a domain name, specified in the following formats:

 GroupName@domain
domain\GroupName
-e
Display all profiles used to calculate the cumulative authority that the entity has to the object specified in -n Profile. The variable Profile must not contain any wildcard characters.

The following parameters must also be specified:

  • -m QMgrName
  • -n Profile
  • -t ObjectType

and either -p PrincipalName, or -g GroupName.

-x
Display all profiles with the same name as specified in -n Profile. This option does not apply to the QMGR object, so a dump request of the form dmpmqaut -m QM -t QMGR ... -x is not valid.


Examples

The following examples show the use of dmpmqaut to dump authority records for generic profiles:

  1. This example dumps all authority records with a profile that matches queue a.b.c for principal user1.

     dmpmqaut -m qm1 -n a.b.c -t q -p user1
    
    The resulting dump would look something like this:

     profile:     a.b.*
    object type: queue entity:      user1
    type:        principal
    authority:   get, browse, put, inq
    

    Note: UNIX users cannot use the -p option; they must use -g groupname instead.

  2. This example dumps all authority records with a profile that matches queue a.b.c.

     dmpmqaut -m qmgr1 -n a.b.c -t q
    
    The resulting dump would look something like this:

     profile:     a.b.c
    object type: queue entity:      Administrator
    type:        principal
    authority:   all - - - - - - - - - - - - - - - - - 
    profile:     a.b.*
    object type: queue entity:      user1
    type:        principal
    authority:   get, browse, put, inq
    - - - - - - - - - - - - - - - - - 
    profile:     a.**
    object type: queue entity:      group1
    type:        group
    authority:   get 
    
  3. This example dumps all authority records for profile a.b.*, of type queue.

     dmpmqaut -m qmgr1 -n a.b.* -t q
    
    The resulting dump would look something like this:

     profile:     a.b.*
    object type: queue entity:      user1
    type:        principal
    authority:   get, browse, put, inq
    
  4. This example dumps all authority records for queue manager qmX.

     dmpmqaut -m qmX 
    
    The resulting dump would look something like this:

     profile:     q1
    object type: queue entity:      Administrator
    type:        principal
    authority:   all - - - - - - - - - - - - - - - - - 
    profile:     q*
    object type: queue entity:      user1
    type:        principal
    authority:   get, browse
    - - - - - - - - - - - - - - - - - 
    profile:     name.*
    object type: namelist
    entity:      user2
    type:        principal
    authority:   get - - - - - - - - - - - - - - - - - 
    profile:     pr1
    object type: process
    entity:      group1
    type:        group
    authority:   get 
  5. This example dumps all profile names and object types for queue manager qmX.

     dmpmqaut -m qmX -l 
    
    The resulting dump would look something like this:

     profile: q1, type: queue profile: q*, type: queue profile: name.*, type: namelist
    profile: pr1, type: process
    

Note:

  1. For WebSphere MQ for Windows only, all principals displayed include domain information, for example:

     profile:     a.b.*
    object type: queue entity:      user1@domain1
    type:        principal
    authority:   get, browse, put, inq
    
  2. Each class of object has authority records for each group or principal. These records have the profile name @CLASS and track the crt (create) authority common to all objects of that class. If the crt authority for any object of that class is changed then this record is updated. For example:

     profile:     @class
    object type: queue entity:      test
    entity type: principal
    authority:   crt
    
    This shows that members of the group test have crt authority to the class queue.
  3. For WebSphere MQ for Windows only, members of the Administrators group are by default given full authority. This authority, however, is given automatically by the OAM, and is not defined by the authority records. The dmpmqaut command displays authority defined only by the authority records. Unless an authority record has been explicitly defined, therefore, running the dmpmqaut command against the Administrators group displays no authority record for that group.


dmpmqcfg

Use the dmpmqcfg to dump the configuration of a WebSphere MQ queue manager.


Purpose

Use the dmpmqcfg command to dump the configuration of WebSphere MQ queue managers.

The dmpmqcfg utility dumps only subscriptions of type MQSUBTYPE_ADMIN, that is, only subscriptions that are created using the MQSC command DEFINE SUB or its PCF equivalent. The output from dmpmqcfg is a runmqsc command to enable the administration subscription to be re-created. Subscriptions that are created by applications using the MQSUB MQI call of type MQSUBTYPE_API are not part of the queue manager configuration, even if durable, and so are not dumped by dmpmqcfg.

   
>>-dmpmqcfg--+------+--+-----------------------------+---------->
             '-  -?-'  +-  -c-- DEFINE CHANNEL String-+   
                       '- -c-- default----------------'   

>--+------------------+--+------+--+----------------+----------->
   |      .-  all---. |  '-  -a-'  '- -s-- SeqNumber-'   
   '- -x--+---------+-'                                 
          +-object--+                                   
          +-authrec-+                                   
          +-chlauth-+                                   
          '-sub-----'                                   

>--+-----+--+---------------------+--+-------------------+------>
   '- -z-'  |      .- *---------. |  |      .- all-----. |   
            '- -n--+------------+-'  '- -t--+----------+-'   
                   '- ObjectName-'           +-authinfo-+     
                                            +-channel--+     
                                            +-clntconn-+     
                                            +-comminfo-+     
                                            +-lstr-----+     
                                            '-namelist-'     

>--+--------------------+--------------------------------------->
   |      .- mqsc-----. |   
   '- -o--+-----------+-'   
          +-1line-----+     
          +-setmqaut--+     
          '-grtmqmaut-'     

>--+--------------------------------------+--------------------->
   |      .-  SYSTEM.DEFAULT.MODEL.QUEUE-. |   
   '- -q--+-----------------------------+-'   
          '- ReplyQueueName--------------'     

>--+---------------+--+----------------+-----------------------><
   '-  -r-- RmtQMgr-'  '-  -m-- QMgrName-'   



Optional Parameters

-?
Inquire the usage message for dmpmqcfg.
-c
Force a client mode connection. If the -c parameter is qualified with the option default, the default client connection process is used. If -c is omitted, the default is to attempt to connect to the queue manager first by using server bindings and then if this fails by using client bindings.

If the option is qualified with an MQSC DEFINE CHANNEL CHLTYPE(CLNTCONN) string then this is parsed and if successful, used to create a temporary connection to the queue manager.

-x [ all | object | authrec | chlauth | sub ]
Filter the definition procedure to show object definitions, authority records, channel authentication records, or durable subscriptions . The default value all is that all types are returned.
-a
Return object definitions to show all attributes. The default is to return only attributes which differ from the defaults for the object type.
-sSeqNumber
Reset channel sequence number for sender, server and cluster sender channel types to the numeric value specified. The value SeqNumber must be in the range 1 - 999999999.
-z
Activate silent mode in which warnings, such as those which appear when inquiring attributes from a queue manager of a higher command level are suppressed.
-n [ * | ObjectName ]
Filter the definitions produced by object or profile name, the object/profile name may contain a single asterisk. The * option can be placed only at the end of the entered filter string.
-t
Choose a single type of object for which to export. Possible values are:

Value Dscription
all All object types
authinfo An authentication information object
channel or chl A channel (including MQTT channel type)
comminfo A communications information object
lstr or listener A listener
namelist or nl A namelist
process or prcs A process
queue or q A queue
qmgr A queue manager
srvc or service A service
topic or top A topic

-o[ mqsc | 1line | setmqaut | grtmqmaut ]
Possible values are:

Value Description
mqsc Multi-line MQSC that can be used as direct input to runmqsc
1line MQSC with all attributes on a single line for line diffing
setmqaut setmqaut statements for UNIX and Windows queue managers; valid only when -x authrec is specified
grtmqmaut Linux only; generates iSeries syntax for granting access to the objects.

-q
The name of the reply-to queue Used when getting configuration information.
-r
The name of the remote queue manager/transmit queue when using queued mode. If this parameter is omitted the configuration for the directly connected queue manager (specified with the -m parameter) is dumped.
-m
The name of the queue manager to connect to. If omitted the default queue manager name is used.


Authorizations

The user must have MQZAO_OUTPUT (+put) authority to access the command input queue (SYSTEM.ADMIN.COMMAND.QUEUE) and MQZAO_DISPLAY (+dsp) authority to access the default model queue (SYSTEM.DEFAULT.MODEL.QUEUE), to be able to create a temporary dynamic queue if using the default reply queue.

The user must also have MQZAO_CONNECT (+connect) and MQZAO_INQUIRE (+inq) authority for the queue manager, and MQZAO_DISPLAY (+dsp) authority for every object that is requested.


dmpmqlog

Display and format a portion of the WebSphere MQ system log.


Purpose

Use the dmpmqlog command to dump a formatted version of the WebSphere MQ system log to standard out.

The log to be dumped must have been created on the same type of operating system as that being used to issue the command.


Syntax

   
>>-dmpmqlog--+--------------------+--+--------------+----------->
             +- -b ---------------+  '- -e -- EndLSN-'   
             +- -s -- StartLSN-----+                     
             '- -n -- ExtentNumber-'                     

>--+-------------------+--+----------------+-------------------><
   '- -f -- LogFilePath-'  '- -m -- QMgrName-'   



Optional parameters

Dump start point
Use one of the following parameters to specify the log sequence number (LSN) at which the dump should start. If you omit this, dumping starts by default from the LSN of the first record in the active portion of the log.

-b
Start dumping from the base LSN. The base LSN identifies the start of the log extent that contains the start of the active portion of the log.
-s StartLSN
Start dumping from the specified LSN. The LSN is specified in the format nnnn:nnnn:nnnn:nnnn.

If you are using a circular log, the LSN value must be equal to or greater than the base LSN value of the log.

-n ExtentNumber
Start dumping from the specified extent number. The extent number must be in the range 0 - 9999999.

This parameter is valid only for queue managers using linear logging.

-e EndLSN
End dumping at the specified LSN. The LSN is specified in the format nnnn:nnnn:nnnn:nnnn.
-f LogFilePath
The absolute (rather than relative) directory path name to the log files. The specified directory must contain the log header file (amqhlctl.lfh) and a subdirectory called active. The active subdirectory must contain the log files. By default, log files are assumed to be in the directories specified in the WebSphere MQ configuration information. If you use this option, queue names associated with queue identifiers are shown in the dump only if you use the -m option to name a queue manager name that has the object catalog file in its directory path.

On a system that supports long file names this file is called qmqmobjcat and, to map the queue identifiers to queue names, it must be the file used when the log files were created. For example, for a queue manager named qm1, the object catalog file is located in the directory ..\qmgrs\qm1\qmanager\. To achieve this mapping, you might need to create a temporary queue manager, for example named tmpq, replace its object catalog with the one associated with the specific log files, and then start dmpmqlog, specifying -m tmpq and -f with the absolute directory path name to the log files.

-m QMgrName
The name of the queue manager. If you omit this parameter, the name of the default queue manager is used.

Note: Do not dump the log while the queue manager is running, and do not start the queue manager while dmpmqlog is running.


dspmq

Display information about queue managers.


Purpose

Use the dspmq command to display names and details of the queue managers on a system.


Syntax

   
                              .- -s ----------------------.   
>>-dspmq--+----------------+--+---------------------------+----->
          '- -m -- QMgrName-'  +- -o all ------------------+   
                              | .-----------------------. |   
                              | V                       | |   
                              '---+-------------------+-+-'   
                                  +- -o default ------+       
                                  +- -o installation -+       
                                  +- -o status -------+       
                                  '- -o standby ------'       

>--+-----+--+-----+--+-----+-----------------------------------><
   '- -x-'  '- -n-'  '- -a-'   



Required parameters

None


Optional parameters

-a
Displays information about the active queue managers only.

A queue manager is active if it is associated with the installation from which the dspmq command was issued and one or more of the following statements are true:

  • The queue manager is running
  • A listener for the queue manager is running
  • A process is connected to the queue manager

-m QMgrName
The queue manager for which to display details. If you give no name, all queue manager names are displayed.
-n
Suppresses translation of output strings.
-s
The operational status of the queue managers is displayed. This parameter is the default status setting.

The parameter -o status is equivalent to -s.

-o all
The operational status of the queue managers is displayed, and whether any are the default queue manager.

On Windows, UNIX and Linux, the installation name (INSTNAME), installation path (INSTPATH), and installation version (INSTVER) of the installation that the queue manager is associated with is also displayed.

-o default
Displays whether any of the queue managers are the default queue manager.
-o installation
Windows, UNIX and Linux only.

Displays the installation name (INSTNAME), installation path (INSTPATH), and installation version (INSTVER) of the installation that the queue manager is associated with.

-o status
The operational status of the queue managers is displayed.
-o standby
Displays whether a queue manager currently permits starting a standby instance. The possible values are shown in Table 1 .

Standby values

Value Description
Permitted The queue manager is running and is permitting standby instances.
Not permitted The queue manager is running and is not permitting standby instances.
Not applicable The queue manager is not running. You can start the queue manager and this instance becomes active if it starts successfully.

-x
Information about queue manager instances are displayed. The possible values are shown in Table 2 .

Instance values

Value Description
Active The instance is the active instance.
Standby The instance is a standby instance.


Queue Manager States

The following is a list of the different states a queue manager can be in:


Return codes

Return code Description
0 Command completed normally
36 Invalid arguments supplied
58 Inconsistent use of installations detected
71 Unexpected error
72 Queue manager name error


Examples

  1. The following command displays queue managers on this server:

     dspmq -o all 
    
  2. The following command displays standby information for queue managers on this server that have ended immediately:

     dspmq -o standby 
    
  3. The following command displays standby information and instance information for queue managers on this server:

     dspmq -o standby -x
    


dspmqaut

dspmqaut displays the authorizations of a specific WebSphere MQ object.


Purpose

Use the dspmqaut command to display the current authorizations to a specified object.

If a user ID is a member of more than one group, this command displays the combined authorizations of all the groups.

Only one group or principal can be specified.

For more information about authorization service components, see Installable services , Service components , and Authorization service interface .


Syntax

   
>>-dspmqaut--+----------------+-- -n -- Profile------------------>
             '- -m -- QMgrName-'                  

>-- -t -- ObjectType--+- -g -- GroupName-----+-------------------->
                     '- -p -- PrincipalName-'   

>--+------------------------+----------------------------------><
   '- -s -- ServiceComponent-'   



Required parameters

-n Profile
The name of the profile for which to display authorizations. The authorizations apply to all WebSphere MQ objects with names that match the profile name specified. The profile name can be generic, using wildcard characters to specify a range of names as explained in Using OAM generic profiles on UNIX or Linux systems and Windows .

This parameter is required, unless you are displaying the authorizations of a queue manager. In this case you must not include it and instead specify the queue manager name using the -m parameter.

-t ObjectType
The type of object on which to make the inquiry. Possible values are:

Object Types

Object Type Command Object Description
authinfo An authentication information object, for use with Secure Sockets Layer (SSL) channel security
channel or chl A channel
clntconn or clcn A client connection channel
listener or lstr A Listener
namelist or nl A namelist
process or prcs A process
queue or q A queue or queues matching the object name parameter
rqmname or rqmn A remote queue manager name
service or srvc A service
topic or top A topic


Optional parameters

-m QMgrName
The name of the queue manager on which to make the inquiry. This parameter is optional if you are displaying the authorizations of your default queue manager.
-g GroupName
The name of the user group on which to make the inquiry. You can specify only one name, which must be the name of an existing user group.

For WebSphere MQ for Windows only, the group name can optionally include a domain name, specified in the following formats:

 GroupName@domain
domain\GroupName
-p PrincipalName
The name of a user for whom to display authorizations to the specified object.

For WebSphere MQ for Windows only, the name of the principal can optionally include a domain name, specified in the following format:

 Userid@domain
For more information about including domain names on the name of a principal, see Principals and groups .
-s ServiceComponent
If installable authorization services are supported, specifies the name of the authorization service to which the authorizations apply. This parameter is optional; if you omit it, the authorization inquiry is made to the first installable component for the service.


Returned parameters

Returns an authorization list, which can contain none, one, or more authorization values. Each authorization value returned means that any user ID in the specified group or principal has the authority to perform the operation defined by that value. the authorities that can be given to the different object types.

Specifying authorities for different object types

Authority Queue Process Queue manager Remote queue manager name Namelist Topic Auth info Clntconn Channel Listener Service
all Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
alladm Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes
allmqi Yes Yes Yes Yes Yes Yes Yes No No No No
none Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
altusr No No Yes No No No No No No No No
browse Yes No No No No No No No No No No
chg Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes
clr Yes No No No No Yes No No No No No
connect No No Yes No No No No No No No No
crt Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes
ctrl No No No No No Yes No No Yes Yes Yes
ctrlx No No No No No No No No Yes No No
dlt Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes
dsp Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes
get Yes No No No No No No No No No No
pub No No No No No Yes No No No No No
put Yes No No Yes No Yes No No No No No
inq Yes Yes Yes No Yes No Yes No No No No
passall Yes No No No No Yes No No No No No
passid Yes No No No No Yes No No No No No
resume No No No No No Yes No No No No No
set Yes Yes Yes No No No No No No No No
setall Yes No Yes No No Yes No No No No No
setid Yes No Yes No No Yes No No No No No
sub No No No No No Yes No No No No No
system No No Yes No No No No No No No No

The following list defines the authorizations associated with each value:

authorization commands and the second column shows their description.">

Authorizations associated with values.

Authorization Commands Description
all Use all operations relevant to the object. all authority is equivalent to the union of the authorities alladm, allmqi, and system appropriate to the object type.
alladm Perform all administration operations relevant to the object
allmqi Use all MQI calls relevant to the object
altusr Specify an alternative user ID on an MQI call
browse Retrieve a message from a queue by issuing an MQGET call with the BROWSE option
chg Change the attributes of the specified object, using the appropriate command set
clr Clear a queue (PCF command Clear queue only) or a topic
ctrl Start, and stop the specified channel, listener, or service, and ping the specified channel.
ctrlx Reset or resolve the specified channel
connect Connect the application to the specified queue manager by issuing an MQCONN call
crt Create objects of the specified type using the appropriate command set
dlt Delete the specified object using the appropriate command set
dsp Display the attributes of the specified object using the appropriate command set
get Retrieve a message from a queue by issuing an MQGET call
inq Make an inquiry on a specific queue by issuing an MQINQ call
passall Pass all context
passid Pass the identity context
pub Publish a message on a topic using the MQPUT call.
put Put a message on a specific queue by issuing an MQPUT call
resume Resume a subscription using the MQSUB call.
set Set attributes on a queue from the MQI by issuing an MQSET call
setall Set all context
setid Set the identity context
sub Create, alter, or resume a subscription to a topic using the MQSUB call.
system Use queue manager for internal system operations

The authorizations for administration operations, where supported, apply to these command sets:


Return codes

Return code Description
0 Successful operation
26 Queue manager running as a standby instance.
36 Invalid arguments supplied
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
69 Storage not available
71 Unexpected error
72 Queue manager name error
133 Unknown object name
145 Unexpected object name
146 Object name missing
147 Object type missing
148 Invalid object type
149 Entity name missing


Examples


dspmqcsv

The status of a command server is displayed


Purpose

Use the dspmqcsv command to display the status of the command server for the specified queue manager.

The status can be one of the following:

You must use the dspmqcsv command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.


Syntax

   
>>-dspmqcsv--+----------+--------------------------------------><
             '- QMgrName-'   



Required parameters

None


Optional parameters

QMgrName
The name of the local queue manager for which the command server status is being requested.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing


Examples

The following command displays the status of the command server associated with venus.q.mgr:

 dspmqcsv venus.q.mgr


Related commands

Command Description
strmqcsv Start a command server
endmqcsv End a command server


dspmqfls

Display the file names corresponding to WebSphere MQ objects.


Purpose

Use the dspmqfls command to display the real file system name for all WebSphere MQ objects that match a specified criterion. You can use this command to identify the files associated with a particular object. This command is useful for backing up specific objects. See Understanding WebSphere MQ file names for information about name transformation.


Syntax

   
>>-dspmqfls--+----------------+--+---------------+-------------->
             '- -m -- QMgrName-'  '- -t -- ObjType-'   

>-- GenericObjName----------------------------------------------><



Required parameters

GenericObjName
The name of the object. The name is a string with no flag and is a required parameter. Omitting the name returns an error.

This parameter supports an asterisk (*) as a wildcard at the end of the string.


Optional parameters

-m QMgrName
The name of the queue manager for which to examine files. If you omit this name, the command operates on the default queue manager.
-t ObjType
The object type. The following list shows the valid object types. The abbreviated name is shown first followed by the full name.

Valid object types

Object Type Description
* or all All object types; this parameter is the default
authinfo Authentication information object, for use with Secure Sockets Layer (SSL) channel security
channel or chl A channel
clntconn or clcn A client connection channel
catalog or ctlg An object catalog
namelist or nl A namelist
listener or lstr A listener
process or prcs A process
queue or q A queue or queues matching the object name parameter
qalias or qa An alias queue
qlocal or ql A local queue
qmodel or qm A model queue
qremote or qr A remote queue
qmgr A queue manager object
service or srvc A service

Note:

  1. The dspmqfls command displays the name of the directory containing the queue, not the name of the queue itself.
  2. In WebSphere MQ for UNIX systems, you must prevent the shell from interpreting the meaning of special characters, for example, an asterisk (*). The way you do this depends on the shell you are using. It may involve the use of single quotation marks, double quotation marks, or a backslash.


Return codes

Return code Description
0 Command completed normally
10 Command completed but not entirely as expected
20 An error occurred during processing


Examples

  1. The following command displays the details of all objects with names beginning SYSTEM.ADMIN defined on the default queue manager.

     dspmqfls SYSTEM.ADMIN*
    
  2. The following command displays file details for all processes with names beginning PROC defined on queue manager RADIUS.

     dspmqfls -m RADIUS -t prcs PROC*
    


dspmqinf

Display WebSphere MQ configuration information (Windows and UNIX platforms only).


Purpose

Use the dspmqinf command to display WebSphere MQ configuration information.


Syntax

   
             .- -s -QueueManager-.  .- -o -stanza--.               
>>-dspmqinf -+-------------------+--+--------------+-- StanzaName-><
             '- -s - StanzaType---'  '- -o -command-'               



Required parameters

StanzaName
The name of the stanza. That is, the value of the key attribute that distinguishes between multiple stanzas of the same type.


Optional parameters

-s StanzaType
The type of stanza to display. If omitted, the QueueManager stanza is displayed.
The only supported value of StanzaType is QueueManager.
-o stanza
Displays the configuration information in stanza format as it is shown in the .ini files. This format is the default output format.
Use this format to display stanza information in a format that is easy to read.
-o command
Displays the configuration information as an addmqinf command.
Information about the installation associated with the queue manager is not displayed using this parameter. The addmqinf command does not require information about the installation.
Use this format to paste into a command shell.


Return codes

Return code Description
0 Successful operation
39 Bad command-line parameters
44 Stanza does not exist
58 Inconsistent use of installations detected
69 Storage not available
71 Unexpected error
72 Queue manager name error


Examples

 dspmqinf QM.NAME
The command defaults to searching for a QueueManager stanza named QM.NAME and displays it in stanza format.

 QueueManager:
   Name=QM.NAME
   Prefix=/var/mqm
   Directory=QM!NAME
   DataPath=/MQHA/qmgrs/QM!NAME
   InstallationName=Installation1
The following command gives the same result:

 dspmqinf -s QueueManager -o stanza QM.NAME
The next example displays the output in addmqinf format.

 dspmqinf -o command QM.NAME
The output is on one line:

 addmqinf -s QueueManager -v Name=QM.NAME -v Prefix=/var/mqm -v Directory=QM!NAME
         -v DataPath=/MQHA/qmgrs/QM!NAME 


Usage notes

Use dspmqinf with addmqinf to create an instance of a multi-instance queue manager on a different server.

To use this command you must be a WebSphere MQ administrator and a member of the mqm group.


Related commands

Command Description
addmqinf Add queue manager configuration information
rmvmqinf Remove queue manager configuration information


dspmqinst

Display installation entries from mqinst.ini on UNIX, Linux, and Windows.


Purpose

File mqinst.ini contains information about all WebSphere MQ installations on a system. For more information about mqinst.ini, see Installation configuration file, mqinst.ini .


Syntax

   
>>-dspmqinst----+- -p - InstallationPath----------------------------+---><
                +- -n - InstallationName----------------------------+     
                |                                              (1) |     
                +- -p - InstallationPath-- -n - InstallationName-----+     
                |                                              (1) |     
                '- -n - InstallationName-- -p - InstallationPath-----'     


Notes:

  1. When specified together, the installation name and installation path must refer to the same installation.


Parameters

-n InstallationName
The name of the installation.
-p InstallationPath
The installation path.
?
Display usage information.


Return codes

Return code Description
0 Entry displayed without error
36 Invalid arguments supplied
44 Entry does not exist
59 Invalid installation specified
71 Unexpected error
89 .ini file error
96 Could not lock .ini file
131 Resource problem


Examples

  1. Display details of all WebSphere MQ installations on the system:

     dspmqinst
    
  2. Query the entry for the installation named Installation3:

     dspmqinst -n Installation3
    
  3. Query the entry with an installation path of /opt/mqm:

     dspmqinst  -p /opt/mqm
    
  4. Query the entry for the installation named Installation3. Its expected installation path is /opt/mqm:

     dspmqinst -n Installation3 -p /opt/mqm
    


dspmqrte

Determine the route that a message has taken through a queue manager network.


Purpose

The WebSphere MQ display route application (dspmqrte) can be executed on all platforms except z/OS. You can execute the WebSphere MQ display route application as a client to a WebSphere MQ for z/OS queue manager by specifying the -c parameter when issuing the dspmqrte command.

Note: To run a client application against a queue manager, the Client Attachment feature must be installed.

The WebSphere MQ display route application generates and puts a trace-route message into a queue manager network. As the trace-route message travels through the queue manager network, activity information is recorded. When the trace-route message reaches its target queue, the activity information is collected by the WebSphere MQ display route application and displayed. For more information, and examples of using the WebSphere MQ display route application, see WebSphere MQ display route application .


Syntax

   
>>-dspmqrte--+------+------------------------------------------->
             '- -c -'   

   .-| Generation options |--------------.                      
>--+-------------------------------------+-- -q -- TargetQName--->
   '- -i -- CorrelId--| Display options |-'                      

>--+----------------+------------------------------------------><
   '- -m -- QMgrName-'   

Generation options

|--+------------------+--+---------------+--+---------------+--->
   '- -ac --+-------+-'  '- -d -- Deliver-'  '- -f -- Forward-'   
            '- -ar -'                                           

>--+-----------------------+--+------+--+----------------+------>
   |                   (1) |  '- -o -'  '- -p -- Priority-'   
   '- -l -- Persistence-----'                                 

>--+-----------------------+--+-----------------------------+--->
   '- -qm -- TargetQMgrName-'  '- -ro --+- none -----------+-'   
                                       | .-,------------. |     
                                       | V              | |     
                                       '--- ReportOption-+-'     

>--+------------------------------------------+----------------->
   '- -rq -- ReplyToQ--+---------------------+-'   
                      '- -rqm -- ReplyToQMgr-'     

>--+------------------+--+--------------+----------------------->
   '- -s -- Activities-'  '- -t -- Detail-'   

>--+--------------------+--+-------------------+---------------->
   '- -ts -- TopicString-'  '- -xp -- PassExpiry-'   

                      .-| Display options |-.   
>--+---------------+--+---------------------+-------------------|
   '- -xs -- Expiry-'  |        (2)          |   
                      '--- -n --------------'   

Display options

             .- -v  summary --------------------------------.   
|--+------+--+----------------------------------------------+--->
   '- -b -'  '- -v --+- all ------------------------------+-'   
                     +- none -----------------------------+     
                     '- outline --+---------------------+-'     
                                  | .-,---------------. |       
                                  | V                 | |       
                                  '---  DisplayOption -+-'       

>--+----------------+-------------------------------------------|
   '- -w -- WaitTime-'   


Notes:

  1. If Persistence is specified as yes, and is accompanied by a request for a trace-route reply message (-ar), or any report generating options (-ro ReportOption), then you must specify the parameter -rq ReplyToQ. The reply-to queue must not resolve to a temporary dynamic queue.
  2. If this parameter is accompanied by a request for a trace-route reply message (-ar), or any of the report generating options (-ro ReportOption), then a specific (non-model) reply-to queue must be specified using -rq ReplyToQ. By default, activity report messages are requested.


Required parameters

-q TargetQName
If the WebSphere MQ display route application is being used to send a trace-route message into a queue manager network, TargetQName specifies the name of the target queue.

If the WebSphere MQ display route application is being used to view previously gathered activity information, TargetQName specifies the name of the queue where the activity information is stored.


Optional parameters

-c
Specifies that the WebSphere MQ display route application connects as a client application. For more information about how to set up client machines, see Installing a WebSphere MQ client .

This parameter can be used only if the client component is installed.

-i CorrelId
This parameter is used when the WebSphere MQ display route application is used to display previously accumulated activity information only. There can be many activity reports and trace-route reply messages on the queue specified by -q TargetQName. CorrelId is used to identify the activity reports, or a trace-route reply message, related to a trace-route message. Specify the message identifier of the original trace-route message in CorrelId.

The format of CorrelId is a 48 character hexadecimal string.

-m QMgrName
The name of the queue manager to which the WebSphere MQ display route application connects. The name can contain up to 48 characters.

If you do not specify this parameter, the default queue manager is used.

Generation options
The following parameters are used when the WebSphere MQ display route application is used to put a trace-route message into a queue manager network.
-ac
Specifies that activity information is to be accumulated within the trace-route message.

If you do not specify this parameter, activity information is not accumulated within the trace-route message.

-ar
Requests that a trace-route reply message containing all accumulated activity information is generated in the following circumstances:

  • The trace-route message is discarded by a WebSphere MQ Version 7.0 queue manager.
  • The trace-route message is put to a local queue (target queue or dead-letter queue) by a WebSphere MQ Version 7.0 queue manager.
  • The number of activities performed on the trace-route message exceeds the value of specified in -s Activities.

For more information about trace-route reply messages, see Trace-route reply message reference .

If you do not specify this parameter, a trace-route reply message is not requested.

-d Deliver
Specifies whether the trace-route message is to be delivered to the target queue on arrival. Possible values for Deliver are:

If you do not specify this parameter, the trace-route message is not put to the target queue.

-f Forward
Specifies the type of queue manager that the trace-route message can be forwarded to. Queue managers use an algorithm when determining whether to forward a message to a remote queue manager. For details of this algorithm, see The cluster workload management algorithm . The possible values for Forward are:

If you do not specify this parameter, the trace-route message is only forwarded to a queue manager that honors the Deliver parameter.

-l Persistence
Specifies the persistence of the generated trace-route message. Possible values for Persistence are:

A trace-route reply message, or any report messages, returned shares the same persistence value as the original trace-route message.

If Persistence is specified as yes , you must specify the parameter -rq ReplyToQ. The reply-to queue must not resolve to a temporary dynamic queue.

If you do not specify this parameter, the generated trace-route message is not persistent.

-o
Specifies that the target queue is not bound to a specific destination. Typically this parameter is used when the trace-route message is to be put across a cluster. The target queue is opened with option MQOO_BIND_NOT_FIXED.

If you do not specify this parameter, the target queue is bound to a specific destination.

-p Priority
Specifies the priority of the trace-route message. The value of Priority is either greater than or equal to 0, or MQPRI_PRIORITY_AS_Q_DEF. MQPRI_PRIORITY_AS_Q_DEF specifies that the priority value is taken from the queue specified by -q TargetQName.

If you do not specify this parameter, the priority value is taken from the queue specified by -q TargetQName.

-qm TargetQMgrName
Qualifies the target queue name; normal queue manager name resolution applies. The target queue is specified with -q TargetQName.

If you do not specify this parameter, the queue manager to which the WebSphere MQ display route application is connected is used as the reply-to queue manager.

-ro none | ReportOption

If -ro ReportOption or -ro none are not specified, then the MQRO_ACTIVITY and MQRO_DISCARD_MSG report options are specified.

-rq ReplyToQ
Specifies the name of the reply-to queue that all responses to the trace-route message are sent to. If the trace-route message is persistent, or if the -n parameter is specified, a reply-to queue must be specified that is not a temporary dynamic queue.

If you do not specify this parameter, the system default model queue, SYSTEM.DEFAULT.MODEL.QUEUE is used as the reply-to queue. Using this model queue causes a temporary dynamic queue, for the WebSphere MQ display route application, to be created.

-rqm ReplyToQMgr
Specifies the name of the queue manager where the reply-to queue is located. The name can contain up to 48 characters.

If you do not specify this parameter, the queue manager to which the WebSphere MQ display route application is connected is used as the reply-to queue manager.

-s Activities
Specifies the maximum number of recorded activities that can be performed on behalf of the trace-route message before it is discarded. This parameter prevents the trace-route message from being forwarded indefinitely if caught in an infinite loop. The value of Activities is either greater than or equal to 1, or MQROUTE_UNLIMITED_ACTIVITIES. MQROUTE_UNLIMITED_ACTIVITIES specifies that an unlimited number of activities can be performed on behalf of the trace-route message.

If you do not specify this parameter, an unlimited number of activities can be performed on behalf of the trace-route message.

-t Detail
Specifies the activities that are recorded. The possible values for Detail are:

If you do not specify this parameter, medium level activities are recorded.

-ts TopicString
Specifies a topic string to which the WebSphere MQ display route application is to publish a trace-route message, and puts this application into topic mode. In this mode, the application traces all of the messages that result from the publish request.
-xp PassExpiry
Specifies whether the report option MQRO_DISCARD_MSG and the remaining expiry time from the trace-route message is passed on to the trace-route reply message. Possible values for PassExpiry are:

If you do not specify this parameter, the MQRO_PASS_DISCARD_AND_EXPIRY report option is not specified in the trace-route message.

-xs Expiry
Specifies the expiry time for the trace-route message, in seconds.

If you do not specify this parameter, the expiry time is specified as 60 seconds.

-n
Specifies that activity information returned for the trace-route message is not to be displayed.

If this parameter is accompanied by a request for a trace-route reply message (-ar), or any of the report generating options from (-ro ReportOption), then a specific (non-model) reply-to queue must be specified using -rq ReplyToQ. By default, activity report messages are requested.

After the trace-route message is put to the specified target queue, a 48 character hexadecimal string is returned containing the message identifier of the trace-route message. The message identifier can be used by the WebSphere MQ display route application to display the activity information for the trace-route message at a later time. This can be done using the -i CorrelId parameter.

If you do not specify this parameter, activity information returned for the trace-route message is displayed in the form specified by the -v parameter.

Display options
The following parameters are used when the WebSphere MQ display route application is used to display collected activity information.
-b
Specifies that the WebSphere MQ display route application only browses activity reports or a trace-route reply message related to a message. This parameter allows activity information to be displayed again at a later time.

If you do not specify this parameter, the WebSphere MQ display route application gets activity reports and deletes them, or a trace-route reply message related to a message.

-v summary | all | none | outline DisplayOption

If you do not specify this parameter, a summary of the message route is displayed.

-w WaitTime
Specifies the time, in seconds, that the WebSphere MQ display route application waits for activity reports, or a trace-route reply message, to return to the specified reply-to queue.

If you do not specify this parameter, the wait time is specified as the expiry time of the trace-route message, plus 60 seconds.


Return codes

Return code Description
0 Command completed normally
10 Invalid arguments supplied
20 An error occurred during processing


Examples

  1. The following command puts a trace-route message into a queue manager network with the target queue specified as TARGET.Q. Providing queue managers on route are enabled for activity recording, activity reports are generated. Depending on the queue manager attribute, ACTIVREC, activity reports are either delivered to the reply-to queue ACT.REPORT.REPLY.Q, or are delivered to a system queue. The trace-route message is discarded on arrival at the target queue.

     dspmqrte -q TARGET.Q -rq ACT.REPORT.REPLY.Q
    
    Providing one or more activity reports are delivered to the reply-to queue, ACT.REPORT.REPLY.Q, the WebSphere MQ display route application orders and displays the activity information.
  2. The following command puts a trace-route message into a queue manager network with the target queue specified as TARGET.Q. Activity information is accumulated within the trace-route message, but activity reports are not generated. On arrival at the target queue, the trace-route message is discarded. Depending on the value of the target queue manager attribute, ROUTEREC, a trace-route reply message can be generated and delivered to either the reply-to queue, TRR.REPLY.TO.Q, or to a system queue.

     dspmqrte -ac -ar -ro discard -rq TRR.REPLY.TO.Q -q TARGET.Q
    
    Providing a trace-route reply message is generated, and delivered to the reply-to queue TRR.REPLY.TO.Q, the WebSphere MQ display route application orders and displays the activity information that was accumulated in the trace-route message.

For more examples of using the WebSphere MQ display route application and its output, see WebSphere MQ display route application examples .


dspmqspl

Use the dspmqspl command to display a list of all policies and details of a named policy.


Syntax

   
>>-dspmqspl-- -m - QMgrName--+-----------------+--+----------+--><
                            '- -p - PolicyName-'  '- -export-'   


dspmqspl command flags.

Command flag Explanation
-m Queue manager name ( mandatory ).
-p Policy name.
-export Adding this flag generates output which can easily applied to a different queue manager.


dspmqtrc

Format and display WebSphere MQ trace.


Purpose

The dspmqtrc command is supported on UNIX and HP Integrity NonStop Server systems only. Use the dspmqtrc command to display WebSphere MQ formatted trace output.

The runtime SSL trace files have the names AMQ.SSL.TRC and AMQ.SSL.TRC.1. You cannot format any of the SSL trace files. The SSL trace files are binary files and, if they are transferred to IBM support by FTP, they must be transferred in binary transfer mode.


Syntax

   
>>-dspmqtrc--+----------------------+--+-----+--+-----+--------->
             '- -t -- FormatTemplate-'  '- -h-'  '- -s-'   

>--+----------------------+-- InputFileName---------------------><
   '- -o -- OutputFilename-'                  



Required parameters

InputFileName
The name of the file containing the unformatted trace, for example:

 /var/mqm/trace/AMQ12345.01.TRC
If you provide one input file, dspmqtrc formats it either to stdout or to the output file you name. If you provide more than one input file, any output file you name is ignored, and formatted files are named AMQyyyyy.zz.FMT, based on the PID of the trace file.


Optional parameters

-t FormatTemplate
The name of the template file containing details of how to display the trace. If this parameter is not supplied, the default template file location is used:

For AIX systems, the default value is as follows:

 MQ_INSTALLATION_PATH/lib/amqtrc2.fmt
For all HP Integrity NonStop Server, and UNIX systems other than AIX systems, the default value is as follows:

 MQ_INSTALLATION_PATH/lib/amqtrc.fmt
MQ_INSTALLATION_PATH represents the high-level directory in which WebSphere MQ is installed.
-h
Omit header information from the report.
-s
Extract trace header and put to stdout.
-o output_filename
The name of the file into which to write formatted data.


Related commands

Command Description
endmqtrc End trace
strmqtrc Start trace


dspmqtrn

Display in-doubt and heuristically completed transactions.


Purpose

Use the dspmqtrn command to display details of transactions. This command includes transactions coordinated by WebSphere MQ and by an external transaction manager.


Syntax

   
>>-dspmqtrn--+-----+--+-----+--+-----+--+-----+--+-----+-------->
             '-  -e-'  '-  -h-'  '-  -i-'  '-  -a-'  '-  -q-'   

>--+--------------+--------------------------------------------><
   '-  -m QMgrName-'   



Optional parameters

-e
Requests details of externally coordinated, in-doubt transactions. Such transactions are those for which WebSphere MQ has been asked to prepare to commit, but has not yet been informed of the transaction outcome.
-h
Requests details of externally coordinated transactions that were resolved by the rsvmqtrn command, and the external transaction coordinator has yet to acknowledge with an xa-forget command. This transaction state is termed heuristically completed by X/Open.

Note: If you do not specify -e, -h, or -i, details of both internally and externally coordinated in-doubt transactions are displayed, but details of externally coordinated, heuristically completed transactions are not displayed.

-i
Requests details of internally coordinated, in-doubt transactions. Such transactions are those for which each resource manager has been asked to prepare to commit, but WebSphere MQ has yet to inform the resource managers of the transaction outcome.

Information about the state of the transaction in each of its participating resource managers is displayed. This information can help you assess the affects of failure in a particular resource manager.

Note: If you do not specify -e or -i, details of both internally and externally coordinated in-doubt transactions are displayed.

-a
Requests a list of all transactions known to the queue manager . The returned data includes transaction details for all transactions known to the queue manager. If a transaction is currently associated with a WebSphere MQ application connection, information related to that WebSphere MQ application connection is also returned. The data returned by this command might typically be correlated with the output of a runmqsc DISPLAY CONN command, and the output fields have the same meaning as in that command.
Not all of the fields are appropriate for all transactions. When the fields are not meaningful, they are displayed as blank. For example: The UOWLOG value when the command is issued against a circular logging queue manager.
-q
Specifying this parameter on its own is the same as specifying -a -q.
Displays all the data from the -a parameter and a list of up to 100 unique objects updated within the transaction. If more than 100 objects are updated in the same transaction, only the first 100 distinct objects are listed for each transaction.
-mQMgrName
The name of the queue manager for which to display transactions. If you omit the name, the transaction of the default queue manager are displayed.


Return codes

Return code Description
0 Successful operation
26 Queue manager running as a standby instance.
36 Invalid arguments supplied
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
69 Storage not available
71 Unexpected error
72 Queue manager name error
102 No transactions found


Related commands

Command Description
rsvmqtrn Resolve transaction


dspmqver

Display WebSphere MQ version and build information.


Purpose

Use the dspmqver command to display WebSphere MQ version and build information.

By default, the dspmqver command displays details of the installation from which it was invoked. A note is displayed if other installations exist; use the -i parameter to display their details.


Syntax

   
>>-dspmqver----------------------------------------------------->

>--+-+------+--+------------------+--+--------------+--+-----+--+-----+-+-><
   | '- -a -'  '- -p -- components-'  '- -f -- fields-'  '- -b-'  '- -v-' |   
   '- -i----------------------------------------------------------------'   



Optional parameters

-a
Display information about all fields and components.
-p Components
Display information for the components specified by component. Either a single component or multiple components can be specified. Enter either the value of a single component or the sum of the values of all the required components. Available components and related values follow:

-f Fields
Display information for the fields specified by field. Specify either a single field or multiple fields. Enter either the value of a single field or the sum of the values of all the required fields. Available fields and related values follow:

Information for each selected field is displayed on a separate line when the dspmqver command is run.

The default value is 8191. This displays information for all fields.

-b
Omit header information from the report.
-v
Display verbose output.
-i
Display information about all installations. You cannot use this option with other options. The installation from which the dspmqver command was issued is displayed first. For any other installations, only the following fields are displayed: Name, Version, Installation name, Installation description, Installation path, and Primary installation. Not applicable to HP Integrity NonStop Server.


Return codes

Return code Description
0 Command completed normally.
10 Command completed with unexpected results.
20 An error occurred during processing.


Examples

The following command displays WebSphere MQ version and build information, using the default settings for -p and -f :

 dspmqver

The following command displays information about all fields and components and is the equivalent of specifying dspmqver -p 63 -f 4095:

 dspmqver -a

The following command displays version and build information for the WebSphere MQ classes for Java:

 dspmqver -p 2

The following command displays the Common Services for Java Platform Standard Edition, IBM WebSphere MQ, Java Message Service Client, and WebSphere MQ classes for Java Message Service:

 dspmqver -p 4

The following command displays the build level of the WebScale Distribution Hub:

 dspmqver -p 8 -f 4

The following command displays the name and build type for IBM WebSphere MQ custom channel for Windows Communication Foundation:

 dspmqver -p 16 -f 9

The following command displays information about installations of WebSphere MQ.

 dspmqver -i


Command Failure

The dspmqver command can fail if you try to view version or build information for the WebSphere MQ classes for Java, and you have not correctly configured your environment. For example, you might see the following message:

 [root@blade883 ~]# dspmqver -p2
AMQ8351: WebSphere MQ Java environment has not been configured correctly.
To resolve this problem, ensure that the path is configured to include the JRE, and that the correct environment variables are set; for example, by using setjmsenv or setjmsenv64. For example:

 export PATH=$PATH:/opt/mqm/java/jre/bin
cd /opt/mqm/java/bin/
. ./setjmsenv64

[root@blade883 bin]# dspmqver -p2
Name:       WebSphere MQ classes for Java
Version:    7.1.0.0
Level:      k000-L110908
Build Type: Production


endmqcsv

Stop the command server for a queue manager.


Purpose

Use the endmqscv command to stop the command server on the specified queue manager.

You must use the endmqscv command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

If the queue manager attribute, SCMDSERV, is specified as QMGR then changing the state of the command server using endmqscv does not effect how the queue manager acts upon the SCMDSERV attribute at the next restart.


Syntax

   
             .- -c -.             
>>-endmqcsv--+------+-- QMgrName--------------------------------><
             '- -i -'             



Required parameters

QMgrName
The name of the queue manager for which to end the command server.


Optional parameters

-c
Stops the command server in a controlled manner. The command server can complete the processing of any command message that it has already started. No new message is read from the command queue.

This parameter is the default.

-i
Stops the command server immediately. Actions associated with a command message currently being processed might not complete.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing


Examples

  1. The following command stops the command server on queue manager saturn.queue.manager:

     endmqcsv  -c saturn.queue.manager
    

    The command server can complete processing any command it has already started before it stops. Any new commands received remain unprocessed in the command queue until the command server is restarted.

  2. The following command stops the command server on queue manager pluto immediately:

     endmqcsv -i pluto
    


Related commands

Command Description
strmqcsv Start a command server
dspmqcsv Display the status of a command server


endmqlsr

End all listener process for a queue manager.


Purpose

The endmqlsr command ends all listener processes for the specified queue manager.

You must use the endmqlsr command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

You do not have to stop the queue manager before issuing the endmqlsr command. If any of the listeners are configured to have inbound channels running within the runmqlsr listener process, rather than within a pool process, the request to end that listener might fail if channels are still active. In this case a message is written indicating how many listeners were successfully ended and how many listeners are still running.

If the listener attribute, CONTROL, is specified as QMGR then changing the state of the listener using endmqlsr does not effect how the queue manager acts upon the CONTROL attribute at the next restart.


Syntax

   
>>-endmqlsr--+------+--+----------------+----------------------><
             '- -w -'  '- -m -- QMgrName-'   



Optional parameters

-m QMgrName
The name of the queue manager. If you omit this parameter, the command operates on the default queue manager.
-w
Wait before returning control.

Control is returned to you only after all listeners for the specified queue manager have stopped.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing


endmqdnm

Stop the .NET monitor for a queue (Windows only).


Purpose

Note: The endmqdnm command applies to WebSphere MQ for Windows only.

Use the endmqdnm control command to stop a .NET monitor.


Syntax

   
>>-endmqdnm-- -q -- QueueName--+----------------+---------------><
                              '- -m -- QMgrName-'   



Required parameters

-q QueueName
The name of the application queue that the .NET monitor is monitoring.


Optional parameters

-m QMgrName
The name of the queue manager that hosts the application queue.

If omitted, the default queue manager is used.


Return codes

Return code Description
0 Successful operation
36 Invalid arguments supplied
40 Queue manager not available
58 Inconsistent use of installations detected
71 Unexpected error
72 Queue manager name error
133 Unknown object name error


endmqm

Stop a queue manager or switch to a standby queue manager.


Purpose

Use the endmqm command to end (stop) a specified queue manager. This command stops a queue manager in one of three modes:

The endmqm command stops all instances of a multi-instance queue manager in the same way as it stops a single instance queue manager. You can issue the endmqm on either the active instance, or one of the standby instances of a multi-instance queue manager. You must issue endmqm on the active instance to end the queue manager.

If you issue the endmqm command on the active instance of a multi-instance queue manager, you can permit a standby instance to switch over to being the new active instance when the current active instance completes its shutdown.

If you issue the endmqm command on a standby instance of a multi-instance queue manager, you can end the standby instance by adding the -x option, and leave the active instance running. The queue manager reports an error if you issue endmqm on the standby instance without the -x option.

Issuing the endmqm command will affect any client application connected through a server-connection channel. The effect varies depending on the parameter used, but it is as though a STOP CHANNEL command was issued in one of the three possible modes. See Stopping channels , for information about the effects of STOP CHANNEL modes on server-connection channels. The endmqm optional parameter descriptions state which STOP CHANNEL mode they will be equivalent to.

If you issue endmqm to stop a queue manager, reconnectable clients do not try to reconnect. To override this behavior, specify either the -r or -s option to enable clients to start trying to reconnect.

Note: If a queue manager or a channel ends unexpectedly, reconnectable clients start trying to reconnect.

Note: The client might not reconnect to this queue manager. Depending on the MQCONNX reconnect option the client has used, and the definition of the queue manager group in the client connection table, the client might reconnect to a different queue manager. You can configure the client to force it to reconnect to the same queue manager.

You must use the endmqm command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

The attributes of the queue manager and the objects associated with it are not affected by the endmqm command. You can restart the queue manager using the strmqm (Start queue manager) command.

To delete a queue manager, stop it and then use the dltmqm (Delete queue manager) command.


Syntax

   
                       .- -c -.                         
>>-endmqm--+------+--+-+------+--+------+-+-- QMgrName----------><
           '- -z -'  | +- -w -+  +- -s -+ |             
                     | +- -i -+  '- -r -' |             
                     | '- -p -'           |             
                     '- -x ---------------'             



Required parameters

QMgrName
The name of the message queue manager to be stopped.


Optional parameters

-c
Controlled (or quiesced) shutdown. This parameter is the default.

The queue manager stops, but only after all applications have disconnected. Any MQI calls currently being processed are completed. In the unlikely event that a dspmq command is issued in the small timeframe between the applications disconnecting and the queue manager actually stopping, the dspmq command might transiently report the status as Ending immediately, even though a controlled shutdown was requested.

Control is returned to you immediately and you are not notified of when the queue manager has stopped.

The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in QUIESCE mode.

-i
Immediate shutdown. The queue manager stops after it has completed all the MQI calls currently being processed. Any MQI requests issued after the command has been issued fail. Any incomplete units of work are rolled back when the queue manager is next started.

Control is returned after the queue manager has ended.

The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in FORCE mode.

-p
Pre-emptive shutdown.


Use this type of shutdown only in exceptional circumstances. For example, when a queue manager does not stop as a result of a normal endmqm command.

The queue manager might stop without waiting for applications to disconnect or for MQI calls to complete. This can give unpredictable results for WebSphere MQ applications. The shutdown mode is set to immediate shutdown. If the queue manager has not stopped after a few seconds, the shutdown mode is escalated, and all remaining queue manager processes are stopped.

The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in TERMINATE mode.

-r
Start trying to reconnect reconnectable clients. This parameter has the effect of reestablishing the connectivity of clients to other queue managers in their queue manager group.
-s
Switch over to a standby queue manager instance after shutting down. The command checks that there is a standby instance running before ending the active instance. It does not wait for the standby instance to start before ending.

Connections to the queue manager are broken by the active instance shutting down. Reconnectable clients start trying to reconnect.

You can configure the reconnection options of a client to reconnect only to another instance of the same queue manager, or to reconnect to other queue managers in the queue manager group.

-w
Wait shutdown.

This type of shutdown is equivalent to a controlled shutdown except that control is returned to you only after the queue manager has stopped. You receive the message Waiting for queue manager qmName to end while shutdown progresses. In the unlikely event that a dspmq command is issued in the small timeframe between the applications disconnecting and the queue manager actually stopping, the dspmq command might transiently report the status as Ending immediately, even though a controlled shutdown was requested.

The effect on any client applications connected through a server-connection channel is equivalent to a STOP CHANNEL command issued in QUIESCE mode.

-x
End a standby instance of the queue manager, without ending the active instance of the queue manager.
-z
Suppresses error messages on the command.


Return codes

Return code Description
0 Queue manager ended
3 Queue manager being created
16 Queue manager does not exist
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
62 The queue manager is associated with a different installation
69 Storage not available
71 Unexpected error
72 Queue manager name error
77 WebSphere MQ queue manager cannot switch over
79 Active instance of WebSphere MQ queue manager QmgrName not ended
90 Standby instance of WebSphere MQ queue manager QmgrName not ended
119 Permission denied


Examples

The following examples show commands that stop the specified queue managers.

  1. This command ends the queue manager named mercury.queue.manager in a controlled way. All applications currently connected are allowed to disconnect.

     endmqm mercury.queue.manager
    
  2. This command ends the queue manager named saturn.queue.manager immediately. All current MQI calls complete, but no new ones are allowed.

     endmqm -i saturn.queue.manager
    

The results of issuing endmqm to the local instance of a multi-instance queue manager are shown in Table 1 . The results of the command depend on whether the -s or -x switch is used, and the running status of local and remote instances of the queue manager.

endmqm actions

endmqm option Local machine Remote machine RC Message Result
  Active None 0 - Queue manager ended.
Standby Queue manager ended, including the standby instance.
Standby Active 90 AMQ8368 Standby instance of WebSphere MQ queue manager QmgrName not ended.
-s Active None 77 AMQ7276 WebSphere MQ queue manager cannot switch over.
Standby 0 - Queue manager QMNAME ended, permitting switchover to a standby instance.
Standby Active 90 AMQ8368 Standby instance of WebSphere MQ queue manager QmgrName not ended.
-x Active None 79 AMQ8367 Active instance of WebSphere MQ queue manager QmgrName not ended.
Standby
Standby Active 0 - Standby instance of queue manager QMNAME ended.


Related commands

Command Description
crtmqm Create queue manager
strmqm Start queue manager
dltmqm Delete queue manager


endmqsvc (end IBM WebSphere MQ service)

The endmqsvc command ends the IBM WebSphere MQ service on Windows. Run the command on Windows only.


Purpose

The command ends the IBM WebSphere MQ service on Windows.

Run the command to end the service, if the service is running.

Restart the service for WebSphere MQ processes to pick up a new environment, including new security definitions.


Syntax

endmqsvc


Parameters

The endmqsvc command has no parameters.

You must set the path to the installation that contains the service. Either make the installation primary, run the setmqenv command, or run the command from the directory containing the endmqsvc binary file.


Related reference :


endmqtrc

End trace for some or all of the entities that are being traced.


Purpose

Use the endmqtrc command to end tracing for the specified entity or all entities. The endmqtrc command ends only the trace that is described by its parameters. Using endmqtrc with no parameters ends early tracing of all processes.


Syntax

The syntax of this command is as follows:

   
>>-endmqtrc--+----------------+--+---------------+-------------->
             '- -m -- QMgrName-'  '- -i -- PidTids-'   

>--+------------+--+------+--+------+--------------------------><
   '- -p -- Apps-'  '- -e -'  '- -a -'   



Optional parameters

-m QMgrName
The name of the queue manager for which to end tracing. This parameter applies to server products only.

The QMgrName supplied must match exactly the QMgrName supplied on the strmqtrc command. If the strmqtrc command used wildcards, the endmqtrc command must use the same wildcard specification including the escaping of any wildcard characters to prevent them being processed by the command environment.

A maximum of one -m flag and associated queue manager name can be supplied on the command.

-i PidTids
Process identifier (PID) and thread identifier (TID) for which to end tracing. You cannot use the -i flag with the -e flag. If you try to use the -i flag with the -e flag, then an error message is issued. This parameter must only be used under the guidance of IBM Service personnel.
-p Apps
The named processes for which to end tracing. Apps is a comma-separated list. You must specify each name in the list exactly as the program name would be displayed in the "Program Name" FDC header. Asterisk (*) or question mark (?) wildcards are allowed. You cannot use the -p flag with the -e flag. If you try to use the -p flag with the -e flag, then an error message is issued.
-e
Ends early tracing of all processes.

Use endmqtrc with no parameters has the same effect as endmqtrc -e. You cannot specify the -e flag with the -m flag, the -i flag, or the -p flag.

-a
Ends all tracing.

This flag must be specified alone.


Return codes

Return code Description
AMQ5611 This message is issued if you supply invalid arguments to the command.
58 Inconsistent use of installations detected


Examples

This command ends tracing of data for a queue manager called QM1.

 endmqtrc -m QM1

The following examples are a sequence that shows how the endmqtrc command ends only the trace that is described by its parameters.

  1. The following command enables tracing for queue manager QM1 and process amqxxx.exe:

     strmqtrc -m QM1 -p amqxxx.exe
    
  2. The following command enables tracing for queue manager QM2:

     strmqtrc -m QM2
    
  3. The following command ends tracing for queue manager QM2 only. Tracing of queue manager QM1 and process amqxxx.exe continues:

     endmqtrc -m QM2
    


Related commands

Command Description
dspmqtrc Display formatted trace output
strmqtrc Start trace


migmbbrk

The migmbbrk command migrates publish/subscribe configuration data from WebSphere Event Broker Version 6.0 or WebSphere Message Broker Version 6.0 or 6.1 to WebSphere MQ Version 7.0.1 or later versions.


Purpose


The migmbbrk command is not supported on all of the platforms that WebSphere MQ supports. See Supported operating systems for details.

To use the migmbbrk command you must be using at least WebSphere Message Broker Version 6.0, Fix Pack 9, or WebSphere Message Broker Version 6.1, Fix Pack 4.

Use the migmbbrk command to migrate the publish/subscribe configuration data from a WebSphere Event Broker Version 6.0 or a WebSphere Message Broker Version 6.0 or Version 6.1 broker to a WebSphere MQ Version 7.0.1 or later queue manager. The command runs a migration process that migrates the following publish/subscribe configuration data to the queue manager that is associated with the named broker:

The migmbbrk command does not migrate the Access Control List (ACL). Instead, running the migration with the -t or -r parameters produces a file containing suggested setmqaut commands to set up a security environment in the queue manager that is equivalent to the security environment that existed in the broker. You must review and modify the security command file as needed and run the commands to set up a security environment in the queue manager, equivalent to the one that existed in the broker, before running the migration with the -c parameter to complete the migration.

Note: On UNIX systems, all authorities are held by user groups internally, not by principals. This has the following implications:

You must issue the migmbbrk command from a command window that can execute both WebSphere MQ and WebSphere Message Broker commands successfully. Typically this is true if the command is issued from a WebSphere Message Broker command console.

The WebSphere Event Broker Version 6.0 or WebSphere Message Broker Version 6.0 or 6.1 publish/subscribe configuration data, which is stored in the subscription database tables, is not deleted by the migration process. This configuration data is therefore available to use until you explicitly delete it.


Syntax

   
                      .---------.                    
                      V         |                    
>>-migmbbrk--+- -c +----+-----+-+-- -b - BrokerName-------------><
             +- -r +    +- -l +                      
             '- -t '    +- -o +                      
                        +- -s +                      
                        '- -z '                      



Required parameters

-b BrokerName
The name of the broker that is the source of the publish/subscribe configuration data that is to be migrated. The queue manager to which the publish/subscribe configuration data is migrated is the queue manager that is associated with the named broker.
-c
Complete the migration of the publish/subscribe configuration data. The completion phase of the migration uses the topic objects that are created in the initial -t phase. It is possible that the broker state has changed since the initial phase was run and that new additional topic objects are now required. If so, the completion phase creates new topic objects as necessary. The completion phase does not delete any topic objects that have become unnecessary; you might need to delete any topic objects that you do not require.

Before you complete the migration you must review and modify the security command file produced in the -r or -t phase as required and execute the commands to set up a security environment in the queue manager, equivalent to the one that existed in the broker.

Before you run this completion phase, you must run the initial -t phase. You cannot use the -c parameter with the -r parameter or the -t parameter. This phase also creates a migration log.

-r
Rehearse the migration process but do not change anything. You can use this parameter before running the migration with the -t parameter, to create a migration log, including any errors, so that you can observe what the result of the migration process would be, but without changing the current configurations.

Rehearsing the migration also produces a file containing suggested setmqaut commands to set up a security environment in the queue manager that is equivalent to the security environment that existed in the broker. Before you complete the migration with the -c parameter you must review and modify the security command file as required and execute the commands to set up a security environment in the queue manager, equivalent to the one that existed in the broker.

You cannot use the -r parameter with the -c parameter or the -t parameter.

-t
Create topic objects that might be needed in the queue manager, based on the ACL entries that are defined in the broker.

Use of the -t parameter also produces a file containing suggested setmqaut commands to set up a security environment in the queue manager that is equivalent to the security environment that existed in the broker. The topic objects are created in anticipation of you executing the security commands to create ACLs for the topic objects. Before you complete the migration with the -c parameter you must review and modify the security command file as required and execute the commands to set up a security environment in the queue manager, equivalent to the one that existed in the broker.

You must run this phase before running the completion phase with the -c parameter. You cannot use the -t parameter with the -c parameter or the -r parameter. This phase also creates a migration log.


Optional parameters

-l
Leave the broker running. If you do not specify this parameter, the broker is shut down by default at the end of the migration process.
-o
Overwrite any subscription or retained publication that exists in the queue manager and that has the same name as a subscription or retained publication that is being migrated from the broker, with the publish/subscribe configuration data that was retrieved from the broker. The -o parameter has no effect if you use it with the -r parameter.
-s
Discard any intermediate configuration data that was retained from a previous instance of the migration process that failed or was interrupted. The migration process populates private queues with temporary data. If the migration process completes successfully, the temporary data is deleted. If you do not specify this parameter and the migration process fails or is interrupted, the temporary data is retained and is used by the migration process if you restart it, so that the process resumes at the point where it previously failed or was interrupted.
-z
Run the migration process, regardless of whether it has previously run to a successful completion. If you do not specify this parameter and the migration process has previously run to a successful completion, the process recognizes this fact and exits. You can use the -o parameter with the -z parameter, but this is not mandatory. A previous rehearsal of the migration using the -r parameter does not count as a successful completion.


Return codes

Return Code Explanation
0 Migration completed successfully
20 An error occurred during processing


Output files

The migration process writes two output files to the current directory:

amqmigrateacl.txt

A file containing a list of setmqaut commands, created in the current directory for you to review, change, and run if appropriate, to help you to reproduce your ACLs.

amqmigmbbrk.log

A log file containing a record of the details of the migration.


Examples

This command migrates the publish/subscribe configuration data of broker BRK1 into its associated queue manager and specifies that the migration process runs regardless of whether it has previously run to a successful completion. It also specifies that any subscription or retained publication that exists in the queue manager, that has the same name as a subscription or retained publication that is being migrated from the broker, must be overwritten.

 migmbbrk -z -o -b BRK1


Supported operating systems

The migmbbrk command is supported only on the following platforms that support WebSphere Event Broker Version 6.0 or WebSphere Message Broker Version 6.0:

On z/OS, the equivalent function to the migmbbrk command is provided by the CSQUMGMB utility.


MQExplorer (launch WebSphere MQ Explorer)

Start WebSphere MQ Explorer (Windows, Linux x86, and Linux x86-64 platforms only).


Purpose

To launch WebSphere MQ Explorer by using the system menu on Linux, or the start menu on Windows, you must left-click on the installation that you want to launch.

On Windows, open the start menu, and select the WebSphere MQ Explorer installation entry under the IBM WebSphere MQ folder that corresponds to the installation that you want to launch. Each instance of WebSphere MQ Explorer listed is identified by the name that you chose for its installation.

On Linux, the system menu entry for WebSphere MQ Explorer is added to the Development category. Where it appears within the system menu is dependent on your Linux distribution (SUSE or Red Hat), and your desktop environment (GNOME or KDE).


Syntax

The MQExplorer command is stored in MQ_INSTALLATION_PATH/bin. MQExplorer.exe (the MQExplorer command) supports standard Eclipse runtime options. The syntax of this command is as follows:

   
>>-MQExplorer--+------+--+------+------------------------------><
               '- -c -'  '- -i -'   



Optional parameters

-c
-clean is passed to Eclipse. This parameter causes Eclipse to delete any cached data used by the Eclipse runtime.
-i
-init is passed to Eclipse. This parameter causes Eclipse to discard configuration information Used by the Eclipse runtime.


mqrc (MQ return code)

Display information about return codes.


Purpose

You can use the mqrc command to display information about symbols, return codes, and AMQ messages. You can specify a range of return codes or AMQ messages, as well as specifying specific return codes or AMQ messages.

Numeric arguments are interpreted as decimal if they start with a digit 1 - 9, or hex if prefixed with 0x.


Syntax

   
>>-+-+-----+--+-----+--+- returnCode-------------------------+-+-><
   | '- -a '  '- -b '  +- -r - returnCode--------------------+ |   
   |                   +- AMQmessage-------------------------+ |   
   |                   +- -m - AMQmessage--------------------+ |   
   |                   +- -R -+---------------------------+-+ |   
   |                   |      |                       (1) | | |   
   |                   |      '- -f - first-- -l - last-----' | |   
   |                   |                            (1)     | |   
   |                   '- -M - -f - first-- -l - last---------' |   
   '-+-----+-- symbol------------------------------------------'   
     '- -s-'                                                      


Notes:

  1. If there is a problem with a message within a range, an indication is displayed before the message text. ? is displayed if the message severity is different to the return code severity.


Parameters

returnCode
The return code to display
AMQmessage
The AMQ message to display
symbol
The symbol to display
-a
Try all severities to find message text
-b
Display messages without extended information
-f first
First number in a range
-l last
Last number in a range
-m AMQmessage
The AMQ message to list
-M
Display AMQ messages in a range
-r returnCode
The return code to display
-R
Display all return codes. If used with the -f and -l parameters, -R displays the return codes within a range.
-s symbol
The symbol to display


Examples

  1. This command displays AMQ message 5005:

     mqrc AMQ5005
    
  2. This command displays return codes in the range 2505 - 2530:

     mqrc -R -f 2505 -l 2530
    


rcdmqimg

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 recreate the object from the image.

rcdmqimg must be run manually or from an automated task you have created. 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 WebSphere MQ .

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

   
>>-rcdmqimg--+----------------+--+------+--+------+------------->
             '- -m -- QMgrName-'  '- -z -'  '- -l -'   

>--  -t ObjectType-- GenericObjName------------------------------><



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 you 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:

Note: When using WebSphere MQ for UNIX systems, you must prevent the shell from interpreting the meaning of special characters, for example, an asterisk (*). How you do this depends on the shell you 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 you 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.
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


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 Recreate a queue manager object


rcrmqobj

Re-create an object, or group of objects, from their images contained in the log.


Purpose

Use this command to re-create an object, or group of objects, from their images contained in the log. This command can only be used when using linear logging. Use the associated command, rcdmqimg, to record the object images to the log.

Use this command on a running queue manager. All activity on the queue manager after the image was recorded is logged. To re-create an object, replay the log to re-create events that occurred after the object image was captured.


Syntax

   
>>-rcrmqobj--+----------------+--+------+--  -t ObjectType------->
             '- -m -- QMgrName-'  '- -z -'                   

>-- GenericObjName----------------------------------------------><



Required parameters

GenericObjName
The name of the object to re-create. This parameter can have a trailing asterisk to re-create any objects with names matching the portion of the name before the asterisk.

This parameter is required unless the object type is the channel synchronization file; any object name supplied for this object type is ignored.

-t ObjectType
The types of object to re-create. Valid object types are:

Note: When using WebSphere MQ for UNIX systems, you must prevent the shell from interpreting the meaning of special characters, for example, an asterisk (*). How you do this depends on the shell you 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 re-create objects. If omitted, the command operates on the default queue manager.
-z
Suppresses error messages.


Return codes

Return code Description
0 Successful operation
26 Queue manager running as a standby instance.
36 Invalid arguments supplied
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
66 Media image not available
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
135 Temporary object cannot be recovered
136 Object in use


Examples

  1. The following command re-creates all local queues for the default queue manager:

     rcrmqobj -t ql *
    
  2. The following command re-creates all remote queues associated with queue manager store:

     rcrmqobj -m store -t qr *
    


Related commands

Command Description
rcdmqimg Record an object in the log


rmvmqinf

Remove WebSphere MQ configuration information (Windows and UNIX platforms only).


Purpose

Use the rmvmqinf command to remove WebSphere MQ configuration information.

You must use the rmvmqinf command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.


Syntax

   
             .- -s -QueueManager-.               
>>-rmvmqinf -+-------------------+-- StanzaName-----------------><
             '- -s - StanzaType---'               



Required parameters

StanzaName
The name of the stanza. That is, the value of the key attribute that distinguishes between multiple stanzas of the same type.


Optional parameters

-s StanzaType
The type of stanza to remove. If omitted, a QueueManager stanza is removed.
The only supported value of StanzaType is QueueManager.


Return codes

Return code Description
0 Successful operation
5 Queue manager is running
26 Queue manager is running as a standby instance
39 Bad command line parameters
44 Stanza does not exist
49 Queue manager is stopping
58 Inconsistent use of installations detected
69 Storage is not available
71 Unexpected error
72 Queue manager name error


Example

 rmvmqinf QM.NAME


Usage notes

Use rmvmqinf to remove an instance of a multi-instance queue manager.

To use this command you must be a WebSphere MQ administrator and a member of the mqm group.


Related commands

Command Description
addmqinf Add queue manager configuration information
dspmqinf Display queue manager configuration information


rsvmqtrn

Resolve in-doubt and heuristically completed transactions


Purpose

The rsvmqtrn command is used to resolve two different transaction states.

in-doubt transactions

Use the rsvmqtrn command to commit or back out internally or externally coordinated in-doubt transactions.

Note: Use this command only when you are certain that transactions cannot be resolved by the normal protocols. Issuing this command might result in the loss of transactional integrity between resource managers for a distributed transaction.

heuristically completed transactions

Use the rsvmqtrn command with the -f option for WebSphere MQ to remove all information about externally coordinated transactions that were previously resolved manually using the rsvmqtrn command, but the resolution has not been acknowledged by the transaction coordinator using the xa-forget command. Transactions that are manually resolved by a resource manager and unacknowledged by the transaction manager, are known as heuristically completed transactions by X/Open.

Note: Only use the -f option if the external transaction coordinator is permanently unavailable. The queue manager, as a resource manager, remembers the transactions that are committed or backed out manually by the rsvmqtrn command.


Syntax

   
>>-rsvmqtrn--+- -a -------------------------+-- -m -- QMgrName--><
             '-+- -b --------+-- Transaction-'                   
               +- -c --------+                                  
               +- -f --------+                                  
               '- -r -- RMID -'                                  



Required parameters

-m QMgrName
The name of the queue manager.


Optional parameters

-a
The queue manager resolves all internally coordinated, in-doubt transactions (that is, all global units of work).
-b
Backs out the named transaction. This flag is valid for externally coordinated transactions (that is, for external units of work) only.
-c
Commits the named transaction. This flag is valid for externally coordinated transactions (that is, external units of work) only.
-f
Forgets the named heuristically completed transaction. This flag is valid only for externally coordinated transactions (that is, external units of work) that are resolved, but unacknowledged by the transaction coordinator.

Note: Use only if the external transaction coordinator is never going to be able to acknowledge the heuristically completed transaction. For example, if the transaction coordinator has been deleted.

-r RMID
The participation of the resource manager in the in-doubt transaction can be ignored. This flag is valid for internally coordinated transactions only, and for resource managers that have had their resource manager configuration entries removed from the queue manager configuration information.

Note: The queue manager does not call the resource manager. Instead, it marks the participation of the resource manager in the transaction as being complete.

Transaction
The transaction number of the transaction being committed or backed out. Use the dspmqtrn command to find the relevant transaction number. This parameter is required with the -b, -c, and -r RMID parameters.


Return codes

Return code Description
0 Successful operation
26 Queue manager running as a standby instance.
32 Transactions could not be resolved
34 Resource manager not recognized
35 Resource manager not permanently unavailable
36 Invalid arguments supplied
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
69 Storage not available
71 Unexpected error
72 Queue manager name error
85 Transactions not known


Related commands

Command Description
dspmqtrn Display list of prepared transactions


runmqchi

Run a channel initiator process to automate starting channels.


Purpose

Use the runmqchi command to run a channel initiator process.

You must use the runmqchi command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

The channel initiator is started by default as part of the queue manager.


Syntax

   
>>-runmqchi--+-----------------------+--+----------------+-----><
             '- -q -- InitiationQName-'  '- -m -- QMgrName-'   



Optional parameters

-q InitiationQName
The name of the initiation queue to be processed by this channel initiator. If you omit it, SYSTEM.CHANNEL.INITQ is used.
-m QMgrName
The name of the queue manager on which the initiation queue exists. If you omit the name, the default queue manager is used.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing

If errors occur that result in return codes of either 10 or 20, review the queue manager error log that the channel is associated with for the error messages, and the system error log for records of problems that occur before the channel is associated with the queue manager. For more information about error logs, see Error log directories .


runmqchl

Start a sender or requester channel


Purpose

Use the runmqchl command to run either a sender (SDR) or a requester (RQSTR) channel.

The channel runs synchronously. To stop the channel, issue the MQSC command STOP CHANNEL.


Syntax

   
>>-runmqchl-- -c -- ChannelName--+----------------+-------------><
                                '- -m -- QMgrName-'   



Required parameters

-c ChannelName
The name of the channel to run.


Optional parameters

-m QMgrName
The name of the queue manager with which this channel is associated. If you omit the name, the default queue manager is used.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing

If return codes 10 or 20 are generated, review the error log of the associated queue manager for the error messages, and the system error log for records of problems that occur before the channel is associated with the queue manager.


runmqdlq

Start the dead-letter queue handler to monitor and process messages on the dead-letter queue.


Purpose

Use the runmqdlq command to start the dead-letter queue (DLQ) handler, which monitors and handles messages on a dead-letter queue.


Syntax

   
>>-runmqdlq--+-------------------------+-----------------------><
             '-  QName --+------------+-'   
                        '-  QMgrName -'     



Description

Use the dead-letter queue handler to perform various actions on selected messages by specifying a set of rules that can both select a message and define the action to be performed on that message.

The runmqdlq command takes its input from stdin. When the command is processed, the results and a summary are put into a report that is sent to stdout.

By taking stdin from the keyboard, you can enter runmqdlq rules interactively.

By redirecting the input from a file, you can apply a rules table to the specified queue. The rules table must contain at least one rule.

If you use the DLQ handler without redirecting stdin from a file (the rules table), the DLQ handler reads its input from the keyboard. In WebSphere MQ for AIX, Solaris, HP-UX, and Linux, the DLQ handler does not start to process the named queue until it receives an end_of_file (Ctrl+D) character. In WebSphere MQ for Windows, it does not start to process the named queue until you press the following sequence of keys: Ctrl+Z, Enter, Ctrl+Z, Enter.

For more information about rules tables and how to construct them, see The DLQ handler rules table .


Optional parameters

The MQSC command rules for comment lines and for joining lines also apply to the DLQ handler input parameters.

QName
The name of the queue to be processed.

If you omit the name, the dead-letter queue defined for the local queue manager is used. If you enter one or more blanks (' '), the dead-letter queue of the local queue manager is explicitly assigned.

QMgrName
The name of the queue manager that owns the queue to be processed.

If you omit the name, the default queue manager for the installation is used. If you enter one or more blanks (' '), the default queue manager for this installation is explicitly assigned.


runmqdnm

Start processing messages on a queue using the .NET monitor (Windows only).


Purpose

Note: The runmqdnm command applies to WebSphere MQ for Windows only.


runmqdnm can be run from the command line, or as a triggered application.

Use the runmqdnm control command to start processing messages on an application queue with a .NET monitor.


Syntax

   
>>-runmqdnm-- -q -- QueueName-- -a -- AssemblyName---------------->

>--+----------------+--+-----------------+---------------------->
   '- -m -- QMgrName-'  '- -c -- ClassName-'   

>--+---------------------+--+-----------------+----------------->
   '- -u -- UserParameter-'  '- -s -- Syncpoint-'   

>--+------------------+--+------------------+------------------->
   '- -d -- Conversion-'  '- -n -- MaxThreads-'   

>--+---------------+--+------------------------+---------------->
   '- -t -- Timeout-'  '- -b -- BackoutThreshold-'   

>--+-----------------+--+---------------------+----------------><
   '- -r -- QueueName-'  '- -p -- ContextOption-'   



Required parameters

-q QueueName
The name of the application queue to monitor.
-a AssemblyName
The name of the .NET assembly.


Optional parameters

-m QMgrName
The name of the queue manager that hosts the application queue.

If omitted, the default queue manager is used.

-c ClassName
The name of the .NET class that implements the IMQObjectTrigger interface. This class must reside in the specified assembly.

If omitted, the specified assembly is searched to identify classes that implement the IMQObjectTrigger interface:

  • If one class is found, then ClassName takes the name of this class.
  • If no classes or multiple classes are found, then the .NET monitor is not started and a message is written to the console.

-u UserData
User-defined data. This data is passed to the Execute method when the .NET monitor calls it. User data must contain ASCII characters only, with no double quotation marks, NULLs, or carriage returns.

If omitted, null is passed to the Execute method.

-s Syncpoint
Specifies whether sync point control is required when messages are retrieved from the application queue. Possible values are:

If omitted, the value of Syncpoint is dependent on your transactional model:

  • If distributed transaction coordination (DTC) is being used, then Syncpoint is specified as YES.
  • If distributed transaction coordination (DTC) is not being used, then Syncpoint is specified as PERSISTENT.

-d Conversion
Specifies whether data conversion is required when messages are retrieved from the application queue. Possible values are:

If omitted, Conversion is specified as NO.

-n MaxThreads
The maximum number of active worker threads.

If omitted, MaxThreads is specified as 20.

-t Timeout
The time, in seconds, that the .NET monitor waits for further messages to arrive on the application queue. If you specify -1, the .NET monitor waits indefinitely.

If omitted when run from the command line, the .NET monitor waits indefinitely.

If omitted when run as a triggered application, the .NET monitor waits for 10 seconds.

-b BackoutThreshold
Specifies the backout threshold for messages retrieved from the application queue. Possible values are:

If omitted, BackoutThreshold is specified as -1.

-r QueueName
The queue to which messages, with a backout count exceeding the backout threshold, are put.

If omitted, the value of QueueName is dependent on the value of the BOQNAME attribute from the application queue:

  • If BOQNAME is non-blank, then QueueName takes the value of BOQNAME.
  • If BOQNAME is blank, then QueueName is specified as the queue manager dead letter queue. If a dead letter queue has not been assigned to the queue manager, then backout processing is not available.

-p ContextOption
Specifies whether context information from a message that is being backed out is passed to the backed out message. Possible values are:

If omitted, ContextOption is specified as ALL.


Return codes

Return code Description
0 Successful operation
36 Invalid arguments supplied
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
71 Unexpected error
72 Queue manager name error
133 Unknown object name error


runmqlsr

Run a listener process to listen for remote requests on various communication protocols.


Purpose

Use the runmqlsr command to start a listener process.

This command is run synchronously and waits until the listener process has finished before returning to the caller.


Syntax

   
>>-runmqlsr-- -t ----------------------------------------------->

>--+- tcp --+------------+--+--------------+--+---------------+-+-->
   |        '- -p -- Port-'  '- -i -- IPAddr-'  '- -b -- Backlog-' |   
   +- lu62 -- -n -- TpName---------------------------------------+   
   |            .---------------------.                         |   
   |            V                     |                         |   
   +- netbios ----+-----------------+-+-------------------------+   
   |              +- -a -- Adapter---+                           |   
   |              +- -l -- LocalName-+                           |   
   |              +- -e -- Names-----+                           |   
   |              +- -s -- Sessions--+                           |   
   |              '- -o -- Commands--'                           |   
   |        .-------------------.                               |   
   |        V                   |                               |   
   '- spx ----+---------------+-+-------------------------------'   
              +- -x -- Socket--+                                     
              '- -b -- Backlog-'                                     

>--+----------------+------------------------------------------><
   '- -m -- QMgrName-'   



Required parameters

-t
The transmission protocol to be used:


Optional parameters

-p Port
The port number for TCP/IP. This flag is valid for TCP only. If you omit the port number, it is taken from the queue manager configuration information, or from defaults in the program. The default value is 1414. It must not exceed 65535.
-i IPAddr
The IP address for the listener, specified in one of the following formats:

  • IPv4 dotted decimal
  • IPv6 hexadecimal notation
  • Alphanumeric format

This flag is valid for TCP/IP only.

On systems that are both IPv4 and IPv6 capable you can split the traffic by running two separate listeners. One listening on all IPv4 addresses and one listening on all IPv6 addresses. If you omit this parameter, the listener listens on all configured IPv4 and IPv6 addresses.

-n TpName
The LU 6.2 transaction program name. This flag is valid only for the LU 6.2 transmission protocol. If you omit the name, it is taken from the queue manager configuration information.
-a Adapter
The adapter number on which NetBIOS listens. By default the listener uses adapter 0.
-l LocalName
The NetBIOS local name that the listener uses. The default is specified in the queue manager configuration information.
-e Names
The number of names that the listener can use. The default value is specified in the queue manager configuration information.
-s Sessions
The number of sessions that the listener can use. The default value is specified in the queue manager configuration information.
-o Commands
The number of commands that the listener can use. The default value is specified in the queue manager configuration information.
-x Socket
The SPX socket on which SPX listens. The default value is hexadecimal 5E86.
-m QMgrName
The name of the queue manager. By default the command operates on the default queue manager.
-b Backlog
The number of concurrent connection requests that the listener supports. See TCP, LU62, NETBIOS, and SPX for a list of default values and further information.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing: the AMQMSRVN process did not start.


Examples

The following command runs a listener on the default queue manager using the NetBIOS protocol. The listener can use a maximum of five names, five commands, and five sessions. These resources must be within the limits set in the queue manager configuration information.

 runmqlsr -t netbios -e 5 -s 5 -o 5


runmqras

runmqras is used to gather WebSphere MQ diagnostic information together into a single archive, for example to submit to IBM Support.


Purpose

The runmqras command is used to gather diagnostic information from a machine, into a single archive. You can use this command to gather information about an application or WebSphere MQ failure, possibly for submission into IBM when you report a problem.

By default, runmqras gathers information such as:

Running without requesting more sections is intended as a starting point for general problem diagnosis, however, you can request more sections through the command line.

These additional sections gather more detailed information, depending on the type of problem being diagnosed. If non-default sections are needed by IBM support personnel, they will tell you.

The runmqras command can be run under any user ID, but the command only gathers information that the user ID can gather manually. In general, when debugging WebSphere MQ problems, run the command under the mqm user ID to allow the command to gather queue manager files and command outputs.


Syntax

   
>>-runmqras--+- zipfile --  ZipFileName--------+----------------><
             +- outputdir --  path-------------+   
             +- workdirectory -- path----------+   
             +- section-- SectionA, SectionB---+   
             +- qmlist-- QMA[, QMB]------------+   
             +- timeout-- secs-----------------+   
             +- demo--------------------------+   
             +-v------------------------------+   
             +-+- ftp-- IBM------------------+-+   
             | +- ftp-- custom---------------+ |   
             | '-+- ftpserver--  server----+-' |   
             |   +- ftpusername-- userid---+   |   
             |   +- ftppassword-- password-+   |   
             |   '-  ftpdirectory-- path---'   |   
             '- pmrno-- 12345,678,9AB----------'   



Keywords and parameters

All parameters are required unless the description states they are optional.

In every case, QMgrName is the name of the queue manager to which the command applies.

zipfile ZipFileName
Supply the file name of the resulting archive.

By default, the name of the output archive is runmqras.zip.

outputdirpath
The directory in which the resulting output file is placed.

By default, the output directory is the same as the work directory.

workdirectorypath
The directory that is used for storing the output from commands that are run during the processing of the tool. If supplied, this directory must either not exist, in which case it is created, or must be empty.

If you do not supply the path, a directory under /tmp is used on UNIX systems, and under %temp% is used on Windows, whose name starts with runmqras and is suffixed by the date and time.

section SectionA, SectionB
The optional sections about which to gather more specific information.

By default, a generic section of documentation is collected, whereas more specific information can be gathered for a specified problem type; for example, a section name of trace gathers all of the contents of the trace directory.

The default collections can be avoided by supplying a section name of nodefault.

IBM support generally supplies you with the sections to use. Example available sections are:

all

Gathers all possible information, including all trace files, and diagnostics for many different types of problems. You must use this option only in certain circumstances and this option is not intended for general use.

nodefault

Prevents the default collections from occurring, but other explicitly requested sections are still collected.

trace

Gather all the trace file information plus the default information

defs

Gather the queue manager definitions and status

cluster

Gather information specific for clustering
qmlist QMA[,QMB]
A list of queue manager names on which the runmqras command is to be run. This parameter does not apply to a client product (for example, HP Integrity NonStop Server) because there are no queue managers from which to request direct output.

By supplying a comma-separated list, you can restrict the iteration across queue managers to a specific list of queue managers. By default, iteration of commands is across all queue managers.

timeout secs
The default timeout to give an individual command before the command stops waiting for completion.

By default, a timeout of 10 seconds is used. A value of zero means wait indefinitely.

demo
Run in demonstration mode where no commands are processed, and no files gathered.

By running in demonstration mode, you can see exactly which commands would have been processed, and what files would have been gathered. The output zip file contains a console.log file that documents exactly what would have been processed and gathered, should the command be run normally.

-v
Extends the amount of information that is logged in the console.log file, contained in the output zip file.
ftp ibm/custom
Allows the collected archive to be sent through basic FTP to a remote destination.

At the end of processing, the resultant archive can be sent through basic FTP, either directly into IBM, or to a site of your choosing. If you select the ibm option, anonymous FTP is used to deliver the archive into the IBM ECuRep server. This process is identical to submitting the file manually using FTP.

Note if you select the ibm option, you must also provide the pmrno option, and all other FTP* options are ignored.

ftpserverserver
An FTP server name to connect to, when an FTP custom option is used.
ftpusernameuserid
The user ID to log in to the FTP server with, when an FTP custom option is used.
ftppasswordpassword
The password to log in to the FTP server with, when an FTP custom option is used.
ftpdirectorypath
The directory on the FTP server to place the resulting zip file into, used when an FTP custom option is used.
pmrno12345,678,9AB
A valid IBM PMR number (problem record number) against which to associate the documentation.

Use this option to ensure that the output is prefixed with your PMR Number, so that when the information is sent into IBM, the information is automatically associated with that problem record.


Examples

This command gathers the default documentation from the WebSphere MQ installation, and all queue managers on a machine:

 runmqras

This command gathers the default documentation from the WebSphere MQ installation on a machine, and sends it directly into IBM to be associated with PMR number 11111,222,333 using the basic FTP capability:

 runmqras -ftp ibm -pmrno 11111,222,333

This command gathers the default documentation from a machine, plus all trace files, the queue manager definitions, and status for all queue managers on the machine:

 runmqras -section trace,defs


Return codes

A non zero return code indicates failure.


runmqsc

Run WebSphere MQ commands on a queue manager.


Purpose

Use the runmqsc command to issue MQSC commands to a queue manager. MQSC commands enable you to perform administration tasks, for example defining, altering, or deleting a local queue object. MQSC commands and their syntax are described in the MQSC reference .

You must use the runmqsc command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

To end using the runmqsc command, use the end command. You can also use the exit or the quit command to stoprunmqsc.


Syntax

   
>>-runmqsc--+------+--+------+---------------------------------->
            '- -e -'  '- -v -'   

>--+----------------------------------------------------+------->
   |                           .- -m - DefaultQMgrName-. |   
   '- -w -- WaitTime--+------+--+----------------------+-'   
                     '- -x -'  '- -m - LocalQMgrName---'     

>--+----------+------------------------------------------------><
   '- QMgrName-'   



Description

You can start the runmqsc command in three ways:

Verify command

Verify MQSC commands but do not run them. An output report is generated indicating the success or failure of each command. This mode is available on a local queue manager only.

Run command directly

Send MQSC commands directly to a local queue manager.

Run command indirectly

Run MQSC commands on a remote queue manager. These commands are put on the command queue on a remote queue manager and run in the order in which they were queued. Reports from the commands are returned to the local queue manager.

The runmqsc command takes its input from stdin. When the commands are processed, the results and a summary are put into a report that is sent to stdout.

By taking stdin from the keyboard, you can enter MQSC commands interactively.

By redirecting the input from a file, you can run a sequence of frequently used commands contained in the file. You can also redirect the output report to a file.


Optional parameters

-e
Prevents source text for the MQSC commands from being copied into a report. This parameter is useful when you enter commands interactively.
-m LocalQMgrName
The local queue manager that you want to use to submit commands to the remote queue manager. If you omit this parameter the local default queue manager is used to submit commands to the remote queue manager.
-v
Verifies the specified commands without performing the actions. This mode is only available locally. The -w and -x flags are ignored if they are specified at the same time.
-w WaitTime
Run the MQSC commands on another queue manager. You must have the required channel and transmission queues set up for this. See Preparing channels and transmission queues for remote administration for more information.

WaitTime

The time, in seconds, that runmqsc waits for replies. Any replies received after this are discarded, but the MQSC commands still run. Specify a time in the range 1 through 999 999 seconds.

Each command is sent as an Escape PCF to the command queue (SYSTEM.ADMIN.COMMAND.QUEUE) of the target queue manager.

The replies are received on queue SYSTEM.MQSC.REPLY.QUEUE and the outcome is added to the report. This can be defined as either a local queue or a model queue.

This flag is ignored if the -v flag is specified.

-x
The target queue manager is running under z/OS. This flag applies only in indirect mode. The -w flag must also be specified. In indirect mode, the MQSC commands are written in a form suitable for the WebSphere MQ for z/OS command queue.
QMgrName
The name of the target queue manager on which to run the MQSC commands, by default, the default queue manager.


Return codes

Return code Description
00 MQSC command file processed successfully
10 MQSC command file processed with errors; report contains reasons for failing commands
20 Error; MQSC command file not run


Examples

  1. Enter this command at the command prompt:

     runmqsc
    
    Now you can enter MQSC commands directly at the command prompt. No queue manager name is specified, so the MQSC commands are processed on the default queue manager.
  2. Use one of these commands, as appropriate in your environment, to specify that MQSC commands are to be verified only:

     runmqsc -v BANK < "/u/users/commfile.in"
     
    runmqsc -v BANK < "c:\users\commfile.in"
    
    This command verifies the MQSC commands in file commfile.in. The queue manager name is BANK. The output is displayed in the current window.
  3. These commands run the MQSC command file mqscfile.in against the default queue manager.

     runmqsc < "/var/mqm/mqsc/mqscfile.in" > "/var/mqm/mqsc/mqscfile.out"
     
    runmqsc < "c:\Program Files\IBM\WebSphere MQ\mqsc\mqscfile.in" > 
    	"c:\Program Files\IBM\WebSphere MQ\mqsc\mqscfile.out"
    
    In this example, the output is directed to file mqscfile.out.
  4. This command submits commands to the QMREMOTE queue manager, using QMLOCAL to submit the commands.

     runmqsc -w 30 -m QMLOCAL QMREMOTE
    


runmqtmc

Start the trigger monitor on a client.


Purpose

Use the runmqtmc command to start a trigger monitor for a client. For further information about using trigger monitors, see Trigger monitors .

When a trigger monitor starts, it continuously monitors the specified initiation queue. The trigger monitor does not stop until the queue manager ends, see endmqm . While the client trigger monitor is running it keeps the dead letter queue open.


Syntax

   
>>-runmqtmc--+----------------+--+-----------------------+------>
             '- -m -- QMgrName-'  '- -q -- InitiationQName-'   

>--+-----+-----------------------------------------------------><
   '- -r '   



Optional parameters

-m QMgrName
The name of the queue manager on which the client trigger monitor operates, by default the default queue manager.
-q InitiationQName
The name of the initiation queue to be processed, by default SYSTEM.DEFAULT.INITIATION.QUEUE.
-r
Specifies that the client trigger monitor automatically reconnects.


Return codes

Return code Description
0 Not used. The client trigger monitor is designed to run continuously and therefore not to end. The value is reserved.
10 Client trigger monitor interrupted by an error.
20 Error; client trigger monitor not run.


Examples

For examples of using this command, see The Triggering sample programs .


runmqtrm

Start the trigger monitor on a server.


Purpose

Use the runmqtrm command to start a trigger monitor. For further information about using trigger monitors, see Trigger monitors .

When a trigger monitor starts, it continuously monitors the specified initiation queue. The trigger monitor does not stop until the queue manager ends, see endmqm . While the trigger monitor is running it keeps the dead letter queue open.


Syntax

   
>>-runmqtrm--+----------------+--+-----------------------+-----><
             '- -m -- QMgrName-'  '- -q -- InitiationQName-'   



Optional parameters

-m QMgrName
The name of the queue manager on which the trigger monitor operates, by default the default queue manager.
-q InitiationQName
Specifies the name of the initiation queue to be processed, by default SYSTEM.DEFAULT.INITIATION.QUEUE.


Return codes

Return code Description
0 Not used. The trigger monitor is designed to run continuously and therefore not to end. Hence a value of 0 would not be seen. The value is reserved.
10 Trigger monitor interrupted by an error.
20 Error; trigger monitor not run.


runswchl

runswchl (switch cluster channel) on UNIX, Linux, and Windows.


Purpose

The command switches or queries the cluster transmission queues associated with cluster-sender channels.


Usage notes

You must log on as an Administrator to run this command.

The command switches all the stopped or inactive cluster-sender channels that match the -c parameter, require switching, and can be switched. The command reports back on the channels that are switched, the channels that do not require switching, and the channels it cannot switch because they are not stopped or inactive.

If you set the -q parameter, the command does not perform the switch, but it provides the list of channels that would be switched.


Syntax

   
>>-runswchl-- -m-- - QmgrName--+- -c-- - *------------------+--+-----+-><
                              +- -c-- - GenericChannelName-+  +- -q-+   
                              '- -c-- - ChannelName--------'  '- -n-'   



Required parameters

-m QmgrName
The queue manager to run the command against. The queue manager must be started.
-c *
All the cluster-sender channels
-c GenericChannelName
All matching cluster-sender channels
-c ChannelName
Single cluster-sender channel.


Optional parameters

-q
Display the state of one or more channels. If you omit this parameter, the commands switches any stopped or inactive channels that require switching.
-n
When switching transmission queues, do not transfer messages from the old queue to the new transmission queue.

Note: Take care with the -n option: messages on the old transmission queue are not transferred unless you associate the transmission queue with another cluster-sender channel.


Return codes

0

The command completed successfully

10

The command completed with warnings.

20

The command completed with errors.


Examples

To display the configuration state of cluster-sender channel TO.QM2:

 RUNSWCHL -m QM1 -c TO.QM2 -q
To switch the transmission queue for cluster-sender channel TO.QM3 without moving the messages on it:

 RUNSWCHL -m QM1 -c TO.QM3 -n
To switch the transmission queue for cluster-sender channel TO.QM3 and move the messages on it:

 RUNSWCHL -m QM1 -c TO.QM3
To display the configuration state of all cluster-sender channels on QM1:

 RUNSWCHL -m QM1 -c * -q
To display the configuration state of all cluster-sender channels with a generic name of TO.*:

 RUNSWCHL -m QM1 -c TO.* -q


setmqaut

Change the authorizations to a profile, object, or class of objects. Authorizations can be granted to, or revoked from, any number of principals or groups.

For more information about authorization service components, see Installable services , Service components , and Authorization service interface .

For more information about how authorizations work, see How authorizations work .


Syntax

   
>>-setmqaut--+----------------+-- -n -- Profile------------------>
             '- -m -- QMgrName-'                  

>-- -t -- ObjectType--+------------------------+----------------->
                     '- -s -- ServiceComponent-'   

   .-------------------------.   
   V                         |   
>----+- -p -- PrincipalName-+-+---------------------------------->
     '- -g -- GroupName-----'     

   .---------------------------------------.   
   V                                       |   
>----+-| MQI authorizations |------------+-+-------------------><
     +-| Context authorizations |--------+     
     +-| Administration authorizations |-+     
     +-| Generic authorizations |--------+     
     +- +remove -------------------------+     
     '- -remove -------------------------'     

MQI authorizations

   .--------------------.   
   V                    |   
|------+- +altusr --+---+---------------------------------------|
       +- -altusr --+       
       +- +browse --+       
       +- -browse --+       
       +- +connect -+       
       +- -connect -+       
       +- +get -----+       
       +- -get -----+       
       +- +inq -----+       
       +- -inq -----+       
       +- +pub -----+       
       +- -pub -----+       
       +- +put -----+       
       +- -put -----+       
       +- +resume --+       
       +- -resume---+       
       +- +set -----+       
       +- -set -----+       
       +- +sub -----+       
       '- -sub -----'       

Context authorizations

   .--------------------.   
   V                    |   
|------+- +passall -+---+---------------------------------------|
       +- -passall -+       
       +- +passid --+       
       +- -passid --+       
       +- +setall --+       
       +- -setall --+       
       +- +setid ---+       
       '- -setid ---'       

Administration authorizations

   .------------------.   
   V                  |   
|------+- +chg ---+---+-----------------------------------------|
       +- -chg ---+       
       +- +clr ---+       
       +- -clr ---+       
       +- +crt ---+       
       +- -crt ---+       
       +- +dlt ---+       
       +- -dlt ---+       
       +- +dsp ---+       
       +- -dsp ---+       
       +- +ctrl --+       
       +- -ctrl --+       
       +- +ctrlx -+       
       '- -ctrlx -'       

Generic authorizations

   .-------------------.   
   V                   |   
|------+- +all ----+---+----------------------------------------|
       +- -all ----+       
       +- +alladm -+       
       +- -alladm -+       
       +- +allmqi -+       
       +- -allmqi -+       
       +- +none ---+       
       +- +system -+       
       '- -system -'       



Description

Use setmqaut both to grant an authorization, that is, give a principal or user group permission to perform an operation, and to revoke an authorization, that is, remove the permission to perform an operation. You can specify a number of parameters:

The authorizations that can be given are categorized as follows:

Each authorization to be changed is specified in an authorization list as part of the command. Each item in the list is a string prefixed by a plus sign (+) or a minus sign (-). For example, if you include +put in the authorization list, you grant authority to issue MQPUT calls against a queue. Alternatively, if you include -put in the authorization list, you revoke the authority to issue MQPUT calls.

You can specify any number of principals, user groups, and authorizations in a single command, but you must specify at least one principal or user group.

If a principal is a member of more than one user group, the principal effectively has the combined authorities of all those user groups. On Windows systems, the principal also has all the authorities that have been granted to it explicitly using the setmqaut command.

On UNIX systems, all authorities are held by user groups internally, not by principals. Granting authorities to groups has the following implications:

To alter authorizations for a cluster sender channel that has been automatically generated by a repository, see Channel definition commands .


Required parameters

-t ObjectType
The type of object for which to change authorizations.

Possible values are as follows:

-n Profile
The name of the profile for which to change authorizations. The authorizations apply to all WebSphere MQ objects with names that match the profile name specified. The profile name can be generic, using wildcard characters to specify a range of names as explained in Using OAM generic profiles on UNIX or Linux systems and Windows .

This parameter is required, unless you are changing the authorizations of a queue manager, in which case you must not include it. To change the authorizations of a queue manager use the queue manager name, for example

 setmqaut -m QMGR -t qmgr -p user1 +connect
where QMGR is the name of the queue manager and user1 is the user requesting the change.

Each class of object has authority records for each group or principal. These records have the profile name @CLASS and track the crt (create) authority common to all objects of that class. If the crt authority for any object of that class is changed then this record is updated. For example:

 profile:     @class
object type: queue entity:      test
entity type: principal
authority:   crt
This shows that members of the group test have crt authority to the class queue.


Optional parameters

-m QMgrName
The name of the queue manager of the object for which to change authorizations. The name can contain up to 48 characters.

This parameter is optional if you are changing the authorizations of your default queue manager.

-p PrincipalName
The name of the principal for which to change authorizations.

For WebSphere MQ for Windows only, the name of the principal can optionally include a domain name, specified in the following format:

 Userid@domain

For more information about including domain names on the name of a principal, see Principals and groups .

You must have at least one principal or group.

-g GroupName
The name of the user group for which to change authorizations. You can specify more than one group name, but each name must be prefixed by the -g flag.

For WebSphere MQ for Windows only, the group name can optionally include a domain name, specified in the following formats:

 GroupName@domain
domain\GroupName
-s ServiceComponent
The name of the authorization service to which the authorizations apply (if your system supports installable authorization services). This parameter is optional; if you omit it, the authorization update is made to the first installable component for the service.
+remove or -remove
Remove all the authorities from WebSphere MQ objects that match the specified profile.

This option cannot be used with the option -t qmgr.

Authorizations
The authorizations to be granted or revoked. Each item in the list is prefixed by a plus sign (+) or a minus sign (-). The plus sign indicates that authority is to be granted. The minus sign indicates that authority is to be revoked.

For example, to grant authority to issue MQPUT calls, specify +put in the list. To revoke the authority to issue MQPUT calls, specify -put. be given to the different object types.

Specifying authorities for different object types.

Cross-tabulation of object types versus authority. Each cell contains whether the authority can be given to the object type.

Authority Queue Process Queue manager Remote queue manager name Namelist Topic Auth info Clntconn Channel Listener Service Comminfo
all 1 Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
alladm 2 Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
allmqi 3 Yes Yes Yes Yes Yes Yes Yes No No No No No
none Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes Yes
altusr No No Yes No No No No No No No No No
browse Yes No No No No No No No No No No No
chg Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
clr Yes No No No No Yes No No No No No No
connect No No Yes No No No No No No No No No
crt Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
ctrl No No No No No Yes No No Yes Yes Yes No
ctrlx No No No No No No No No Yes No No No
dlt Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
dsp Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes
get Yes No No No No No No No No No No No
pub No No No No No Yes No No No No No No
put Yes No No Yes No No No No No No No No
inq Yes Yes Yes No Yes No Yes No No No No No
passall Yes No No No No No No No No No No No
passid Yes No No No No No No No No No No No
resume No No No No No Yes No No No No No No
set Yes Yes Yes No No No No No No No No No
setall Yes No Yes No No No No No No No No No
setid Yes No Yes No No Yes No No No No No No
sub No No No No No Yes No No No No No No
system No No Yes No No No No No No No No No

Note:

  1. all authority is equivalent to the union of the authorities alladm, allmqi, and system appropriate to the object type.
  2. alladm authority is equivalent to the union of the individual authorities chg, clr, dlt, dsp, ctrl, and ctrlx appropriate to the object type. crt authority is not included in the subset alladm.
  3. allmqi authority is equivalent to the union of the individual authorities altusr, browse, connect, get, inq, pub, put, resume, set, and sub appropriate to the object type.


Return codes

Return code Explanation
0 Successful operation
26 Queue manager running as a standby instance.
36 Invalid arguments supplied
40 Queue manager not available
49 Queue manager stopping
58 Inconsistent use of installations detected
69 Storage not available
71 Unexpected error
72 Queue manager name error
133 Unknown object name
145 Unexpected object name
146 Object name missing
147 Object type missing
148 Invalid object type
149 Entity name missing
150 Authorization specification missing
151 Invalid authorization specification


Examples

  1. This example shows a command that specifies that the object on which authorizations are being given is the queue orange.queue on queue manager saturn.queue.manager.

     setmqaut -m saturn.queue.manager -n orange.queue -t queue          -g tango +inq +alladm
    
    The authorizations are given to a user group called tango, and the associated authorization list specifies that the user group can:

    • Issue MQINQ calls
    • Perform all administration operations on that object

  2. In this example, the authorization list specifies that a user group called foxy:

    • Cannot issue any MQI calls to the specified queue
    • Can perform all administration operations on the specified queue

     setmqaut -m saturn.queue.manager -n orange.queue -t queue          -g foxy -allmqi +alladm
    
  3. This example gives user1 full access to all queues with names beginning a.b. on queue manager qmgr1. The profile applies to any object with a name that matches the profile.

     setmqaut -m qmgr1 -n a.b.* -t q -p user1 +all
    
  4. This example deletes the specified profile.

     setmqaut -m qmgr1 -n a.b.* -t q -p user1 -remove
    
  5. This example creates a profile with no authority.

     setmqaut -m qmgr1 -n a.b.* -t q -p user1 +none
    


Authorizations for MQI calls

Note: If you open a queue for multiple options, you must be authorized for each option.


Authorizations for context

Note: To use setid or setall authority authorizations must be granted on both the appropriate queue object and also on the queue manager object.


Authorizations for commands


Authorizations for generic operations


setmqcrl

Administer CRL (certificate revocation list) LDAP definitions in an Active Directory (Windows only).


Purpose

Note: The setmqcrl command applies to WebSphere MQ for Windows only.

Use the setmqcrl command to configure and administer support for publishing CRL (certificate revocation list) LDAP definitions in an Active Directory.

A domain administrator must use this command, or setmqscp, initially to prepare the Active Directory for WebSphere MQ usage and to grant WebSphere MQ users and administrators the relevant authorities to access and update the WebSphere MQ Active Directory objects. You can also use the setmqcrl command to display all the currently configured CRL server definitions available on the Active Directory, that is, those definitions referred to by the queue manager's CRL namelist.

The only types of CRL servers supported are LDAP servers.


Syntax

   
>>-setmqcrl--+--------------------------+----------------------->
             '- -a --+----------------+-'   
                     '- -m -- QMgrName-'     

>--+--------------------------+--+------+----------------------><
   '- -r --+----------------+-'  '- -d -'   
           '- -m -- QMgrName-'               



Optional parameters

You must specify one of -a (add), -r (remove) or -d (display).

-a
Adds the WebSphere MQ MQI client connections Active Directory container, if it does not already exist. You must be a user with the appropriate privileges to create subcontainers in the System container of your domain. The WebSphere MQ folder is called CN=IBM-MQClientConnections. Do not delete this folder in any other way than by using the setmqscp command.
-d
Displays the WebSphere MQ CRL server definitions.
-r
Removes the WebSphere MQ CRL server definitions.
-m [ * | qmgr ]
Modifies the specified parameter (-a or -r) so that only the specified queue manager is affected. You must include this option with the -a parameter.

* | qmgr

* specifies that all queue managers are affected. This enables you to migrate a specific WebSphere MQ CRL server definitions file from one queue manager alone.


Examples

The following command creates the IBM-MQClientConnections folder and allocates the required permissions to WebSphere MQ administrators for the folder, and to child objects created subsequently. (In this, it is functionally equivalent to setmqscp -a.)

 setmqcrl -a

The following command migrates existing CRL server definitions from a local queue manager, Paint.queue.manager, to the Active Directory, deleting any other CRL definitions from the Active Directory first :

 setmqcrl -a -m Paint.queue.manager


setmqenv

Use the setmqenv to set up the WebSphere MQ environment, on UNIX, Linux, and Windows.


Purpose

You can use the setmqenv script to automatically set up the environment for use with an installation of WebSphere MQ. Alternatively, you can use the crtmqenv command to create a list of environment variables and values to manually set each environment variable for your system; see crtmqenv for more information.

You can specify which installation the environment is set up for by specifying a queue manager name, an installation name, or an installation path. You can also set up the environment for the installation that issues the setmqenv command by issuing the command with the -s parameter.

The setmqenv command sets the following environment variables, appropriate to your system:

On UNIX and Linux systems, if the -l or -k flag is specified, the LIBPATH environment variable is set on AIX, and the LD_LIBRARY_PATH environment variable is set on HP-UX, Linux, and Solaris.


Usage notes


Syntax

   
>>-setmqenv--+- -m - QMgrName---------+--+-----+--+-----------+-><
             +- -n - InstallationName-+  +- -k +  '- -x - Mode-'   
             +- -p - InstallationPath-+  '- -l '                  
             +- -r ------------------+                           
             '- -s ------------------'                           



Optional Parameters

-m QMgrName
Set the environment for the installation associated with the queue manager QMgrName.
-n InstallationName
Set the environment for the installation named InstallationName.
-p InstallationPath
Set the environment for the installation in the path InstallationPath.
-r
Remove all installations from the environment.
-s
Set the environment for the installation that issued the setmqenv command.
-k
UNIX and Linux only.
Include the LD_LIBRARY_PATH or LIBPATH environment variable in the environment, adding the path to the WebSphere MQ libraries at the start of the current LD_LIBRARY_PATH or LIBPATH variable.
-l
UNIX and Linux only.
Include the LD_LIBRARY_PATH or LIBPATH environment variable in the environment, adding the path to the WebSphere MQ libraries at the end of the current LD_LIBRARY_PATH or LIBPATH variable.
-x Mode
Mode can take the value 32 or 64.
Create a 32-bit or 64-bit environment. If this parameter is not specified, the environment matches that of the queue manager or installation specified in the command.
Any attempt to display a 64-bit environment with a 32-bit installation fails.


Return codes

Return code Description
0 Command completed normally.
10 Command completed with unexpected results.
20 An error occurred during processing.


Examples

The following examples assume that a copy of WebSphere MQ is installed in the /opt/mqm directory on a UNIX or Linux system.

Note: The period character (.) character used at the beginning of each command makes the setmqenv script run in the current shell. Therefore, the environment changes made by the setmqenv script are applied to the current shell. Without the period character (.), the environment variables are changed in another shell, and the changes are not applied to the shell from which the command is issued.

The following example assumes that a copy of WebSphere MQ is installed in C:\Program Files\IBM\WebSphere MQ on a Windows system.

This command sets up the environment for an installation called Installation1:

 "C:\Program Files\IBM\WebSphere MQ\bin\setmqenv.cmd" -n Installation1


setmqinst

Set WebSphere MQ installations, on UNIX, Linux, and Windows.


Purpose

You can use the setmqinst command to change the installation description of an installation, or to set or unset an installation as the primary installation. To change the primary installation, you must unset the current primary installation before you can set a new primary installation. This command updates information contained in the mqinst.ini file.

After unsetting the primary installation, the setmqinst command will not be available unless you specify the full path or have an appropriate installation directory on your PATH (or equivalent). The default path in a system standard location will have been deleted.

File mqinst.ini contains information about all WebSphere MQ installations on a system. For more information about mqinst.ini, see Installation configuration file, mqinst.ini .

On UNIX or Linux systems, you must run this command as root. On Windows systems, you must run this command as a member of the Administrators group. The command does not have to be run from the installation you are modifying.


Syntax

   
>>-setmqinst--| Action |--| Installation |---------------------><

Action

|--+- -i------------------+-------------------------------------|
   +- -x------------------+   
   '- -d-- DescriptiveText-'   

Installation

|--+- -p - InstallationPath----------------------------+---------|
   +- -n - InstallationName----------------------------+   
   |                                              (1) |   
   +- -p - InstallationPath-- -n-- InstallationName-----+   
   |                                              (1) |   
   '- -n - InstallationName-- -p - InstallationPath-----'   


Notes:

  1. When specified together, the installation name and installation path must refer to the same installation.


Parameters

-d DescriptiveText
Text that describes the installation.

The text can be up to 64 single-byte characters, or 32 double-byte characters. The default value is all blanks. You must use double quotation marks around the text if it contains spaces.

-i
Set this installation as the primary installation.
-x
Unset this installation as the primary installation.
-n InstallationName
The name of the installation to modify.
-p InstallationPath
The path of the installation to modify. You must use double quotation marks around the path if it contains spaces


Return codes

Return code Description
0 Entry set without error
36 Invalid arguments supplied
37 Descriptive text was in error
44 Entry does not exist
59 Invalid installation specified
71 Unexpected error
89 ini file error
96 Could not lock ini file
98 Insufficient authority to access ini file
131 Resource problem


Examples

  1. This command sets the installation with the name of myInstallation as the primary installation:

     setmqinst -i -n myInstallation
    
  2. This command sets the installation with an installation path of /opt/myInstallation as the primary installation:

     setmqinst -i -p /opt/myInstallation
    
  3. This command unsets the installation named myInstallation as the primary installation:

     setmqinst -x -n myInstallation
    
  4. This command unsets the installation with an installation path of /opt/myInstallation as the primary installation:

     setmqinst -x -p /opt/myInstallation
    
  5. This command sets the descriptive text for the installation named myInstallation:

     setmqinst -d "My installation" -n myInstallation
    
    The descriptive text is enclosed in quotation marks as it contains spaces.


setmqm

Set the associated installation of a queue manager.


Purpose

Use the setmqm command to set the associated WebSphere MQ installation of a queue manager. The queue manager can then be administered using only the commands of the associated installation. For example, when a queue manager is started with strmqm, it must be the strmqm command of the installation that was specified by the setmqm command.

For more information about using this command, including information about when to use it, see Associating a queue manager with an installation .

This command is only applicable to UNIX, Linux and Windows.


Usage notes


Syntax

   
>>-setmqm-- -m-- QMgrName-- -n-- InstallationName----------------><



Required Parameters

-m QMgrName
The name of the queue manager to set the associated installation for.
-n InstallationName
The name of the installation that the queue manager is to be associated with. The installation name is not case-sensitive.


Return codes

Return code Description
0 Queue manager set to an installation without error
5 Queue manager running
36 Invalid arguments supplied
59 Invalid installation specified
60 Command not executed from the installation named by the -n parameter
61 Invalid installation name for this queue manager
69 Resource problem
71 Unexpected error
72 Queue manager name error
119 User not authorized


Examples

  1. This command associates a queue manager QMGR1, with an installation with the installation name of myInstallation.

     MQ_INSTALLATION_PATH/bin/setmqm -m QMGR1 -n myInstallation
    


setmqspl

Use the setmqspl command to define a new security policy, alter an already existing one, or remove an existing policy.


Syntax

   
>>-setmqspl-- -m - QMgrName-------------------------------------->

>-- -p - PolicyName--+-| Policy definition |-+------------------><
                    '- -remove--------------'   

Policy definition 
                     .----------------------.   
        .-NONE----.  V                      |   
|-- -e -+---------+----+------------------+-+------------------->
        |     (1) |    '- -r - RecipientDN-'     
        +-RC2-----+                             
        +-DES-----+                             
        +-3DES----+                             
        +-AES128--+                             
        '-AES256--'                             

   .-----------------------.                                
   V                       |       .-NONE---.       .-0-.   
>----+-------------------+-+-- -s -+--------+-- -t -+---+-------|
     |               (2) |         +-MD5----+       '-1-'   
     '- -a - AuthorDN-----'         +-SHA1---+               
                                   +-SHA256-+               
                                   +-SHA384-+               
                                   '-SHA512-'               


Notes:

  1. If an encryption algorithm is selected, a recipient DN must also be provided.
  2. If an author DN is provided, a signing algorithm must also be selected.

setmqspl command flags.

Command flag Explanation
-m Queue manager name.

This flag is mandatory for all actions on security policies.

-p Policy name.

Set the policy name to the name of the queue you wish the policy to apply to.

-s Digital signature algorithm.

WebSphere MQ Advanced Message Security supports the following values: MD5, SHA1, SHA256, SHA384, and SHA512. All must be in uppercase. The default value is NONE

  • For the SHA384 and SHA512 cryptographic hash functions, keys used for signing must be longer than 768 bits.
  • Encryption algorithms' name must be in uppercase

-e Digital encryption algorithm.

WebSphere MQ Advanced Message Security supports the following encryption algorithms: RC2, DES, 3DES, AES128, AES256. The default value is NONE.

Encryption algorithms' name must be in uppercase

-r Message recipient's distinguished name (DN) (certificate of a DN provided is used to encrypt a given message). Recipients can be specified only if encryption algorithm is different from NONE. Multiple recipients can be included for a message. Each DN must be provided with a separate -r flag.

  • DN attribute names must be in uppercase.
  • Commas must be used as a name separators.
  • To avoid command interpreter errors, place quotation marks around the DNs.

For example:

 -r "CN=alice, O=ibm, C=US"
-a Signature DN that is validated during message retrieval. Only messages signed by a user with a DN provided are accepted during the retrieval. Signature DNs can be specified only if the signature algorithm is different from NONE. Multiple authors can be included. Each author needs to have a separate -a flag.

DN attribute name must be in uppercase.

-t Toleration flag that indicates whether a policy that is associated with a queue can be ignored when an attempt to retrieve a message from the queue involves a message with no security policy set. Valid values include:

Toleration is optional and facilitates staged roll-out, where policies were applied to queues but those queues may already contain messages that have no policy, or still receive messages from remote systems that do not have the security policy set.

-remove Delete policy.

If specified, only the -p flag remains valid.


setmqprd

Enroll a WebSphere MQ production license.

A license is normally enrolled as part of the installation process.

Note: You must have the appropriate privileges to run this command on your system. UNIX requires root access, and Windows with UAC (User Account Control) requires Administrator access to run this command.


Syntax

   
>>-setmqprd-- LicenseFile---------------------------------------><



Required parameters

LicenseFile
Specifies the fully-qualified name of the production license certificate file.

The full license file is amqpcert.lic. On UNIX and Linux, it is in the /MediaRoot/licenses directory on the installation media. On Windows it is in the \MediaRoot\licenses directory on the installation media. It is installed into the bin directory on the WebSphere MQ installation path.


Trial license conversion

A trial license installation is identical to a production license installation, except for the count-down message that is displayed when you start a queue manager on an installation with a trial license. Parts of WebSphere MQ that are not installed on the server, such as the WebSphere MQ MQI client, continue to work after the expiry of the trial license. You do not need to run setmqprd to enroll them with a production license.

When a trial license expires, you can still uninstall WebSphere MQ. You can also reinstall WebSphere MQ with a full production license.

Run setmqprd to enroll a production license after installing and using a installation with a trial license.


setmqscp

Publish client connection channel definitions in an Active Directory (Windows only).


Purpose

Note: The setmqscp command applies to WebSphere MQ for Windows only.

Use the setmqscp command to configure and administer support for publishing client connection channel definitions in an Active Directory.

Initially, this command is used by a domain administrator to:

You can also use the setmqscp command to display all the currently configured client connection channel definitions available on the Active Directory.


Syntax

   
>>-setmqscp--+--------------------------+----------------------->
             '- -a --+----------------+-'   
                     '- -m -- QMgrName-'     

>--+--------------------------+--+------+----------------------><
   '- -r --+----------------+-'  '- -d -'   
           '- -m -- QMgrName-'               



Optional parameters

You must specify one of -a (add), -r (remove) or -d (display).

-a
Adds the WebSphere MQ MQI client connections Active Directory container, if it does not already exist. You must be a user with the appropriate privileges to create subcontainers in the System container of your domain. The WebSphere MQ folder is called CN=IBM-MQClientConnections. Do not delete this folder in any other way than by using the setmqscp -r command.
-d
Displays the service connection points.
-r
Removes the service connection points. If you omit -m, and no client connection definitions exist in the IBM-MQClientConnections folder, the folder itself is removed from the Active Directory.
-m [ * | qmgr ]
Modifies the specified parameter (-a or -r) so that only the specified queue manager is affected.

* | qmgr

* specifies that all queue managers are affected. This enables you to migrate a specific client connection table file from one queue manager alone, if required.


Examples

The following command creates the IBM-MQClientConnections folder and allocates the required permissions to WebSphere MQ administrators for the folder, and to child objects created subsequently:

 setmqscp -a

The following command migrates existing client connection definitions from a local queue manager, Paint.queue.manager, to the Active Directory:

 setmqscp -a -m Paint.queue.manager

The following command migrates all client connection definitions on the local server to the Active Directory:

 setmqscp -a -m *


strmqcfg

Start WebSphere MQ Explorer (Windows, Linux x86, and Linux x86-64 platforms only).


Purpose

For WebSphere MQ for Windows only, note that if you use runas to execute this command, you must define the Environment Variable APPDATA.

On Linux, to start WebSphere MQ Explorer successfully, you must be able to write a file to your home directory, and the home directory must exist.

Note: The preferred way to start WebSphere MQ Explorer on Windows and Linux systems is by using the system menu, or the MQExplorer executable file.


Syntax

The syntax of this command follows:

   
>>-strmqcfg--+------+--+------+--+------+----------------------><
             '- -c -'  '- -i -'  '- -x -'   



Optional parameters

-c
-clean is passed to Eclipse. This parameter causes Eclipse to delete any cached data used by the Eclipse runtime.
-i
-init is passed to Eclipse. This parameter causes Eclipse to discard configuration information Used by the Eclipse runtime.
-x
Output debug messages to the console.


strmqcsv

Start the command server for a queue manager.


Purpose

Use the strmqcsv command to start the command server for the specified queue manager. This enables WebSphere MQ to process commands sent to the command queue.

You must use the strmqcsv command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

If the queue manager attribute, SCMDSERV, is specified as QMGR then changing the state of the command server using strmqcsv does not effect how the queue manager acts upon the SCMDSERV attribute at the next restart.


Syntax

   
>>-strmqcsv--+-----+--+----------+-----------------------------><
             '- -a-'  '- QMgrName-'   



Required parameters

None


Optional parameters

-a
Blocks the following PCF commands from modifying or displaying authority information:

  • Inquire authority records (MQCMD_INQUIRE_AUTH_RECS)
  • Inquire entity authority (MQCMD_INQUIRE_ENTITY_AUTH)
  • Set authority record (MQCMD_SET_AUTH_REC).
  • Delete authority record (MQCMD_DELETE_AUTH_REC).

QMgrName
The name of the queue manager on which to start the command server. If omitted, the default queue manager is used.


Return codes

Return code Description
0 Command completed normally
10 Command completed with unexpected results
20 An error occurred during processing


Examples

The following command starts a command server for queue manager earth:

 strmqcsv earth


Related commands

Command Description
endmqcsv End a command server
dspmqcsv Display the status of a command server


strmqsvc (Start IBM WebSphere MQ service)

The strmqsvc command starts the IBM WebSphere MQ service on Windows. Run the command on Windows only.


Purpose

The command starts the IBM WebSphere MQ service on Windows.

Run the command to start the service, if it has not been started automatically, or if the service has ended.

Restart the service for WebSphere MQ processes to pick up a new environment, including new security definitions.


Syntax

strmqsvc


Parameters

The strmqsvc command has no parameters.

You must set the path to the installation that contains the service. Either make the installation primary, run the setmqenv command, or run the command from the directory containing the strmqsvc binary file.


strmqm

Start a queue manager or ready it for standby operation.


Purpose

Use the strmqm command to start a queue manager.

You must use the strmqm command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command.

If a queue manager has no associated installation and there is no installation of WebSphere MQ V7.0.1 on the system, the strmqm command will associate the queue manager with the installation that issued the strmqm command.

If the queue manager startup takes more than a few seconds WebSphere MQ shows intermittent messages detailing the startup progress.


Syntax

   
>>-strmqm--+----------------------+--+-----+--+-------+--------->
           +- -c -----------------+  '- -f '  +- -si -+   
           +- -r -----------------+           '- -ss -'   
           +- -a -----------------+                       
           +- -x -----------------+                       
           '- -e CMDLEVEL=-- Level '                       

>--+------------------+--+------+--+------+--+-----------+-----><
   '- -d - Information '  '- -z -'  '- -ns-'  '-  QMgrName '   



Optional parameters

-a
Activate the specified backup queue manager. The backup queue manager is not started.

When activated, a backup queue manager can be started using the control command strmqm QMgrName. The requirement to activate a backup queue manager prevents accidental startup.

When activated, a backup queue manager can no longer be updated.

For more information about using backup queue managers, see Backing up and restoring WebSphere MQ queue manager data .

-c
Starts the queue manager, redefines the default and system objects, then stops the queue manager. Any existing system and default objects belonging to the queue manager are replaced if you specify this flag, and any non-default system object values are reset (for example, the value of MCAUSER is set to blank).

Use the crtmqm command to create the default and system objects for a queue manager.

-d Information
Specifies whether information messages are displayed. Possible values for Information follow:

The -z parameter takes precedence over this parameter.

-e CMDLEVEL=Level
Enables a command level for this queue manager, and then stops the queue manager.

The queue manager is now able to use all functions provided by the specified command level. You can start the queue manager only with an installation that supports the new command level.

This option is only valid if the current command level used by the queue manager is lower than the maximum command level supported by the installation. Specify a command level that is greater than the current command level of the queue manager and less than or equal to the maximum command level supported by the installation.

Use exactly the command level as a value for Level that is associated with the function you want to enable.

This flag cannot be specified with -a, -c, -r or -x.

-f
Use this option if you know a queue manager is not starting because its data directories are missing or corrupted.

The strmqm -f qmname command attempts to re-create the queue manager data directory and reset file permissions. If it is successful, the queue manager starts, unless the queue manager configuration information is missing. If the queue manager fails to start because the configuration information is missing, re-create the configuration information, and restart the queue manager.

In releases of WebSphere MQ earlier than 7.0.1, strmqm, with no -f option, automatically repaired missing data directories and then tried to start. This behavior has changed.

From WebSphere MQ Version 7.0.1 onwards, the default behavior of strmqm, with no -f option, is not to recover missing or corrupted data directories automatically, but to report an error, such as AMQ6235 or AMQ7001, and not start the queue manager.

You can think of the -f option as performing the recover actions that used to be performed automatically by strmqm.

The reason for the change to the behavior of strmqm is that with the support for networked file storage in WebSphere MQ Version 7.0.1, the most likely cause of missing or corrupted queue manager data directories is a configuration error that can be rectified, rather than the data directories are corrupted or irretrievably unavailable.

You must not use strmqm -f to re-create the queue manager data directories if you can restore the directories by correcting the configuration.

Possible solutions to problems with strmqm are to make the networked file storage location accessible to the queue manager, or to ensure the gid and uid of the mqm group and user ID on the server hosting the queue manager match the gid and uid of the mqm group and user ID on the server hosting the queue manager data directory.

From WebSphere MQ Version 7.0.1, if you are performing media recovery for a queue manager, then you must use the -f option to re-create the queue manager data directory.

-ns
Prevents any of the following processes from starting automatically when the queue manager starts:

-r
Updates the backup queue manager. The backup queue manager is not started.

WebSphere MQ updates the objects of the backup queue manager by reading the queue manager log and replaying updates to the object files.

For more information about using backup queue managers, see Backing up and restoring WebSphere MQ queue manager data .

-si
Interactive (manual) queue manager startup type. This option is available on WebSphere MQ for Windows only.

The queue manager runs under the logged on (interactive) user. Queue managers configured with interactive startup end when the user who started them logs off.

If you set this parameter, it overrides any startup type set previously by the crtmqm command, the amqmdain command, or the WebSphere MQ Explorer.

If you do not specify a startup type of either -si or -ss, the queue manager startup type specified on the crtmqm command is used.

-ss
Service (manual) queue manager startup type. This option is available on WebSphere MQ for Windows only.

The queue manager runs as a service. Queue managers configured with service startup continue to run even after the interactive user has logged off.

If you set this parameter, it overrides any startup type set previously by the crtmqm command, the amqmdain command, or the WebSphere MQ Explorer.

-x

Start an instance of a multi-instance queue manager on the local server, permitting it to be highly available. If an instance of the queue manager is not already running elsewhere, the queue manager starts and the instance becomes active. The active instance is ready to accept local and remote connections to the queue manager on the local server.

If a multi-instance queue manager instance is already active on a different server the new instance becomes a standby, permitting it to takeover from the active queue manager instance. While it is in standby, it cannot accept local or remote connections.

You must not start a second instance of a queue manager on the same server.

The default behavior, omitting the -x optional parameter, is to start the instance as a single instance queue manager, forbidding standby instances from being started.

-z
Suppresses error messages.

This flag is used within WebSphere MQ to suppress unwanted information messages. Because using this flag can result in loss of information, do not use it when entering commands on a command line.

This parameter takes precedence over the -d parameter.

QMgrName
The name of a local queue manager. If omitted, the default queue manager is used.


Return codes

Return code Description
0 Queue manager started
3 Queue manager being created
5 Queue manager running
16 Queue manager does not exist
23 Log not available
24 A process that was using the previous instance of the queue manager has not yet disconnected.
30 A standby instance of the queue manager started. The active instance is running elsewhere
31 The queue manager already has an active instance. The queue manager permits standby instances.
39 Invalid parameter specified
43 The queue manager already has an active instance. The queue manager does not permit standby instances.
47 The queue manager already has the maximum number of standby instances
49 Queue manager stopping
58 Inconsistent use of installations detected
62 The queue manager is associated with a different installation
69 Storage not available
71 Unexpected error
72 Queue manager name error
74 The WebSphere MQ service is not started.
91 The command level is outside the range of acceptable values.
92 The queue manager's command level is greater or equal to the specified value.
100 Log location invalid
119 User not authorized to start the queue manager


Examples

The following command starts the queue manager account:

 strmqm account 


Related commands

Command Description
crtmqm Create a queue manager
dltmqm Delete a queue manager
dspmqver Display MQ version information
endmqm End a queue manager


strmqtrc

Enable trace at a specified level of detail, or report the level of tracing in effect.


Purpose

Use the strmqtrc command to enable tracing.

You must use the strmqtrc command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command. This does not apply to a client product (for example, HP Integrity NonStop Server) because there are no queue managers from which to request direct output.


Syntax

The syntax of this command is as follows:

   
>>-strmqtrc--+----------------+--+------+----------------------->
             '- -m -- QMgrName-'  '- -e -'   

   .---------------------.                        
   V                     |                        
>----+-----------------+-+--+-----------------+----------------->
     '- -t -- TraceType-'    '- -x -- TraceType-'   

>--+---------------+--+----------------------+------------------>
   '- -l -- MaxSize-'  '- -d--+- 0----------+-'   
                             +- -1---------+     
                             '-  NumOfBytes-'     

>--+---------------+--+------------+--+------+------------------>
   '- -i -- PidTids-'  '- -p -- Apps-'  '- -s -'   

>--+--------------------+--+-------------------+---------------><
   '- -b -- StartTrigger-'  '- -c -- StopTrigger-'   



Description

The strmqtrc command enables tracing. The command has optional parameters that specify the level of tracing you want:

Each combination of parameters on an individual invocation of the command are interpreted by WebSphere MQ as having a logical AND between them. You can start the strmqtrc command multiple times, regardless of whether tracing is already enabled. If tracing is already enabled, the trace options that are in effect are modified to those specified on the most recent invocation of the command. Multiple invocations of the command, without an intervening enqmqtrc command, are interpreted by WebSphere MQ as having a logical OR between them. The maximum number of concurrent strmqtrc commands that can be in effect at one time is 16.

For the WebSphere MQ client on HP Integrity NonStop Server, you must direct your trace commands to specific processors. For example, if your client is running on processor 2 and your shell is on processor 1, initiating trace with strmqtrc <options> does not trace the client. In this case, run -cpu=2 strmqtrc is required.


Optional parameters

-m QMgrName
The name of the queue manager to trace. This parameter applies to server products only.

The following wildcards are allowed: asterisk (*), replacing zero or more characters, and question mark (?), replacing any single character. In command environments such as the UNIX shell, where the asterisk (*) and question mark (?) characters have special meaning, you must either escape the wildcard character or enclose it in quotation marks to prevent the command environment from operating on the wildcard character.

-e
Requests early tracing of all processes, making it possible to trace the creation or startup of a queue manager. If you include this flag, any process belonging to any component of any queue manager traces its early processing. The default is not to perform early tracing.

You cannot use the -e flag with the -m flag, -i flag, the -p flag, the -c flag, or the -b flag. If you try to use the -e flag with the -m flag, the -i flag, the -p flag, the -c flag, or the -b flag, then an error message is issued.

-t TraceType
The points to trace and the amount of trace detail to record. By default all trace points are enabled and a default-detail trace is generated.

Alternatively, you can supply one or more of the options in the following list. For each tracetype value you specify, including -t all, specify either -t parms or -t detail to obtain the appropriate level of trace detail. If you do not specify either -t parms or -t detail for any particular trace type, only a default-detail trace is generated for that trace type.

If you supply multiple trace types, each must have its own -t flag. You can include any number of -t flags, if each has a valid trace type associated with it.

It is not an error to specify the same trace type on multiple -t flags.

-x TraceType
The points not to trace. By default all trace points are enabled and a default-detail trace is generated. The trace points you can specify are those listed for the -t flag.

You can use the -x flag with tracetype values to exclude those entry points you do not want to record. This is useful in reducing the amount of trace produced.

If you supply multiple trace types, each must have its own -x flag. You can include any number of -x flags, if each has a valid tracetype associated with it.

-l MaxSize
The maximum size of a trace file (AMQppppp.qq.TRC) in megabytes (MB). For example, if you specify a MaxSize of 1, the size of the trace is limited to 1 MB.

When a trace file reaches the specified maximum, it is renamed to AMQppppp.qq.TRS and a new AMQppppp.qq.TRC file is started. If a previous copy of an AMQppppp.qq.TRS file exists, it is deleted.

The highest value that MaxSize can be set to is 2048 MB.

-d 0
Trace no user data.
-d -1 or all
Trace all user data.
-d NumOfBytes

  • For a communication trace; trace the specified number of bytes of data including the transmission segment header (TSH).
  • For an MQPUT or MQGET call; trace the specified number of bytes of message data held in the message buffer.
  • Values in the range 1 through 15 are not allowed.

-i PidTids
Process identifier (PID) and thread identifier (TID) to which the trace generation is restricted. You cannot use the -i flag with the -e flag. If you try to use the -i flag with the -e flag, then an error message is issued. This parameter must only be used under the guidance of IBM Service personnel.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed WebSphere MQ problem diagnostics.

-p Apps
The named processes to which the trace generation is restricted. Apps is a comma-separated list. You must specify each name in the list exactly as the program name would be displayed in the "Program Name" FDC header. Asterisk (*) or question mark (?) wildcards are allowed. You cannot use the -p flag with the -e flag. If you try to use the -p flag with the -e flag, then an error message is issued.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed WebSphere MQ problem diagnostics.

-s
Reports the tracing options that are currently in effect. You must use this parameter on its own with no other parameters.

A limited number of slots are available for storing trace commands. When all slots are in use, then no more trace commands can be accepted unless they replace an existing slot. Slot numbers are not fixed, so if the command in slot number 0 is removed, for example by an endmqtrc command, then all the other slots move up, with slot 1 becoming slot 0, for example. An asterisk (*) in a field means that no value is defined, and is equivalent to the asterisk wildcard.

An example of the output from this command is as follows:

 Listing Trace Control Array

Used slots = 2 of 15

EarlyTrace    [OFF]
TimedTrace    [OFF]
TraceUserData [0]
MaxSize       [0]
Trace Type    [1]

Slot position 1

Untriggered
Queue Manager [avocet]
Application   [*]
PID.TID       [*]
TraceOptions  [1f4ffff]
TraceInterval    [0]
Trace Start Time [0]
Trace Stop  Time [0]
Start Trigger [KN346050K]
Start Trigger [KN346080]

Slot position 2

Untriggered
Queue Manager [*]
Application   [*]
PID.TID       [*]
TraceOptions  [1fcffff]
TraceInterval    [0]
Trace Start Time [0]
Trace Stop  Time [0]
Start Trigger [KN346050K]
Start Trigger [KN346080]

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed WebSphere MQ problem diagnostics.

-b Start_Trigger
FDC probe IDs for which tracing must be turned on. Start_Trigger is a comma-separated list of FDC probe IDs. You can use asterisk (*) and question mark (?) wildcards in the specification of probe IDs. You cannot use the -b flag with the -e flag. If you try to use the -b flag with the -e flag, then an error message is issued. This parameter must only be used under the guidance of IBM Service personnel.

Start_Trigger Effect
FDC=comma-separated list of FDC probe IDs. Turns on tracing when any FDCs with the specified FDC probe IDs are generated.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed WebSphere MQ problem diagnostics.

-c Stop_Trigger
FDC probe IDs for which tracing must be turned off, or interval in seconds after which tracing must be turned off. Stop_Trigger is a comma-separated list of FDC probe IDs. You can use asterisk (*) and question mark (?) wildcards in the specification of probe IDs. This parameter should be used only under the guidance of IBM Service personnel.

Stop_Trigger Effect
FDC=comma-separated list of FDC probe IDs. Turns tracing off when any FDCs with the specified FDC probe IDs are generated.
interval=n where n is an unsigned integer between 1 and 32,000,000. Turns tracing off n seconds after it starts or, if it tracing is already enabled, turns tracing off n seconds after this instance of the command is issued.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed WebSphere MQ problem diagnostics.


Return codes

Return code Description
AMQ7024 Non-valid arguments supplied to the command.
AMQ8304 Nine concurrent traces (the maximum) already running.
58 Inconsistent use of installations detected


Examples

This command enables tracing of processing flow from common services and the local queue manager for a queue manager called QM1 in WebSphere MQ for UNIX systems. Trace data is generated at the default level of detail.

 strmqtrc -m QM1 -t csflows -t lqmflows -t parms

This command disables tracing of SSL activity on a queue manager called QM1. Other trace data is generated at the parms level of detail.

 strmqtrc -m QM1 -x ssl -t parms

This command enables high-detail tracing of the processing flow for all components:

 strmqtrc -t all -t detail

This command enables tracing when FDC KN346050 or FDC KN346080 occur on any process that is using queue manager QM1:

 strmqtrc -m QM1 -b FDC=KN346050,KN346080

This command enables tracing when FDC KN34650 occurs, and stops tracing when FDC KN346080 occurs. In both cases the FDC must occur on a process that is using queue manager QM1:

 strmqtrc -m QM1 -b FDC=KN346050 -c FDC=KN346080

The next examples use the -p and -m flags to show the following:

  1. This command enables tracing for all threads that result from any executing process called amqxxx.exe:

     strmqtrc -p amqxxx.exe
    
  2.   

    • If you start the following command after the command in step 1, without an intervening endmqtrc command, then tracing is limited to all threads that result from any executing process called amqxxx.exe and that are using queue manager QM2:

       strmqtrc -p amqxxx.exe -m QM2
      
    • If you start the following command after the command in step 1, without an intervening endmqtrc command, then tracing is limited to all processes and threads that result from executing amqxxx.exe or that are using queue manager QM2:

       strmqtrc -m QM2
      


Related commands

Command Description
dspmqtrc Display formatted trace output
endmqtrc End trace


Comparing command sets

The tables in this section compare the facilities available from the different administration command sets, and state whether you can perform each function from within the WebSphere MQ Explorer.

Note: The following tables do not apply to WebSphere MQ for z/OS or WebSphere MQ for IBM i.


Queue manager commands

A table of queue manager commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Queue manager commands

Description PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Queue Manager Change Queue Manager ALTER QMGR No equivalent Yes
Create Queue Manager No equivalent No equivalent crtmqm Yes
Delete Queue Manager No equivalent No equivalent dltmqm Yes
Inquire Queue Manager Inquire Queue Manager DISPLAY QMGR No equivalent Yes
Inquire Queue Manager Status Inquire Queue Manager Status DISPLAY QMSTATUS dspmq Yes
Ping Queue Manager Ping Queue Manager PING QMGR No equivalent No
Refresh Queue Manager No equivalent REFRESH QMGR No equivalent No
Reset Queue Manager Reset Queue Manager RESET QMGR No equivalent No
Start Queue Manager No equivalent No equivalent strmqm Yes
Stop Queue Manager No equivalent No equivalent endmqm Yes


Command server commands

A table of command server commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Commands for command server administration

Description PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Display command server Inquire Queue Manager Status DISPLAY QMSTATUS dspmqcsv Yes
Start command server Change Queue Manager ALTER QMGR strmqcsv Yes
Stop command server No equivalent No equivalent endmqcsv Yes


Authority commands

A table of authority commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Commands for authority administration

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Delete authority record DELETE AUTHREC setmqaut Yes
Inquire authority records DISPLAY AUTHREC dmpmqaut Yes
Inquire entity authority DISPLAY ENTAUTH dspmqaut Yes
Refresh Security REFRESH SECURITY No equivalent Yes
Set authority record SET AUTHREC setmqaut Yes


Cluster commands

A table of cluster commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Cluster commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Inquire Cluster Queue Manager DISPLAY CLUSQMGR No equivalent Yes
Refresh Cluster REFRESH CLUSTER No equivalent Yes
Reset Cluster RESET CLUSTER No equivalent No
Resume Queue Manager Cluster RESUME QMGR No equivalent Yes
Suspend Queue Manager Cluster SUSPEND QMGR No equivalent Yes


Authentication information commands

A table of authentication information commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Authentication information commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Authentication Information Object ALTER AUTHINFO No equivalent Yes
Copy Authentication Information Object DEFINE AUTHINFO(x) LIKE(y) No equivalent Yes
Create Authentication Information Object DEFINE AUTHINFO No equivalent Yes
Delete Authentication Information Object DELETE AUTHINFO No equivalent Yes
Inquire Authentication Information Object DISPLAY AUTHINFO No equivalent Yes


Channel commands

A table of channel commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Channel commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Channel ALTER CHANNEL No equivalent Yes
Copy Channel DEFINE CHANNEL(x) LIKE(y) No equivalent Yes
Create Channel DEFINE CHANNEL No equivalent Yes
Delete Channel DELETE CHANNEL No equivalent Yes
Inquire Channel DISPLAY CHANNEL No equivalent Yes
Inquire Channel Names DISPLAY CHANNEL No equivalent Yes
Inquire Channel Status DISPLAY CHSTATUS No equivalent Yes
Ping Channel PING CHANNEL No equivalent Yes
Purge Channel PURGE CHANNEL No equivalent Yes
Reset Channel RESET CHANNEL No equivalent Yes
Resolve Channel RESOLVE CHANNEL No equivalent Yes
Start Channel START CHANNEL runmqchl Yes
Start Channel Initiator START CHINIT runmqchi No
Stop Channel STOP CHANNEL No equivalent Yes


Listener commands

A table of listener commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Listener commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Listener ALTER LISTENER No equivalent Yes
Copy Listener DEFINE LISTENER(x) LIKE(y) No equivalent Yes
Create Listener DEFINE LISTENER No equivalent Yes
Delete Listener DELETE LISTENER No equivalent Yes
Inquire Listener DISPLAY LISTENER No equivalent Yes
Inquire Listener Status DISPLAY LSSTATUS No equivalent Yes
Start Channel Listener START LISTENER 1 runmqlsr Yes
Stop Listener STOP LISTENER endmqlsr 2 Yes

Notes:

  1. Used with listener objects only
  2. Stops all active listeners


Namelist commands

A table of namelist commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Namelist commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Namelist ALTER NAMELIST No equivalent Yes
Copy Namelist DEFINE NAMELIST(x) LIKE(y) No equivalent Yes
Create Namelist DEFINE NAMELIST No equivalent Yes
Delete Namelist DELETE NAMELIST No equivalent Yes
Inquire Namelist DISPLAY NAMELIST No equivalent Yes
Inquire Namelist Names DISPLAY NAMELIST No equivalent Yes


Process commands

A table of process commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Process commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Process ALTER PROCESS No equivalent Yes
Copy Process DEFINE PROCESS(x) LIKE(y) No equivalent Yes
Create Process DEFINE PROCESS No equivalent Yes
Delete Process DELETE PROCESS No equivalent Yes
Inquire Process DISPLAY PROCESS No equivalent Yes
Inquire Process Names DISPLAY PROCESS No equivalent Yes


Queue commands

A table of queue commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Queue commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Queue

ALTER QLOCAL
ALTER QALIAS
ALTER QMODEL
ALTER QREMOTE

No equivalent Yes
Clear Queue CLEAR QLOCAL No equivalent Yes
Copy Queue

DEFINE QLOCAL(x) LIKE(y)
DEFINE QALIAS(x) LIKE(y)
DEFINE QMODEL(x) LIKE(y)
DEFINE QREMOTE(x) LIKE(y)

No equivalent Yes
Create Queue

DEFINE QLOCAL
DEFINE QALIAS
DEFINE QMODEL
DEFINE QREMOTE

No equivalent Yes
Delete Queue

DELETE QLOCAL
DELETE QALIAS
DELETE QMODEL
DELETE QREMOTE

No equivalent Yes
Inquire Queue DISPLAY QUEUE No equivalent Yes
Inquire Queue Names DISPLAY QUEUE No equivalent Yes
Inquire Queue Status DISPLAY QSTATUS No equivalent Yes
Reset Queue Statistics No equivalent No equivalent No


Service commands

A table of service commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Service commands

PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Change Service ALTER SERVICE No equivalent Yes
Copy Service DEFINE SERVICE(x) LIKE(y) No equivalent Yes
Create Service DEFINE SERVICE No equivalent Yes
Delete Service DELETE SERVICE No equivalent Yes
Inquire Service DISPLAY SERVICE No equivalent Yes
Inquire Service Status DISPLAY SVSTATUS No equivalent Yes
Start Service START SERVICE No equivalent Yes
Stop Service STOP SERVICE No equivalent Yes


Other commands

A table of other commands, showing the command description, and its PCF command, MQSC command, control command equivalents, and WebSphere MQ Explorer equivalents, if available.

Other commands

Description PCF command MQSC command Control command WebSphere MQ Explorer equivalent?
Create conversion exit No equivalent No equivalent crtmqcvx No
Display files used by objects No equivalent No equivalent dspmqfls No
Display formatted trace No equivalent No equivalent dspmqtrc 1 No
Display version information No equivalent No equivalent dspmqver No
Display transactions No equivalent No equivalent dspmqtrn No
Dump log No equivalent No equivalent dmpmqlog No
Dump MQ Configuration No equivalent No equivalent dmpmqcfg No
End trace No equivalent No equivalent endmqtrc Yes
Escape Escape No equivalent No equivalent No
Record media image No equivalent No equivalent rcdmqimg No
Re-create media object No equivalent No equivalent rcrmqobj No
Resolve transactions No equivalent No equivalent rsvmqtrn No
Run client trigger monitor No equivalent No equivalent runmqtmc No
Run dead-letter queue handler No equivalent No equivalent runmqdlq No
Run MQSC commands No equivalent No equivalent runmqsc No
Run trigger monitor No equivalent No equivalent runmqtrm No
Set service connection points No equivalent No equivalent setmqscp 2 No
Start WebSphere MQ trace No equivalent No equivalent strmqtrc Yes
WebSphere MQ Services control No equivalent No equivalent amqmdain 2 No

Notes:

  1. Not supported on WebSphere MQ for Windows.
  2. Supported by WebSphere MQ for Windows only.


Managing keys and certificates

Use the runmqckm command (Windows and UNIX systems) to manage keys, certificates, and certificate requests.

The runmqckm command

The runmqckm command is available on Windows and UNIX systems.

The runmqckm command provides functions that are similar to those of iKeyman, described in Security .

Use the runmqckm command to do the following:


Preparing to use the runmqckm and runmqakm commands

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

To run the runmqckm command line interfaces, ensure that the systems environment variables are correctly configured. For primary installations of WebSphere MQ v7.1, you can run the setmqinst command. For further information on this command please see setmqinst


runmqckm, and runmqakm commands

This section describes the runmqckm, and runmqakm commands according to the object of the command.

An overview of the main differences between the two commands:

Each command specifies at least one object. Commands for PKCS #11 device operations might specify additional objects. Commands for key database, certificate, and certificate request objects also specify an action. The object can be one of the following:

-keydb

Actions apply to a key database

-cert

Actions apply to a certificate

-certreq

Actions apply to a certificate request

-help

Displays help

-version

Displays version information

The following subtopics describe the actions that you can take on key database, certificate, and certificate request objects; See runmqckm and runmqakm options for a description of the options on these commands.


Commands for a CMS key database only

You can use the runmqckm, and runmqakm commands to manage keys and certificates for a CMS key database.

-keydb -changepw

Change the password for a CMS key database:

 -keydb -changepw -db filename -pw password -new_pw new_password 
    
-stash

-keydb -create

Create a CMS key database:

 -keydb -create -db filename -pw password -type cms -expire days -stash

-keydb -stashpw

Stash the password of a CMS key database into a file:

 -keydb -stashpw -db filename -pw password

-cert -getdefault

Get the default personal certificate:

 -cert -getdefault -db filename -pw password

-cert -modify

Modify a certificate.

Note: Currently, the only field that can be modified is the Certificate Trust field.

 -cert -modify -db filename -pw password -label label 
    -trust enable | disable

-cert -setdefault

Set the default personal certificate:

 -cert -setdefault -db filename -pw password -label label


Command for CMS or PKCS #12 key databases

You can use the runmqckm, and runmqakm commands to manage keys and certificates for a CMS key database or PKCS #12 key database.

Note: WebSphere MQ does not support SHA-3 or SHA-5 algorithms. You can use the digital signature algorithm names SHA384WithRSA and SHA512WithRSA because both algorithms are members of the SHA-2 family.

The digital signature algorithm names SHA3WithRSA and SHA5WithRSA are deprecated because they are an abbreviated form of SHA384WithRSA and SHA512WithRSA respectively.

-keydb -changepw

Change the password for a key database:

 -keydb -changepw -db filename -pw password -new_pw new_password -expire days

-keydb -convert

convert the key database from one format to another:

 -keydb -convert -db filename -pw password
    -old_format cms | pkcs12 -new_format cms

-keydb -create

Create a key database:

 -keydb -create -db filename -pw password -type cms
 | pkcs12

-keydb -delete

Delete a key database:

 -keydb -delete -db filename -pw password

-keydb -list

List currently-supported types of key database:

 -keydb -list 

-cert -add

Add a certificate from a file into a key database:

 -cert -add -db filename -pw password -label label
 -file filename
    -format ascii | binary

-cert -create

Create a self-signed certificate:

 -cert -create -db filename -pw password -label label
 -dn distinguished_name
    -size 1024 | 512 -x509version 3 | 1
 | 2
    -expire days -sig_alg MD2_WITH_RSA | MD2WithRSA
 | 
                               MD5_WITH_RSA | MD5WithRSA
 | 
                               SHA1WithDSA | SHA1WithRSA
 |
                               SHA256_WITH_RSA | SHA256WithRSA
 | 
                               SHA2WithRSA | SHA384_WITH_RSA
 | 
                               SHA384WithRSA |  SHA512_WITH_RSA
 |
                               SHA512WithRSA | SHA_WITH_DSA 
 |
                               SHA_WITH_RSA | SHAWithDSA
 |
                               SHAWithRSA     

-cert -delete

Delete a certificate:

 -cert -delete -db filename -pw password -label label

-cert -details

List the detailed information for a specific certificate:

 -cert -details -db filename -pw password -label label

-cert -export

Export a personal certificate and its associated private key from a key database into a PKCS #12 file, or to another key database:

 -cert -export -db filename -pw password -label label
 -type cms | pkcs12
    -target filename -target_pw password -target_type cms | pkcs12   

-cert -extract

Extract a certificate from a key database:

 -cert -extract -db filename -pw password -label label
 -target filename
    -format ascii | binary

-cert -import

Import a personal certificate from a key database:

 -cert -import -file filename -pw password -type pkcs12 -target filename
        -target_pw password -target_type cms -label label

The -label option is required and specifies the label of the certificate that is to be imported from the source key database.

The -new_label option is optional and allows the imported certificate to be given a different label in the target key database from the label in the source database.

-cert -list

List all certificates in a key database:

 -cert -list all | personal | CA 
    -db filename -pw password

-cert -receive

Receive a certificate from a file:

 -cert -receive -file filename -db filename -pw password
 
    -format ascii | binary -default_cert yes | no

-cert -sign

Sign a certificate:

 -cert -sign -db filename -file filename  -pw password
   -label label -target filename
   -format ascii | binary -expire days
   -sig_alg MD2_WITH_RSA | MD2WithRSA | MD5_WITH_RSA
 |
            MD5WithRSA | SHA1WithDSA | SHA1WithRSA
 |
            SHA256_WITH_RSA | SHA256WithRSA | 
            SHA2WithRSA | SHA384_WITH_RSA | 
            SHA384WithRSA |  SHA512_WITH_RSA |
            SHA512WithRSA | SHA_WITH_DSA  |
            SHA_WITH_RSA | SHAWithDSA |
            SHAWithRSA     

-certreq -create

Create a certificate request:

 -certreq -create -db filename -pw password
    -label label -dn distinguished_name
    -size 1024 | 512 -file filename
    -sig_alg MD2_WITH_RSA | MD2WithRSA | 
             MD5_WITH_RSA | MD5WithRSA | 
             SHA1WithDSA | SHA1WithRSA |
             SHA256_WITH_RSA | SHA256WithRSA | 
             SHA2WithRSA | SHA384_WITH_RSA | 
             SHA384WithRSA |  SHA512_WITH_RSA |
             SHA512WithRSA | SHA_WITH_DSA  |
             SHA_WITH_RSA | SHAWithDSA |
             SHAWithRSA     

-certreq -delete

Delete a certificate request:

 -certreq -delete -db filename -pw password -label label

-certreq -details

List the detailed information of a specific certificate request:

 -certreq -details -db filename -pw password -label label

List the detailed information about a certificate request and show the full certificate request:

 -certreq -details -showOID -db filename 
    -pw password -label label

-certreq -extract

Extract a certificate request from a certificate request database into a file:

 -certreq -extract -db filename -pw password
     -label label -target filename

-certreq -list

List all certificate requests in the certificate request database:

 -certreq -list -db filename -pw password

-certreq -recreate

Re-create a certificate request:

 -certreq -recreate -db filename -pw password
    -label label -target filename     


Commands for cryptographic device operations

You can use the runmqckm, and runmqakm commands to manage keys and certificates for cryptographic device operations.

Note: WebSphere MQ does not support SHA-3 or SHA-5 algorithms. You can use the digital signature algorithm names SHA384WithRSA and SHA512WithRSA because both algorithms are members of the SHA-2 family.

The digital signature algorithm names SHA3WithRSA and SHA5WithRSA are deprecated because they are an abbreviated form of SHA384WithRSA and SHA512WithRSA respectively.

-keydb -changepw

Change the password for a cryptographic device:

 -keydb -changepw -crypto module_name -tokenlabel token_label
    -pw password -new_pw new_password 

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-keydb -list

List currently-supported types of key database:

 -keydb -list 

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-cert -add

Add a certificate from a file to a cryptographic device:

 -cert -add -crypto module_name -tokenlabel token_label
    -pw password -label label -file filename -format ascii | binary

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-cert -create

Create a self-signed certificate on a cryptographic device:

 -cert -create -crypto module_name -tokenlabel token_label
 
    -pw password -label label -dn distinguished_name
 -size 1024 | 512
    -x509version 3 | 1 | 2 -default_cert no
 | yes -expire days 
    -sig_alg MD2_WITH_RSA | MD2WithRSA | 
             MD5_WITH_RSA | MD5WithRSA | 
             SHA1WithDSA | SHA1WithRSA |
             SHA256_WITH_RSA | SHA256WithRSA | 
             SHA2WithRSA | SHA384_WITH_RSA | 
             SHA384WithRSA | SHA512_WITH_RSA | 
             SHA512WithRSA | SHA_WITH_DSA  |
             SHA_WITH_RSA | SHAWithDSA |
             SHAWithRSA      

Note: You cannot import a certificate containing multiple OU (organizational unit) attributes in the distinguished name.

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-cert -delete

Delete a certificate on a cryptographic device:

 -cert -delete -crypto module_name -tokenlabel token_label
    -pw password -label label

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-cert -details

List the detailed information for a specific certificate on a cryptographic device:

 -cert -details -crypto module_name -tokenlabel token_label
 
    -pw password -label label

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

List the detailed information and show the full certificate for a specific certificate on a cryptographic device:

 -cert -details -showOID -crypto module_name -tokenlabel token_label 
    -pw password -label label

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-cert -extract

Extract a certificate from a key database:

 -cert -extract -crypto module_name -tokenlabel token_label
    -pw password -label label -target filename
 -format ascii | binary

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-cert -import

Import a certificate to a cryptographic device with secondary key database support:

 -cert -import -db filename -pw password -label label
 -type cms
    -crypto module_name -tokenlabel token_label -pw password
    -secondaryDB filename -secondaryDBpw password

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

 -cert -import -db filename -pw password -label label
 -type cms
    -crypto module_name -tokenlabel token_label -pw password
    -secondaryDB filename -secondaryDBpw password -fips

Import a PKCS #12 certificate to a cryptographic device with secondary key database support:

 -cert -import -file filename -pw password -type pkcs12
    -crypto module_name -tokenlabel token_label -pw password
    -secondaryDB filename -secondaryDBpw password

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

 -cert -import -file filename -pw password -type pkcs12
    -crypto module_name -tokenlabel token_label -pw password
    -secondaryDB filename -secondaryDBpw password -fips

Note: You cannot import a certificate containing multiple OU (organizational unit) attributes in the distinguished name.

-cert -list

List all certificates on a cryptographic device:

 -cert -list all | personal | CA 
    -crypto module_name -tokenlabel token_label -pw password

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-cert -receive

Receive a certificate from a file to a cryptographic device with secondary key database support:

 -cert -receive -file filename -crypto module_name -tokenlabel token_label 
    -pw password  -default_cert yes | no
    -secondaryDB filename -secondaryDBpw password -format ascii | binary

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

Use the runmqakm command:

-certreq -create

Create a certificate request on a cryptographic device:

 -certreq -create -crypto module_name -tokenlabel token_label
 
    -pw password -label label -dn distinguished_name
    -size 1024 | 512 -file filename 
    -sig_alg MD2_WITH_RSA | MD2WithRSA |MD5_WITH_RSA
 |
             MD5WithRSA |SHA1WithDSA | SHA1WithRSA
 |
             SHA256_WITH_RSA | SHA256WithRSA 
             SHA2WithRSA | SHA384_WITH_RSA | 
             SHA384WithRSA | SHA512_WITH_RSA | 
             SHA512WithRSA | SHA_WITH_DSA  |
             SHA_WITH_RSA | SHAWithDSA |
             SHAWithRSA       

Note: You cannot import a certificate containing multiple OU (organizational unit) attributes in the distinguished name.

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-certreq -delete

Delete a certificate request from a cryptographic device:

 -certreq -delete -crypto module_name -tokenlabel token_label
 
    -pw password -label label

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-certreq -details

List the detailed information of a specific certificate request on a cryptographic device:

 -certreq -details -crypto module_name -tokenlabel token_label
 
    -pw password -label label

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

List the detailed information about a certificate request and show the full certificate request on a cryptographic device:

 -certreq -details -showOID -crypto module_name -tokenlabel token_label 
    -pw password -label label

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-certreq -extract

Extract a certificate request from a certificate request database on a cryptographic device into a file:

 -certreq -extract -crypto module_name -tokenlabel token_label
 
    -pw password -label label -target filename

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.

-certreq -list

List all certificate requests in the certificate request database on a cryptographic device:

 -certreq -list -crypto module_name -tokenlabel token_label
 
    -pw password

If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 64-bit programs. External modules required for PKCS #11 support will be loaded into a 64-bit process, therefore you must have a 64-bit PKCS #11 library installed for the administration of cryptographic hardware. The Windows and Linux x86 32-bit platforms are the only exceptions, as the iKeyman and iKeycmd programs are 32-bit on those platforms.


runmqckm and runmqakm options

A table of the runmqckm and runmqakm options that can be present on the command line.

Note: WebSphere MQ does not support SHA-3 or SHA-5 algorithms. You can use the digital signature algorithm names SHA384WithRSA and SHA512WithRSA because both algorithms are members of the SHA-2 family.

The digital signature algorithm names SHA3WithRSA and SHA5WithRSA are deprecated because they are an abbreviated form of SHA384WithRSA and SHA512WithRSA respectively.

The meaning of an option can depend on the object and action specified in the command.

Options that can be used with runmqckm and runmqakm

Option Description
-create Option to create a key database.
-crypto Name of the module to manage a PKCS #11 cryptographic device.

The value after -crypto is optional if you specify the module name in the properties file. If you are using certificates or keys stored on PKCS #11 cryptographic hardware, note that iKeycmd and iKeyman are 32-bit programs. External modules required for PKCS #11 support will be loaded into a 32-bit process, therefore you must have a 32-bit PKCS #11 library installed for the administration of cryptographic hardware, and must specify this library to iKeycmd or iKeyman. The HP Itanium platform is the only exception, as the iKeyman program is 64-bit on the HP Itanium platform.

-db Fully qualified path name of a key database.
-default_cert Sets a certificate as the default certificate. The value can be yes or no. The default is no.
-dn X.500 distinguished name. The value is a string enclosed in double quotation marks, for example CN=John Smith,O=IBM,OU=Test,C=GB . Note that the CN, O, and C attributes are required.

Note: Avoid using multiple OU attributes in distinguished names when you create self-signed certificates. When you create such certificates, only the last entered OU value is accepted into the certificate.

-encryption Strength of encryption used in certificate export command. The value can be strong or weak . The default is strong.
-expire Expiration time in days of either a certificate or a database password. The default is 365 days for a certificate password.

There is no default time for a database password: use the -expire option to set a database password expiration time explicitly.

-file File name of a certificate or certificate request.
-format Format of a certificate. The value can be ascii for Base64_encoded ASCII or binary for Binary DER data. The default is ascii.
-label Label attached to a certificate or certificate request.
-new_format New format of key database.
-new_label Used on a certificate import command, this option allows a certificate to be imported with a different label from the label it had in the source key database.
-new_pw New database password.
-old_format Old format of key database.
-pw Password for the key database or PKCS #12 file.
-secondaryDB Name of a secondary key database for PKCS #11 device operations.
-secondaryDBpw Password for the secondary key database for PKCS #11 device operations.
-showOID Displays the full certificate or certificate request.
-size Key size.

For runmqckm, the value can be 512, 1024, or 2048. The default value is 1024 bits.

For runmqakm, the value depends upon the signature algorithm:

  • For RSA signature algorithms (the default algorithm used if no -sig_alg is specified), the value can be 512, 1024, 2048, or 4096. An RSA key size of 512 bits os not permitted if the -fips parameter is enabled. The default RSA key size is 1024 bits.
  • For Elliptic Curve algorithms, the value can be 256, 384, or 512. The default Elliptic Curve key size depends upon the signature algorithm. For SHA256, it is 256; for SHA384 , it is 384; and for SHA512, it is 512.

-stash Stash the key database password to a file.
-target Destination file or database.
-target_pw Password for the key database if -target specifies a key database.
-target_type Type of database specified by -target operand. See -type option for permitted values.
-tokenLabel Label of a PKCS #11 cryptographic device.
-trust Trust status of a CA certificate. The value can be enable or disable. The default is enable.
-type Type of database. The value can be:

  • cms for a CMS key database
  • pkcs12 for a PKCS #12 file.

-x509version Version of X.509 certificate to create. The value can be 1, 2, or 3. The default is 3.


runmqakm error codes

A table of the numeric error codes issued by runmqakm, and what they mean.

Error code Error Message
0 Success
1 Unknown error occurred
2 An ASN.1 encoding/decoding error occurred.
3 An error occurred while initializing ASN.1 encoder/decoder.
4 An ASN.1 encoding/decoding error occurred because of an out-of-range index or non-existent optional field.
5 A database error occurred.
6 An error occurred while opening the database file, check for file existence and permission.
7 An error occurred while re-opening the database file.
8 Database creation failed.
9 The database already exists.
10 An error occurred while deleting the database file.
11 The database could not be opened.
12 An error occurred while reading the database file.
13 An error occurred while writing data to the database file.
14 A database validation error occurred.
15 An invalid database version was encountered.
16 An invalid database password was encountered.
17 An invalid database file type was encountered.
18 The specified database has been corrupted.
19 An invalid password was provided or the key database has been tampered with or corrupted.
20 A database key entry integrity error occurred.
21 A duplicate certificate already exists in the database.
22 A duplicate key already exists in the database (Record ID).
23 A certificate with the same label already existed in the key database.
24 A duplicate key already exists in the database (Signature).
25 A duplicate key already exists in the database (Unsigned Certificate).
26 A duplicate key already exists in the database (Issuer and Serial Number).
27 A duplicate key already exists in the database (Subject Public Key Info).
28 A duplicate key already exists in the database (Unsigned CRL).
29 The label has been used in the database.
30 A password encryption error occurred.
31 An LDAP related error occurred. (LDAP is not supported by this program)
32 A cryptographic error occurred.
33 An encryption/decryption error occurred.
34 An invalid cryptographic algorithm was found.
35 An error occurred while signing data.
36 An error occurred while verifying data.
37 An error occurred while computing digest of data.
38 An invalid cryptographic parameter was found.
39 An unsupported cryptographic algorithm was encountered.
40 The specified input size is greater than the supported modulus size.
41 An unsupported modulus size was found.
42 A database validation error occurred.
43 Key entry validation failed.
44 A duplicate extension field exists.
45 The version of the key is wrong.
46 A required extension field does not exist.
47 The validity period does not include today or does not fall within its issuer's validity period
48 The validity period does not include today or does not fall within its issuer's validity period.
49 An error occurred while validating private key usage extension.
50 The issuer of the key was not found.
51 A required certificate extension is missing.
52 An invalid basic constraint extension was found.
53 The key signature validation failed.
54 The root key of the key is not trusted.
55 The key has been revoked.
56 An error occurred while validating authority key identifier extension.
57 An error occurred while validating private key usage extension.
58 An error occurred while validating subject alternative name extension.
59 An error occurred while validating issuer alternative name extension.
60 An error occurred while validating key usage extension.
61 An unknown critical extension was found.
62 An error occurred while validating key pair entries.
63 An error occurred while validating CRL.
64 A mutex error occurred.
65 An invalid parameter was found.
66 A null parameter or memory allocation error was encountered.
67 Number or size is too large or too small.
68 The old password is invalid.
69 The new password is invalid.
70 The password has expired.
71 A thread related error occurred.
72 An error occurred while creating threads.
73 An error occurred while a thread was waiting to exit.
74 An I/O error occurred.
75 An error occurred while loading CMS.
76 A cryptography hardware related error occurred.
77 The library initialization routine was not successfully called.
78 The internal database handle table is corrupted.
79 A memory allocation error occurred.
80 An unrecognized option was found.
81 An error occurred while getting time information.
82 Mutex creation error occurred.
83 An error occurred while opening message catalog.
84 An error occurred while opening error message catalog
85 A null file name was found.
86 An error occurred while opening files, check for file existence and permissions.
87 An error occurred while opening files to read.
88 An error occurred while opening files to write.
89 There is no such file.
90 The file cannot be opened because of its permission setting.
91 An error occurred while writing data to files.
92 An error occurred while deleting files.
93 Invalid Base64-encoded data was found.
94 An invalid Base64 message type was found.
95 An error occurred while encoding data with Base64 encoding rule.
96 An error occurred while decoding Base64-encoded data.
97 An error occurred while getting a distinguished name tag.
98 The required common name field is empty.
99 The required country or region name field is empty.
100 An invalid database handle was found.
101 The key database does not exist.
102 The request key pair database does not exist.
103 The password file does not exist.
104 The new password is identical to the old one.
105 No key was found in the key database.
106 No request key was found.
107 No trusted CA was found.
108 No request key was found for the certificate.
109 There is no private key in the key database.
110 There is no default key in the key database.
111 There is no private key in the key record.
112 There is no certificate in the key record.
113 There is no CRL entry.
114 An invalid key database file name was found.
115 An unrecognized private key type was found.
116 An invalid distinguished name input was found.
117 No key entry was found that has the specified key label.
118 The key label list has been corrupted.
119 The input data is not valid PKCS12 data.
120 The password is invalid or the PKCS12 data has been corrupted or been created with later version of PKCS12
121 An unrecognized key export type was found.
122 An unsupported password-based encryption algorithm was found.
123 An error occurred while converting the key ring file to a CMS key database.
124 An error occurred while converting the CMS key database to a key ring file.
125 An error occurred while creating a certificate for the certificate request.
126 A complete issuer chain cannot be built.
127 Invalid WEBDB data was found.
128 There is no data to be written to the key ring file.
129 The number of days that you entered extends beyond the permitted validity period.
130 The password is too short; it must consist of at least {0} characters.
131 A password must contain at least one numeric digit.
132 All characters in the password are either alphabetic or numeric characters.
133 An unrecognized or unsupported signature algorithm was specified.
134 An invalid database type was encountered.
135 The specified secondary key database is in use by another PKCS#11 device.
136 No secondary key database was specified.
137 The label does not exist on the PKCS#11 device.
138 Password required to access the PKCS#11 device.
139 Password not required to access the PKCS#11 device.
140 Unable to load the cryptographic library.
141 PKCS#11 is not supported for this operation.
142 An operation on a PKCS#11 device has failed.
143 The LDAP user is not a valid user. (LDAP is not supported by this program)
144 The LDAP user is not a valid user. (LDAP is not supported by this program)
145 The LDAP query failed. (LDAP is not supported by this program)
146 An invalid certificate chain was found.
147 The root certificate is not trusted.
148 A revoked certificate was encountered.
149 A cryptographic object function failed.
150 There is no certificate revocation list data source available.
151 There is no cryptographic token available.
152 FIPS mode is not available.
153 There is a conflict with the FIPS mode settings.
154 The password entered does not meet the minimum required strength.
200 There was a failure during initialization of the program.
201 Tokenization of the arguments passed to the runmqakm Program failed.
202 The object identified in the command is not a recognized object.
203 The action passed is not a known -keydb action.
204 The action passed is not a known -cert action.
205 The action passed is not a known -certreq action.
206 There is a tag missing for the requested command.
207 The value passed with the -version tag is not a recognized value.
208 The value passed with the -size tag is not a recognized value.
209 The value passed in with the -dn tag is not in the correct format.
210 The value passed in with the -format tag is not a recognized value.
211 There was an error associated with opening the file.
212 PKCS12 is not supported at this stage.
213 The cryptographic token you are trying to change the password for is not password protected.
214 PKCS12 is not supported at this stage.
215 The password entered does not meet the minimum required strength.
216 FIPS mode is not available.
217 The number of days you have entered as the expiry date is out of the allowed range.
218 Password strength failed the minimum requirements.
219 No Default certificate was found in the requested key database.
220 An invalid trust status was encountered.
221 An unsupported signature algorithm was encountered. At this stage only MD5 and SHA1 are supported.
222 PCKS11 not supported for that particular operation.
223 The action passed is not a known -random action.
224 A length than less than zero is not allowed.
225 When using the -strong tag the minimum length password is 14 characters.
226 When using the -strong tag the maximum length password is 300 characters.
227 The MD5 algorithm is not supported when in FIPS mode.
228 The site tag is not supported for the -cert -list command. This attribute is added for backward compatibility and potential future enhancement.
229 The value associated with the -ca tag is not recognized. The value must be either 'true' or 'false'.
230 The value passed in with the -type tag is not valid.
231 The value passed in with the -expire tag is below the allowed range.
232 The encryption algorithm Used or requested is not supported.
233 The target already exists.


MQSC reference

Use MQSC commands to manage queue manager objects, including the queue manager itself, queues, process definitions, channels, client connection channels, listeners, services, namelists, clusters, and authentication information objects.

For an overview of using MQSC commands for administering WebSphere MQ, see Performing local administration tasks using MQSC commands .

MQSC commands use certain special characters to have certain meanings. For more information about these special characters and how to use them, see Generic values and characters with special meanings .

To find out how you can build scripts using MQSC commands, see Building command scripts .

For the full list of MQSC commands, see The MQSC commands .


Generic values and characters with special meanings

The following information describes generic values, and characters that have special meaning when you build MQSC commands.

Wherever a parameter can have a generic value, it is entered ending with an asterisk (*), for example ABC*. A generic value means 'all values beginning with'; so ABC* means 'all values beginning with ABC'.

If characters that require quotation marks are used in the value, the asterisk must be placed inside the quotation marks, thus 'abc*'. The asterisk must be the last or only character in the value.

The question mark (?) and colon (:) are not allowed in generic values.

Character Description
  Blanks are used as separators. Multiple blanks are equivalent to a single blank, except in strings that have apostrophes (') round them. Any trailing blanks in those string attributes which are based on MQCHARV types are treated as significant.
, Commas are used as separators. Multiple commas are equivalent to a single comma, except in strings that have apostrophes (') round them.
' An apostrophe indicates the beginning or end of a string. WebSphere MQ leaves all characters that have quotation marks round them exactly as they are entered. The containing apostrophes are not included when calculating the length of the string.
'' Single quotation marks inside a string are treated by WebSphere MQ as one character when calculating the length of the string and the string is not terminated.
= On z/OS, an equals sign indicates the start of a parameter value which is ended by a comma or blank.
( An open parenthesis indicates the beginning of a parameter value or list of values.
) A close parenthesis indicates the end of a parameter value or list of values.
: A colon indicates an inclusive range. For example (1:5) means (1,2,3,4,5). This notation can be used only in TRACE commands.
* An asterisk means "all". For example, DISPLAY TRACE (*) means display all traces, and DISPLAY QUEUE (PAY*) means display all queues with names that begin with PAY.

When you need to use any of these special characters in a field (for example as part of a description), you must enclose the whole string in single quotation marks.


Building command scripts

Use this information to learn how to build command scripts.

You might want to build the MQSC commands into a script when you use:

When you do this, follow these rules:


Use commands on z/OS

MQSC commands can be issued from various sources, depending on the command.

Commands can be issued from the following sources:

However, not all commands can be issued from all these sources. Commands can be classified according to whether they can be issued from:

1

CSQINP1

2

CSQINP2

C

The z/OS console

R

The command server and command queue, by means of CSQUTIL, CSQINPT, CSQINPX, or applications

Within the command descriptions that follow, these sources are identified by the use of the characters 1, 2, C, and R in the z/OS column of the table at the top of each command description.


The MQSC commands

Use this topic as a reference to the MQSC commands.

This section describes, in alphabetical order, all the MQSC commands that can be issued by operators and administrators.


ALTER AUTHINFO

Use the MQSC command ALTER AUTHINFO to alter an authentication information object.

These objects contain the definitions required to perform certificate revocation checking using OCSP or Certificate Revocation Lists (CRLs) on LDAP servers.
IBM i UNIX and Linux Windows z/OS
X X X 2CR

Parameters not specified in the ALTER AUTHINFO command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT AUTHINFO

   
ALTER AUTHINFO

>>-ALTER AUTHINFO--(-- name--)--+-AUTHTYPE(CRLLDAP)-+------------>
                               '-AUTHTYPE(OCSP)----'   

>--+-----------------------+--+---------------------+----------->
   '-CONNAME--(-- string--)-'  '-DESCR--(-- string--)-'   

>--+-----------------------+--+------------------------+-------->
   '-LDAPPWD--(-- string--)-'  '-LDAPUSER--(-- string--)-'   

>--+-----------------------+------------------------------------>
   '-OCSPURL--(-- string--)-'   

   .-CMDSCOPE(' ')-----------------. (1)   
>--+-------------------------------+---------------------------->
   |                           (1) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (2)               |       
   '-CMDSCOPE(*)-------------------'       

   .-QSGDISP(QMGR)------. (1)   
>--+--------------------+--------------------------------------><
   +-QSGDISP(COPY)------+       
   |                (2) |       
   +-QSGDISP(GROUP)-----+       
   '-QSGDISP(PRIVATE)---'       


Notes:

  1. Valid only on z/OS.
  2. Valid only when the queue manager is a member of a queue-sharing group. You can use queue-sharing groups only on WebSphere MQ for z/OS.


Parameter descriptions for ALTER AUTHINFO

name

Name of the authentication information object. This parameter is required.

The name must not be the same as any other authentication information object name currently defined on this queue manager (unless REPLACE or ALTER is specified). See Rules for naming WebSphere MQ objects .

AUTHTYPE

The type of authentication information.

CRLLDAP
Certificate Revocation List checking is done using LDAP servers.
OCSP
Certificate revocation checking is done using OCSP.

An authentication information object with AUTHTYPE(OCSP) does not apply for use on IBM i or z/OS queue managers. However, it can be specified on those platforms to be copied to the client channel definition table (CCDT) for client use.

This parameter is required.

You cannot define an authentication information object as LIKE one with a different AUTHTYPE. You cannot alter the AUTHTYPE of an authentication information object after you have created it.

CMDSCOPE

This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group.

CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP.

' '

The command is executed on the queue manager on which it was entered.

qmgr-name

The command is executed on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

You can specify a queue manager name other than the queue manager on which it was entered, only if you are using a shared queue environment and if the command server is enabled.

*

The command is executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of * is the same as entering the command on every queue manager in the queue-sharing group.

CONNAME(string)

The host name, IPv4 dotted decimal address, or IPv6 hexadecimal notation of the host on which the LDAP server is running, with an optional port number.

CONNAME is required if AUTHTYPE(CRLLDAP) is specified. CONNAME is not valid if AUTHTYPE(CRLLDAP) is not specified.

If you specify the connection name as an IPv6 address, only systems with an IPv6 stack are able to resolve this address. If the AUTHINFO object is part of the CRL namelist of the queue manager, ensure that any clients using the client channel table generated by the queue manager can resolve the connection name.

On z/OS, if a CONNAME is to resolve to an IPv6 network address, a level of z/OS that supports IPv6 for connection to an LDAP server is required.

The syntax for CONNAME is the same as for channels. For example,

 conname('hostname(nnn)')
where nnn is the port number.

The maximum length for the field is 264 characters on IBM i, UNIX systems, and Windows, and 48 characters on z/OS.

DESCR(string)

Plain-text comment. It provides descriptive information about the authentication information object when an operator issues the DISPLAY AUTHINFO command (see DISPLAY AUTHINFO ).

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

LDAPPWD(string)

The password associated with the Distinguished Name of the user who is accessing the LDAP server. Its maximum size is 32 characters.

This parameter is valid only for AUTHTYPE(CRLLDAP).

On z/OS, the LDAPPWD used for accessing the LDAP server might not be the one defined in the AUTHINFO object. If more than one AUTHINFO object is placed in the namelist referred to by the QMGR parameter SSLCRLNL, the LDAPPWD in the first AUTHINFO object is used for accessing all LDAP Servers.

LDAPUSER(string)

The Distinguished Name of the user who is accessing the LDAP server. (See the SSLPEER parameter for more information about distinguished names.)

This parameter is valid only for AUTHTYPE(CRLLDAP).

The maximum size for the user name is 1024 characters on IBM i, UNIX systems, and Windows, and 256 characters on z/OS.

On z/OS, the LDAPUSER used for accessing the LDAP Server might not be the one defined in the AUTHINFO object. If more than one AUTHINFO object is placed in the namelist referred to by the QMGR parameter SSLCRLNL, the LDAPUSER in the first AUTHINFO object is used for accessing all LDAP Servers.

On IBM i, UNIX systems, and Windows, the maximum accepted line length is defined to be BUFSIZ, which can be found in stdio.h.

OCSPURL

The URL of the OCSP responder used to check for certificate revocation. This value must be an HTTP URL containing the host name and port number of the OCSP responder. If the OCSP responder is using port 80, which is the default for HTTP, then the port number can be omitted. HTTP URLs are defined in RFC 1738.

This field is case sensitive. It must start with the string http:// in lowercase. The rest of the URL might be case sensitive, depending on the OCSP server implementation. To preserve case, use single quotation marks to specify the OCSPURL parameter value, for example:

 OCSPURL('http://ocsp.example.ibm.com')

This parameter is applicable only for AUTHTYPE(OCSP), when it is mandatory.

QSGDISP

This parameter applies to z/OS only.

Specifies the disposition of the object to which you are applying the command (that is, where it is defined and how it behaves).

QSGDISP ALTER
COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(COPY). Any object residing in the shared repository, or any object defined using a command that had the parameters QSGDISP(QMGR), is not affected by this command.
GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). Any object residing on the page set of the queue manager that executes the command (except a local copy of the object) is not affected by this command. If the command is successful, the following command is generated and sent to all active queue managers in the queue-sharing group to attempt to refresh local copies on page set zero:

 DEFINE AUTHINFO(name) 
REPLACE QSGDISP(COPY)
The ALTER for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with QSGDISP(QMGR) or QSGDISP(COPY). Any object residing in the shared repository is unaffected.
QMGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(QMGR). Any object residing in the shared repository, or any local copy of such an object, is not affected by this command.


ALTER BUFFPOOL

Use the MQSC command ALTER BUFFPOOL to dynamically add buffers to a predefined buffer pool, or remove buffers from a predefined buffer pool.

IBM i UNIX and Linux Windows z/OS
      2CR

Parameters not specified in the ALTER BUFFPOOL command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT BP

   
ALTER BUFFPOOL

>>-ALTER BUFFPOOL--(-- buf-pool-id--)---------------------------->

   .-BUFFERS(1000)----------.   
>--+------------------------+----------------------------------><
   '-BUFFERS--(-- integer--)-'   



Usage notes for ALTER BUFFPOOL

  1. Buffers are added or removed according to whether the value is more than or less than the current allocation (which can be shown by the DISPLAY USAGE command).
  2. If there is insufficient storage to add the requested number, as many as possible are added.
  3. The command is processed asynchronously. Message CSQP023I is sent to the console when the command is complete.


Parameter descriptions for ALTER BUFFPOOL

(buf-pool-id)

Buffer pool identifier.

This parameter is an integer in the range zero through 15.

BUFFERS(integer)

This parameter is required and is the number of 4096 byte buffers to be used in this buffer pool. The minimum value is 100. The maximum value is 500,000. The sum of the buffers values for all of the buffer pools is determined by the amount of storage available in the WebSphere MQ address space.

The queue manager records the current buffer pool sizes in checkpoint log records. These buffer pool sizes are automatically restored when a queue manager is later restarted. This restoration occurs after processing of the CSQINP1 data set, therefore if you have used ALTER BUFFPOOL since the buffer pool was last defined, any DEFINE BUFFPOOL command in CSQINP1 has been ignored at restart.


ALTER CFSTRUCT

Use the MQSC command ALTER CFSTRUCT to alter the CF application structure backup and recovery parameters, and offload environment parameters for any specified application structure.

IBM i UNIX and Linux Windows z/OS
      2CR

Parameters not specified in the ALTER CFSTRUCT command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT CFSTRUCT

   
ALTER CFSTRUCT

>>-ALTER CFSTRUCT--(-- structure-name--)------------------------->

>--+----------------------+--+------------------------+--------->
   +-CFCONLOS (ASQMGR)----+  '-CFLEVEL--(-- integer--)-'   
   +-CFCONLOS (TERMINATE)-+                               
   '-CFCONLOS (TOLERATE)--'                               

>--+---------------------+--+------------------------+---------->
   '-DESCR--(-- string--)-'  '-RECOVER--(--+-NO--+--)-'   
                                          '-YES-'        

>--+------------------------+--+------------------------+------><
   '-RECAUTO--(--+-YES-+--)-'  '-| Offload attributes |-'   
                 '-NO--'                                    

Offload attributes

|--+---------------+-------------------------------------------->
   +-OFFLOAD(SMDS)-+   
   '-OFFLOAD(DB2)--'   

>--+----------------+--+----------------------+----------------->
   '-OFFLD1SZ(size)-'  '-OFFLD1TH(percentage)-'   

>--+----------------+--+----------------------+----------------->
   '-OFFLD2SZ(size)-'  '-OFFLD2TH(percentage)-'   

>--+----------------+--+----------------------+----------------->
   '-OFFLD3SZ(size)-'  '-OFFLD3TH(percentage)-'   

>--+----------------------------+--+-------------------+-------->
   '-DSGROUP('data.set.name.*')-'  '-DSBLOCK(blockize)-'   

>--+----------------+--+-------------+--------------------------|
   '-DSBUFS(number)-'  +-EXPAND(YES)-+   
                       '-EXPAND(NO)--'   



Usage notes


Parameter descriptions for ALTER CFSTRUCT

(structure-name)

Name of the coupling facility application structure with queue manager CF level capability and backup and recovery parameters you want to define. This parameter is required.

The name:

  • Cannot have more than 12 characters.
  • Must start with an uppercase letter (A through Z).
  • Can include only the characters A through Z and 0 through 9.

The name of the queue-sharing group to which the queue manager is connected is prefixed to the name you supply. The name of the queue-sharing group is always four characters, padded with @ symbols if necessary. For example, if you use a queue-sharing group named NY03 and you supply the name PRODUCT7, the resultant coupling facility structure name is NY03PRODUCT7. The administrative structure for the queue-sharing group (in this case NY03CSQ_ADMIN) cannot be used for storing messages.

CFCONLOS

This parameter specifies the action to be taken when a queue manager loses connectivity to the CF structure. The value can be:

ASQMGR

The action taken is based on the setting of the CFCONLOS queue manager attribute.

TERMINATE

The queue manager terminates when connectivity to the structure is lost. This is the default value when CFLEVEL is increased to 5.

TOLERATE

The queue manager tolerates loss of connectivity to the structure without terminating.

This parameter is only valid from CFLEVEL(5).

CFLEVEL(integer)

Specifies the functional capability level for this CF application structure. Value can be one of the following:

1

A CF structure that can be "auto-created" by a queue manager at command level 520.

2

A CF structure at command level 520 that can only be created or deleted by a queue manager at command level 530 or greater.

3

A CF structure at command level 530. This CFLEVEL is required if you want to use persistent messages on shared queues (if RECOVER(YES) is set), or for message grouping (when a local queue is defined with INDXTYPE(GROUPID)), or both.

You can only increase the value of CFLEVEL to 3 if all the queue managers in the queue-sharing group are at command level 530 or greater - this is to ensure that there are no latent command level 520 connections to queues referencing the structure.

You can only decrease the value of CFLEVEL from 3 if all the queues that reference the CF structure are both empty (have no messages or uncommitted activity) and closed.

4

This CFLEVEL supports all the CFLEVEL(3) functions. CFLEVEL(4) allows queues defined with CF structures at this level to have messages with a length greater than 63 KB.

Only a queue manager with a command level of 600 or greater can connect to a CF structure at CFLEVEL(4).

You can only increase the value of CFLEVEL to 4 if all the queue managers in the queue-sharing group are at command level 600 or greater.

You can only decrease the value of CFLEVEL from 4 if all the queues that reference the CF structure are both empty (have no messages or uncommitted activity) and closed.

5

This CFLEVEL supports all functions for CFLEVEL(4). In addition, CFLEVEL(5) enables the following new functions. If altering an existing CFSTRUCT to CFLEVEL(5), you must review other attributes as indicated:

  • queues defined with CF structures at this level can have message data offloaded to either shared message data sets (SMDS), or DB2, under control of the OFFLOAD attribute. The offload threshold and size parameters (such as OFFLD1TH, and OFFLD1SZ) determine whether any particular messages are offloaded given its size and current CF utilization. If using SMDS offload, the DSGROUP, DSBUFS, DSEXPAND and DSBLOCK attributes are respected.
  • structures at CFLEVEL(5) allow the queue manager to tolerate a loss of connectivity to the CF structure. The CFCONLOS attribute determines queue manager behavior when a loss of connectivity is detected, and the RECAUTO attribute controls subsequent automatic structure recovery behavior.
  • messages containing WebSphere MQ message properties are stored in a different format on shared queues in a CFLEVEL(5) structure. This format leads to internal processing optimizations. Additional application migration capabilities are also available and these are enabled via the queue PROPCTL attribute.

Only a queue manager with a command level of 710 or above can connect to a CF structure at CFLEVEL(5).

Note:

You can only increase the value of CFLEVEL to 5 if all the queue managers in the queue-sharing group are at command level 710 or greater and have OPMODE set to NEWFUNC.

You can decrease the value of CFLEVEL from 5 if all the queues that reference the CF structure are both empty, that is the queues, and CF structure have no messages or uncommitted activity, and are closed.

DESCR(string)

Plain-text comment that provides descriptive information about the object when an operator issues the DISPLAY CFSTRUCT command.

The string should contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

OFFLOAD

Specify whether offloaded message data is to be stored in a group of shared message data sets or in DB2.

SMDS

Offload messages from coupling facility to shared message data set (SMDS).

DB2

Offload messages from coupling facility to DB2. This value is the default assumption when CFLEVEL is increased to 5.

Offloading messages using DB2 has significant performance impact. To use offload rules as a means of increasing capacity, the SMDS option should be specified.

This parameter is only valid from CFLEVEL(5). At CFLEVEL(4) any message offloading is always to DB2, and only applies to messages greater than the maximum coupling facility entry size.

Note:

If you change the offload technique (from DB2 to SMDS or the other way) then all new messages will be written using the new method but any existing large messages stored using the previous technique can still be retrieved. The relevant DB2 message table or shared message data sets will continue to be used until the queue managers have detected that there are no further messages stored in the old format.

If SMDS is specified, then the DSGROUP parameter is also required. It can be specified either on the same command or on a previous DEFINE or ALTER command for the same structure.

OFFLD1TH(percentage) OFFLD1SZ(size)

OFFLD2TH(percentage) OFFLD2SZ(size)

OFFLD3TH(percentage) OFFLD3SZ(size)

Specify rules for when messages smaller than the maximum coupling facility entry size are to be offloaded to external storage (shared message data sets or DB2 tables) instead of being stored in the application structure. These rules can be used to increase the effective capacity of the structure. The offloaded message still requires an entry in the coupling facility containing message control information, and a descriptor referring to the offloaded message data, but the amount of structure space required is less than the amount that would be needed to store the whole message.

If the message data is very small (less than approximately 140 bytes) it may fit into the same coupling facility entry as the message control information, without needing additional data elements. In this case, no space can be saved, so any offload rules are ignored and the message data is not offloaded.

Messages exceeding the maximum coupling facility entry size (63.75 KB including control information) are always offloaded as they cannot be stored in a coupling facility entry. Messages where the message body exceeds 63 KB are also offloaded to ensure that enough space is available for the control information. Additional rules to request offloading of smaller messages can be specified using these pairs of keywords. Each rule indicates that when the usage of the structure (in either elements or entries) exceeds the specified threshold percentage value, the message data will be offloaded if the total size of the coupling facility entry required to store the whole message (including message data, headers and descriptors) exceeds the specified size value. Headers and descriptors typically require approximately 400 bytes.

percentage

The usage threshold percentage value is an integer in the range 0 (meaning this rule always applies) to 100 (meaning this rule only applies when the structure is full).

size

The message size value should be specified as an integer followed by K, giving the number of kilobytes in the range 0K to 64K. As messages exceeding 63.75 KB are always offloaded, the value 64K is allowed as a simple way to indicate that the rule is not being used.

In general, the smaller the numbers, the more messages are offloaded.

A message is offloaded if any offload rule matches. The normal convention is that a later rule would be for a higher usage level and a smaller message size than an earlier one, but no check is made for consistency or redundancy between the rules.

When structure ALTER processing is active, the number of used elements or entries can temporarily exceed the reported total number, giving a percentage exceeding 100, because the new elements or entries are made available during ALTER processing but the total is only updated when the ALTER completes. At such times, a rule specifying 100 for the threshold may temporarily take effect. If a rule is not intended to be used at all, it should specify 64K for the size.

The default values assumed for the offload rules when defining a new structure at CFLEVEL(5) or upgrading an existing structure to CFLEVEL(5) depend on the OFFLOAD method option. For OFFLOAD(SMDS), the default rules specify increasing amounts of offloading as the structure becomes full. This increases the effective structure capacity with minimal performance impact. For OFFLOAD(DB2), the default rules have the same threshold values as for SMDS but the size values are set to 64K so that the rules never apply and messages are offloaded only if they are too large to be stored in the structure, as for CFLEVEL(4).

For OFFLOAD(SMDS) the defaults are:

  • OFFLD1TH(70) OFFLD1SZ(32K)
  • OFFLD2TH(80) OFFLD2SZ(4K)
  • OFFLD3TH(90) OFFLD3SZ(0K)

For OFFLOAD(DB2) the defaults are:

  • OFFLD1TH(70) OFFLD1SZ(64K)
  • OFFLD2TH(80) OFFLD2SZ(64K)
  • OFFLD3TH(90) OFFLD3SZ(64K)

If the OFFLOAD method option is changed from DB2 to SMDS or back when the current offload rules all match the default values for the old method, the offload rules are switched to the default values for the new method. However, if any of the rules have been changed, the current values are kept when switching method.

These parameters are only valid from CFLEVEL(5). At CFLEVEL(4) any message offloading is always to DB2, and only applies to messages greater than the maximum coupling facility entry size.

DSGROUP

For OFFLOAD(SMDS), specify the generic data set name to be used for the group of shared message data sets associated with this structure (one for each queue manager), with exactly one asterisk indicating where the queue manager name should be inserted to form the specific data set name.

'data.set.name.*'

The value must be a valid data set name when the asterisk is replaced by a queue manager name of up to four characters. The queue manager name can form all or part of any qualifier in the data set name.

The entire parameter value must be enclosed in quotation marks.

This parameter cannot be changed after any data sets have been activated for the structure.

If SMDS is specified, then the DSGROUP parameter must also be specified.

This parameter is only valid from CFLEVEL(5).

DSBLOCK

For OFFLOAD(SMDS), specify the logical block size, which is the unit in which shared message data set space is allocated to individual queues.

8K

16K

32K

64K

128K

256K

512K

1M

Each message is written starting at the next page within the current block and is allocated further blocks as needed. A larger size decreases space management requirements and reduces I/O for large messages, but increases buffer space requirements and disk space requirements for small queues.

This parameter cannot be changed after any data sets have been activated for the structure.

This parameter is only valid from CFLEVEL(5).

DSBUFS

For OFFLOAD(SMDS), specify the number of buffers to be allocated in each queue manager for accessing shared message data sets, as a number in the range 1 - 9999. The size of each buffer is equal to the logical block size. SMDS buffers are allocated in memory objects residing in z/OS 64-bit storage (above the bar).

number

This parameter can be overridden for individual queue managers using the DSBUFS parameter on ALTER SMDS.

When this parameter is altered, any queue managers which are already connected to the structure (and which do not have an individual DSBUFS override value) dynamically increase or decrease the number of data set buffers being used for this structure to match the new value. If the specified target value cannot be reached, the affected queue manager adjusts the DSBUFS parameter associated with its own individual SMDS definition (as for the ALTER SMDS command) to match the actual new number of buffers.

This parameter is only valid from CFLEVEL(5).

DSEXPAND

For OFFLOAD(SMDS), this parameter controls whether the queue manager should expand a shared message data set when it becomes nearly full, and further blocks are required in the data set.

YES

Expansion is supported.

Each time expansion is required, the data set is expanded by the secondary allocation specified when the data set was defined. If no secondary allocation was specified, or it was specified as zero, then a secondary allocation amount of approximately 10% of the existing size is used

NO

No automatic data set expansion is to take place.

This parameter can be overridden for individual queue managers using the DSEXPAND parameter on ALTER SMDS.

If an expansion attempt fails, the DSEXPAND override for the affected queue manager is automatically changed to NO to prevent further expansion attempts, but it can be changed back to YES using the ALTER SMDS command to enable further expansion attempts.

When this parameter is altered, any queue managers which are already connected to the structure (and which do not have an individual DSEXPAND override value) immediately start using the new parameter value.

This parameter is only valid from CFLEVEL(5).

RECOVER

Specifies whether CF recovery is supported for the application structure. Values are:

NO

CF application structure recovery is not supported. (The synonym is N .)

YES

CF application structure recovery is supported. (The synonym is Y .)
You can only set RECOVER(YES) if the structure has a CFLEVEL of 3 or higher. Set RECOVER(YES) if you intend to use persistent messages.

You can only change RECOVER(NO) to RECOVER(YES) if all the queue managers in the queue-sharing group are at command level 530 or greater ; this is to ensure that there are no latent command level 520 connections to queues referencing the CFSTRUCT.

You can only change RECOVER(YES) to RECOVER(NO) if all the queues that reference the CF structure are both empty (have no messages or uncommitted activity) and closed.

RECAUTO

Specifies the automatic recovery action to be taken when a queue manager detects that the structure is failed or when a queue manager loses connectivity to the structure and no systems in the SysPlex have connectivity to the Coupling Facility that the structure is allocated in. Values can be:

YES

The structure and associated shared message data sets which also need recovery are automatically recovered. (The synonym is Y ).

NO

The structure is not automatically recovered. (The synonym is N ). This is the default value when CFLEVEL is increased to 5.

This parameter has no effect for structures defined with RECOVER(NO).

This parameter is only valid from CFLEVEL(5)


ALTER CHANNEL

Use the MQSC command ALTER CHANNEL to alter the parameters of a channel.

IBM i UNIX and Linux Windows z/OS
X X X 2CR
Parameters not specified in the ALTER CHANNEL command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT CHL


Usage notes


Parameter descriptions for ALTER CHANNEL

The following table shows the parameters that are relevant for each type of channel. There is a description of each parameter after the table. Parameters are optional unless the description states that they are required.

ALTER CHANNEL parameters

Parameter SDR SVR RCVR RQSTR CLNT- CONN SVR- CONN CLUS- SDR CLUS- RCVR
AFFINITY         X      
BATCHHB X X         X X
BATCHINT X X         X X
BATCHLIM X X         X X
BATCHSZ X X X X     X X
channel-name X X X X X X X X
CHLTYPE X X X X X X X X
CLNTWGHT         X      
CLUSNL             X X
CLUSTER             X X
CLWLPRTY             X X
CLWLRANK             X X
CLWLWGHT             X X
CMDSCOPE X X X X X X X X
COMPHDR X X X X X X X X
COMPMSG X X X X X X X X
CONNAME X X   X X   X X
CONVERT X X         X X
DEFCDISP X X X X   X    
DEFRECON         X      
DESCR X X X X X X X X
DISCINT X X       X X X
HBINT X X X X X X X X
KAINT X X X X X X X X
LIKE X X X X X X X X
LOCLADDR X X   X X   X X
LONGRTY X X         X X
LONGTMR X X         X X
MAXINST           X    
MAXINSTC           X    
MAXMSGL X X X X X X X X
MCANAME X X   X     X X
MCATYPE X X   X     X X
MCAUSER     X X   X   X
MODENAME X X   X X   X X
MONCHL X X X X   X X X
MRDATA     X X       X
MREXIT     X X       X
MRRTY     X X       X
MRTMR     X X       X
MSGDATA X X X X     X X
MSGEXIT X X X X     X X
NETPRTY               X
NPMSPEED X X X X     X X
PASSWORD X X   X X   X X
PROPCTL X X         X X
PUTAUT     X X   X   X
QMNAME         X      
QSGDISP X X X X X X X X
RCVDATA X X X X X X X X
RCVEXIT X X X X X X X X
REPLACE X X X X X X X X
SCYDATA X X X X X X X X
SCYEXIT X X X X X X X X
SENDDATA X X X X X X X X
SENDEXIT X X X X X X X X
SEQWRAP X X X X     X X
SHARECNV         X X    
SHORTRTY X X         X X
SHORTTMR X X         X X
SSLCAUTH   X X X   X   X
SSLCIPH X X X X X X X X
SSLPEER X X X X X X X X
STATCHL X X X X     X X
TPNAME X X   X X X X X
TRPTYPE X X X X X X X X
USEDLQ X X X X     X X
USERID X X   X X   X  
XMITQ X X            

AFFINITY

The channel affinity attribute is used so client applications that connect multiple times using the same queue manager name can choose whether to use the same client channel definition for each connection. This attribute is intended to be used when multiple applicable channel definitions are available.

PREFERRED

The first connection in a process reading a client channel definition table (CCDT) creates a list of applicable definitions based on the weighting with any applicable CLNTWGHT(0) definitions first and in alphabetical order. Each connection in the process attempts to connect using the first definition in the list. If a connection is unsuccessful the next definition is used. Unsuccessful non-CLNTWGHT(0) definitions are moved to the end of the list. CLNTWGHT(0) definitions remain at the start of the list and are selected first for each connection. For C, C++ and .NET (including fully managed .NET) clients the list is updated if the CCDT has been modified since the list was created. Each client process with the same host name creates the same list.

NONE

The first connection in a process reading a CCDT creates a list of applicable definitions. All connections in a process select an applicable definition based on the weighting with any applicable CLNTWGHT(0) definitions selected first in alphabetical order. For C, C++ and .NET (including fully managed .NET) clients the list is updated if the CCDT has been modified since the list was created.

For example, suppose we had the following definitions in the CCDT:

 CHLNAME(A) QMNAME(QM1) CLNTWGHT(3)
CHLNAME(B) QMNAME(QM1) CLNTWGHT(4)
CHLNAME(C) QMNAME(QM1) CLNTWGHT(4)

The first connection in a process creates its own ordered list based on the weightings. So it might, for example, create the ordered list CHLNAME(B), CHLNAME(A), CHLNAME(C).

For AFFINITY(PREFERRED), each connection in the process attempts to connect using CHLNAME(B). If a connection is unsuccessful the definition is moved to the end of the list which now becomes CHLNAME(A), CHLNAME(C), CHLNAME(B). Each connection in the process then attempts to connect using CHLNAME(A).

For AFFINITY(NONE), each connection in the process attempts to connect using one of the three definitions selected at random based on the weightings.

When sharing conversations is enabled with a non-zero channel weighting and AFFINITY(NONE), multiple connections in a process using the same queue manager name can connect using different applicable definitions rather than sharing an existing channel instance.

BATCHHB(integer)

Specifies whether batch heartbeats are to be used. The value is the length of the heartbeat in milliseconds.

Batch heartbeats allow a sending channel to verify that the receiving channel is still active just before committing a batch of messages, so that if the receiving channel is not active, the batch can be backed out rather than becoming in-doubt, as would otherwise be the case. By backing out the batch, the messages remain available for processing so they could, for example, be redirected to another channel.

If the sending channel has had a communication from the receiving channel within the batch heartbeat interval, the receiving channel is assumed to be still active. If not, a 'heartbeat' is sent to the receiving channel to check.

The value must be in the range zero through 999999. A value of zero indicates that batch heartbeating is not used.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, and CLUSRCVR.

BATCHINT(integer)

The minimum amount of time, in milliseconds, that a channel keeps a batch open.

The batch is terminated when one of the following conditions is met:

  • BATCHSZ messages have been sent.
  • BATCHLIM bytes have been sent.
  • The transmission queue is empty and BATCHINT is exceeded.

The value must be in the range 0 - 999999999. Zero means that the batch is terminated as soon as the transmission queue becomes empty (or the BATCHSZ limit is reached).

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

BATCHLIM(integer)

The limit, in kilobytes, of the amount of data that can be sent through a channel before taking a sync point. A sync point is taken after the message that caused the limit to be reached has flowed across the channel. A value of zero in this attribute means that no data limit is applied to batches over this channel.

The batch is terminated when one of the following conditions is met:

  • BATCHSZ messages have been sent.
  • BATCHLIM bytes have been sent.
  • The transmission queue is empty and BATCHINT is exceeded.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

The value must be in the range 0 - 999999. The default value is 5000.

This parameter is supported on all platforms.

BATCHSZ(integer)

The maximum number of messages that can be sent through a channel before taking a sync point.

The maximum batch size used is the lowest of the following values:

  • The BATCHSZ of the sending channel.
  • The BATCHSZ of the receiving channel.
  • On z/OS, three less than the maximum number of uncommitted messages allowed at the sending queue manager (or one if this value is zero or less). On platforms other than z/OS, the maximum number of uncommitted messages allowed at the sending queue manager (or one if this value is zero or less).
  • On z/OS, three less than the maximum number of uncommitted messages allowed at the receiving queue manager (or one if this value is zero or less). On platforms other than z/OS, the maximum number of uncommitted messages allowed at the receiving queue manager (or one if this value is zero or less).

The maximum number of uncommitted messages is specified by the MAXUMSGS parameter of the ALTER QMGR command.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RCVR, RQSTR, CLUSSDR, or CLUSRCVR.

The value must be in the range 1 through 9999.

(channel-name)

The name of the new channel definition.

This parameter is required on all types of channel. On CLUSSDR channels, it can take a different form from the other channel types. If your convention for naming cluster-sender channels includes the name of the queue manager, you can define a cluster-sender channel using the +QMNAME+ construction. After connection to the matching cluster-receiver channel, WebSphere MQ substitutes the correct repository queue manager name in place of +QMNAME+ in the cluster-sender channel definition. This facility applies to AIX, HP-UX, Linux, IBM i, Solaris, and Windows only.

The name must not be the same as any existing channel defined on this queue manager (unless REPLACE or ALTER is specified). On z/OS, client-connection channel names can duplicate others.

The maximum length of the string is 20 characters, and the string must contain only valid characters; see Rules for naming WebSphere MQ objects .

CHLTYPE

Channel type. This parameter is required. It must follow immediately after the (channel-name) parameter on all platforms except z/OS.

SDR

Sender channel

SVR

Server channel

RCVR

Receiver channel

RQSTR

Requester channel

CLNTCONN

Client-connection channel

SVRCONN

Server-connection channel

CLUSSDR

Cluster-sender channel

CLUSRCVR

Cluster-receiver channel

Note: If you are using the REPLACE option, you cannot change the channel type.

CLNTWGHT

The client channel weighting attribute is used so client channel definitions can be selected at random based on their weighting when more than one suitable definition is available. Specify a value in the range 0 - 99.

The special value 0 indicates that no random load balancing is performed and applicable definitions are selected in alphabetical order. To enable random load balancing the value can be in the range 1 through 99 where 1 is the lowest weighting and 99 is the highest.

When a client issues an MQCONN with queue manager name "*<name>" and more than one suitable definition is available in the CCDT the choice of definition to use is randomly selected based on the weighting with any applicable CLNTWGHT(0) definitions selected first in alphabetical order. The distribution is not guaranteed.

For example, suppose we had the following two definitions in the CCDT:

 CHLNAME(TO.QM1) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address1) CLNTWGHT(2)
CHLNAME(TO.QM2) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address2) CLNTWGHT(4)

A client MQCONN with queue manager name "*GRP1" would choose one of the two definitions based on the weighting of the channel definition. (A random integer 1 - 6 would be generated. If the integer was in the range 1 through 2 address1 would be used otherwise address2 would be used). If this connection was unsuccessful the client would then use the other definition.

The CCDT might contain applicable definitions with both zero and non-zero weighting. In this situation, the definitions with zero weightings are chosen first and in alphabetical order. If these connections are unsuccessful the definitions with non-zero weighting are chosen based on their weighting.

For example, suppose we had the following four definitions in the CCDT:

 CHLNAME(TO.QM1) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address1) CLNTWGHT(1)
CHLNAME(TO.QM2) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address2) CLNTWGHT(2)
CHLNAME(TO.QM3) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address3) CLNTWGHT(0)
CHLNAME(TO.QM4) CHLTYPE(CLNTCONN) QMNAME(GRP1) CONNAME(address4) CLNTWGHT(0)

A client MQCONN with queue manager name "*GRP1" would first choose definition "TO.QM3". If this connection was unsuccessful the client would then choose definition "TO.QM4". If this connection was also unsuccessful the client would then randomly choose one of the remaining two definitions based on their weighting.

CLNTWGHT support is added for all supported transport protocols.

CLUSNL(nlname)

The name of the namelist that specifies a list of clusters to which the channel belongs.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR and CLUSRCVR channels. Only one of the resultant values of CLUSTER or CLUSNL can be nonblank, the other must be blank.

CLUSTER(clustername)

The name of the cluster to which the channel belongs. The maximum length is 48 characters conforming to the rules for naming WebSphere MQ objects.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR. Only one of the resultant values of CLUSTER or CLUSNL can be nonblank, the other must be blank.

CLWLPRTY(integer)

Specifies the priority of the channel for the purposes of cluster workload distribution. The value must be in the range zero through 9 where zero is the lowest priority and 9 is the highest.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR.

For more information about this attribute, see CLWLPRTY queue attribute .

CLWLRANK(integer)

Specifies the rank of the channel for the purposes of cluster workload distribution. The value must be in the range zero through 9 where zero is the lowest rank and 9 is the highest.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR.

For more information about this attribute, see CLWLRANK channel attribute .

CLWLWGHT(integer)

Specifies the weighting to be applied to the channel for the purposes of cluster workload distribution so that the proportion of messages sent down the channel can be controlled. The value must be in the range 1 through 99 where 1 is the lowest rank and 99 is the highest.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLUSSDR or CLUSRCVR.

For more information about this attribute, see CLWLWGHT channel attribute .

CMDSCOPE

This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group.

CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP.

' '

The command is executed on the queue manager on which it was entered.

qmgr-name

The command is executed on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

You can specify a queue manager name other than the queue manager on which it was entered, only if you are using a shared queue environment and if the command server is enabled.

*

The command is executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of * is the same as entering the command on every queue manager in the queue-sharing group.
COMPHDR

The list of header data compression techniques supported by the channel. For sender, server, cluster-sender, cluster-receiver, and client-connection channels, the values specified are in order of preference with the first compression technique supported by the remote end of the channel being used.

The mutually supported compression techniques of the channel are passed to the message exit of the sending channel where the compression technique used can be altered on a per message basis. Compression alters the data passed to send and receive exits.

NONE

No header data compression is performed.

SYSTEM

Header data compression is performed.
COMPMSG

The list of message data compression techniques supported by the channel. For sender, server, cluster-sender, cluster-receiver, and client-connection channels, the values specified are in order of preference with the first compression technique supported by the remote end of the channel being used.

The mutually supported compression techniques of the channel are passed to the message exit of the sending channel where the compression technique used can be altered on a per message basis. Compression alters the data passed to send and receive exits.

NONE

No message data compression is performed.

RLE

Message data compression is performed using run-length encoding.

ZLIBFAST

Message data compression is performed using ZLIB encoding with speed prioritized.

ZLIBHIGH

Message data compression is performed using ZLIB encoding with compression prioritized.

ANY

Any compression technique supported by the queue manager can be used. This value is only valid for receiver, requester, and server-connection channels.
CONNAME(string)

Connection name.

For cluster-receiver channels (when specified) CONNAME relates to the local queue manager, and for other channels it relates to the target queue manager.

The maximum length of the string is 48 characters on z/OS, and 264 characters on other platforms.

A workaround to the 48 character limit might be one of the following suggestions:

  • Set up your DNS servers so that you use, for example, host name of "myserver" instead of "myserver.location.company.com", ensuring you can use the short host name.
  • Use IP addresses.

Specify CONNAME as a comma-separated list of names of machines for the stated TRPTYPE. Typically only one machine name is required. You can provide multiple machine names to configure multiple connections with the same properties. The connections are usually tried in the order they are specified in the connection list until a connection is successfully established. The order is modified for clients if the CLNTWGHT attribute is provided. If no connection is successful, the channel attempts the connection again, as determined by the attributes of the channel. With client channels, a connection-list provides an alternative to using queue manager groups to configure multiple connections. With message channels, a connection list is used to configure connections to the alternative addresses of a multi-instance queue manager.

This parameter is required for channels with a channel type (CHLTYPE) of SDR, RQSTR, CLNTCONN, and CLUSSDR. It is optional for SVR channels, and for CLUSRCVR channels of TRPTYPE(TCP), and is not valid for RCVR or SVRCONN channels.

Providing multiple connection names in a list was first supported in WebSphere MQ version 7.0.1. It changes the syntax of the CONNAME parameter. Earlier clients and queue managers connect using the first connection name in the list, and do not read the rest of the connection names in the list. In order for the earlier clients and queue managers to parse the new syntax, you must specify a port number on the first connection name in the list. Specifying a port number avoids problems when connecting to the channel from a client or queue manager that is running at a level earlier than WebSphere MQ version 7.0.1.

On AIX, HP Open VMS, HP-UX, IBM i, Linux, Solaris, and Windows platforms, the TCP/IP connection name parameter of a cluster-receiver channel is optional. If you leave the connection name blank, WebSphere MQ generates a connection name for you, assuming the default port and using the current IP address of the system. You can override the default port number, but still use the current IP address of the system. For each connection name leave the IP name blank, and provide the port number in parentheses; for example:

 (1415)
The generated CONNAME is always in the dotted decimal (IPv4) or hexadecimal (IPv6) form, rather than in the form of an alphanumeric DNS host name.

Note: If you are using any of the special characters in your connection name (for example, parentheses) you must enclose the string in single quotation marks.

The value you specify depends on the transport type (TRPTYPE) to be used:

LU 6.2

  • On z/OS, there are two forms in which to specify the value:

    Logical unit name

    The logical unit information for the queue manager, comprising the logical unit name, TP name, and optional mode name. Logical unit name can be specified in one of three forms:

    Form Example
    luname IGY12355
    luname/TPname IGY12345/APING
    luname/TPname/modename IGY12345/APINGD/#INTER

    For the first form, the TP name and mode name must be specified for the TPNAME and MODENAME parameters; otherwise these parameters must be blank.

    Note: For client-connection channels, only the first form is allowed.

    Symbolic name

    The symbolic destination name for the logical unit information for the queue manager, as defined in the side information data set. The TPNAME and MODENAME parameters must be blank.

    Note: For cluster-receiver channels, the side information is on the other queue managers in the cluster. Alternatively, in this case it can be a name that a channel auto-definition exit can resolve into the appropriate logical unit information for the local queue manager.

    The specified or implied LU name can be that of a VTAM generic resources group.

  • On IBM i, Windows, UNIX and Linux systems, CONNAME is the name of the CPI-C communications side object or, if the TPNAME is not blank, CONNAME is the fully qualified name of the partner logical unit.

NetBIOS

A unique NetBIOS name (limited to 16 characters).

SPX

The 4 byte network address, the 6 byte node address, and the 2 byte socket number. These values must be entered in hexadecimal, with a period separating the network and node addresses. The socket number must be enclosed in brackets, for example:

 CONNAME('0a0b0c0d.804abcde23a1(5e86)')

TCP

Either the host name, or the network address of the remote machine (or the local machine for cluster-receiver channels). This address can be followed by an optional port number, enclosed in parentheses.

If the CONNAME is a host name, the host name is resolved to an IP address.

The IP stack used for communication depends on the value specified for CONNAME and the value specified for LOCLADDR. See LOCLADDR for information about how this value is resolved.

On z/OS, the connection name can include the IP_name of an z/OS dynamic DNS group or a Network Dispatcher input port. Do not include the IP_name or input port for channels with a channel type (CHLTYPE) of CLUSSDR.

On platforms other than HP Open VMS, when you define a channel with a channel type (CHLTYPE) of CLUSRCVR that is using TCP/IP, you do not need to specify the network address of your queue manager. WebSphere MQ generates a CONNAME for you, assuming the default port and using the current IPv4 address of the system. If the system does not have an IPv4 address, the current IPv6 address of the system is used.

If you are using clustering between IPv6-only and IPv4-only queue managers, do not specify an IPv6 network address as the CONNAME for CLUSRCVR channels. A queue manager that is capable only of IPv4 communication is unable to start a cluster sender channel definition that specifies the CONNAME in IPv6 hexadecimal form. Consider, instead, using host names in a heterogeneous IP environment.

CONVERT

Specifies whether the sending message channel agent attempts conversion of the application message data, if the receiving message channel agent cannot perform this conversion.

NO

No conversion by sender

YES

Conversion by sender

On z/OS, N and Y are accepted as synonyms of NO and YES.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

DEFCDISP

Specifies the default channel disposition of the channel.

PRIVATE

The intended disposition of the channel is as a PRIVATE channel.

FIXSHARED

The intended disposition of the channel is as a FIXSHARED channel.

SHARED

The intended disposition of the channel is as a SHARED channel.

This parameter does not apply to channels with a channel type (CHLTYPE) of CLNTCONN, CLUSSDR, or CLUSRCVR.

DEFRECON

Specifies whether a client connection automatically reconnects a client application if its connection breaks.

NO

Unless overridden by MQCONNX, the client is not reconnected automatically.

YES

Unless overridden by MQCONNX, the client reconnects automatically.

QMGR

Unless overridden by MQCONNX, the client reconnects automatically, but only to the same queue manager. The QMGR option has the same effect as MQCNO_RECONNECT_Q_MGR.

DISABLED

Reconnection is disabled, even if requested by the client program using the MQCONNX MQI call.

Automatic reconnection depends on the values set in the application and in the channel definition

DEFRECON Reconnection options set in the application
  MQCNO_RECONNECT MQCNO_RECONNECT_Q_MGR MQCNO_RECONNECT_AS_DEF MQCNO_RECONNECT_DISABLED
NO YES QMGR NO NO
YES YES QMGR YES NO
QMGR YES QMGR QMGR NO
DISABLED NO NO NO NO

DESCR(string)

Plain-text comment. It provides descriptive information about the channel when an operator issues the DISPLAY CHANNEL command.

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

DISCINT(integer)

The minimum time in seconds for which the channel waits for a message to arrive on the transmission queue, after a batch ends, before terminating the channel. A value of zero causes the message channel agent to wait indefinitely.

The value must be in the range zero through 999 999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SVRCONN , SDR, SVR, CLUSSDR, CLUSRCVR.

For SVRCONN channels using the TCP protocol, this parameter is the minimum time in seconds for which the SVRCONN instance remains active without any communication from its partner client. A value of zero disables this disconnect processing. The SVRCONN inactivity interval only applies between WebSphere MQ API calls from a client, so no client is disconnected during an extended MQGET with wait call. This attribute is ignored for SVRCONN channels using protocols other than TCP.

HBINT(integer)

This attribute specifies the approximate time between heartbeat flows that are to be passed from a sending MCA when there are no messages on the transmission queue.

Heartbeat flows unblock the receiving MCA, which is waiting for messages to arrive or for the disconnect interval to expire. When the receiving MCA is unblocked it can disconnect the channel without waiting for the disconnect interval to expire. Heartbeat flows also free any storage buffers that have been allocated for large messages and close any queues that have been left open at the receiving end of the channel.

The value is in seconds and must be in the range 0 through 999999. A value of zero means that no heartbeat flows are to be sent. The default value is 300. To be most useful, the value needs to be less than the disconnect interval value.

For server-connection and client-connection channels, heartbeats can flow from both the server side as well as the client side independently. If no data has been transferred across the channel for the heartbeat interval, the client-connection MQI agent sends a heartbeat flow and the server-connection MQI agent responds to it with another heartbeat flow. This happens irrespective of the state of the channel, for example, irrespective of whether it is inactive while making an API call, or is inactive waiting for client user input. The server-connection MQI agent is also capable of initiating a heartbeat to the client, again irrespective of the state of the channel. To prevent both server-connection and client-connection MQI agents heart beating to each other at the same time, the server heartbeat is flowed after no data has been transferred across the channel for the heartbeat interval plus 5 seconds.

On server-connection and client-connection channels, heartbeats flow only when a server MCA is waiting for an MQGET command with the WAIT option specified, which it has issued on behalf of a client application.

KAINT(integer)

The value passed to the communications stack for KeepAlive timing for this channel.

For this attribute to be effective, TCP/IP keepalive must be enabled both in the queue manager and in TCP/IP. On z/OS, you enable TCP/IP keepalive in the queue manager by issuing the ALTER QMGR TCPKEEP(YES) command; if the TCPKEEP queue manager parameter is NO, the value is ignored, and the KeepAlive facility is not used. On other platforms, TCP/IP keepalive is enabled when the KEEPALIVE=YES parameter is specified in the TCP stanza in the distributed queuing configuration file, qm.ini, or through the WebSphere MQ Explorer.

Keepalive must also be switched on within TCP/IP itself. Refer to your TCP/IP documentation for information about configuring keepalive. On AIX, use the no command. On HP-UX, use the ndd command. On Windows, edit the registry. On z/OS, update your TCP/IP PROFILE data set and add or change the INTERVAL parameter in the TCPCONFIG section.

Although this parameter is available on all platforms, its setting is implemented only on z/OS. On platforms other than z/OS, you can access and modify the parameter, but it is only stored and forwarded; there is no functional implementation of the parameter. This functionality is useful in a clustered environment where a value set in a cluster-receiver channel definition on Solaris, for example, flows to (and is implemented by) z/OS queue managers that are in, or join, the cluster.

On platforms other than z/OS, if you need the functionality provided by the KAINT parameter, use the Heartbeat Interval (HBINT) parameter, as described in HBINT .

(integer)

The KeepAlive interval to be used, in seconds, in the range 1 through 99 999.

0

The value used is that specified by the INTERVAL statement in the TCP profile configuration data set.

AUTO

The KeepAlive interval is calculated based upon the negotiated heartbeat value as follows:

  • If the negotiated HBINT is greater than zero, KeepAlive interval is set to that value plus 60 seconds.
  • If the negotiated HBINT is zero, the value used is that specified by the INTERVAL statement in the TCP profile configuration data set.

This parameter is valid for all channel types. It is ignored for channels with a TRPTYPE other than TCP or SPX.

LIKE(channel-name)

The name of a channel. The parameters of this channel are used to model this definition.

If this field is not completed, and you do not complete the parameter fields related to the command, the values are taken from one of the following default channels, depending upon the channel type:

SYSTEM.DEF.SENDER

Sender channel

SYSTEM.DEF.SERVER

Server channel

SYSTEM.DEF.RECEIVER

Receiver channel

SYSTEM.DEF.REQUESTER

Requester channel

SYSTEM.DEF.SVRCONN

Server-connection channel

SYSTEM.DEF.CLNTCONN

Client-connection channel

SYSTEM.DEF.CLUSSDR

Cluster-sender channel

SYSTEM.DEF.CLUSRCVR

Cluster-receiver channel

This parameter is equivalent to defining the following object for a sender channel, and similarly for other channel types:

 LIKE(SYSTEM.DEF.SENDER)
These default channel definitions can be altered by the installation to the default values required.

On z/OS, the queue manager searches page set zero for an object with the name you specify and a disposition of QMGR or COPY. The disposition of the LIKE object is not copied to the object and channel type you are defining.

Note:

  1. QSGDISP (GROUP) objects are not searched.
  2. # LIKE is ignored if QSGDISP(COPY) is specified. However, the group object defined is used as a LIKE object.

LOCLADDR(string)

LOCLADDR is the local communications address for the channel. Use this parameter if you want a channel to use a particular IP address, port, or port range for outbound communications. LOCLADDR might be useful in recovery scenarios where a channel is restarted on a different TCP/IP stack. LOCLADDR is also useful to force a channel to use an IPv4 or IPv6 stack on a dual-stack system. You can also use LOCLADDR to force a channel to use a dual-mode stack on a single-stack system.

This parameter is valid only for channels with a transport type (TRPTYPE) of TCP. If TRPTYPE is not TCP, the data is ignored and no error message is issued.

The value is the optional IP address, and optional port or port range used for outbound TCP/IP communications. The format for this information is as follows:

 LOCLADDR([ip-addr][(low-port[,high-port])][,[ip-addr][(low-port[,high-port])]])

The maximum length of LOCLADDR, including multiple addresses, is MQ_LOCAL_ADDRESS_LENGTH.

If you omit LOCLADDR, a local address is automatically allocated.

Note, that you can set LOCLADDR for a C client using the Client Channel Definition Table (CCDT).

All the parameters are optional. Omitting the ip-addr part of the address is useful to enable the configuration of a fixed port number for an IP firewall. Omitting the port number is useful to select a particular network adapter without having the identify a unique local port number. The TCP/IP stack generates a unique port number.

Specify [,[ip-addr][(low-port[,high-port])]] multiple times for each additional local address. Use multiple local addresses if you want to specify a specific subset of local network adapters. You can also use [,[ip-addr][(low-port[,high-port])]] to represent a particular local network address on different servers that are part of a multi-instance queue manager configuration.

ip-addr
ip-addr is specified in one of three forms:

IPv4 dotted decimal

For example 192.0.2.1

IPv6 hexadecimal notation

For example 2001:DB8:0:0:0:0:0:0

Alphanumeric host name form

For example WWW.EXAMPLE.COM
low-port and high-port
low-port and high-port are port numbers enclosed in parentheses.
Table 3 shows how the LOCLADDR parameter can be used:

Examples of how the LOCLADDR parameter can be used

LOCLADDR Meaning
9.20.4.98 Channel binds to this address locally
9.20.4.98, 9.20.4.99 Channel binds to either IP address. The address might be two network adapters on one server, or a different network adapter on two different servers in a multi-instance configuration.
9.20.4.98(1000) Channel binds to this address and port 1000 locally
9.20.4.98(1000,2000) Channel binds to this address and uses a port in the range 1000 - 2000 locally
(1000) Channel binds to port 1000 locally
(1000,2000) Channel binds to port in range 1000 - 2000 locally

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, CLUSSDR, CLUSRCVR, or MQTT.

On CLUSSDR channels, the IP address and port to which the outbound channel binds, is a combination of fields. It is a concatenation of the IP address, as defined in the LOCLADDR parameter, and the port range from the cluster cache. If there is no port range in the cache, the port range defined in the LOCLADDR parameter is used. This port range does not apply to z/OS.

Even though this parameter is similar in form to CONNAME, it must not be confused with it. The LOCLADDR parameter specifies the characteristics of the local communications, whereas the CONNAME parameter specifies how to reach a remote queue manager.

When a channel is started, the values specified for CONNAME and LOCLADDR determine the IP stack to be used for communication; see Table 3 and Local Address (LOCLADDR) .

If the appropriate IP stack for the local address is not installed or configured, the channel fails to start and an error message is generated.

For channels with a channel type (CHLTYPE) of MQTT the usage of this parameter is slightly different. Specifically, a telemetry channel (MQTT) LOCLADDR parameter expects only an IPv4 or IPv6 IP address, or a valid host name as a string. This string must not contain a port number or port range. If an IP address is entered, only the address format is validated. The IP address itself is not validated.

How the IP stack to be used for communication is determined

Protocols supported CONNAME LOCLADDR Action of channel
IPv4 only IPv4 address 1   Channel binds to IPv4 stack
IPv6 address 2   Channel fails to resolve CONNAME
IPv4 and 6 host name 3   Channel binds to IPv4 stack
IPv4 address IPv4 address Channel binds to IPv4 stack
IPv6 address IPv4 address Channel fails to resolve CONNAME
IPv4 and 6 host name IPv4 address Channel binds to IPv4 stack
Any address 4 IPv6 address Channel fails to resolve LOCLADDR
IPv4 address IPv4 and 6 host name Channel binds to IPv4 stack
IPv6 address IPv4 and 6 host name Channel fails to resolve CONNAME
IPv4 and 6 host name IPv4 and 6 host name Channel binds to IPv4 stack
IPv4 and IPv6 IPv4 address   Channel binds to IPv4 stack
IPv6 address   Channel binds to IPv6 stack
IPv4 and 6 host name   Channel binds to stack determined by IPADDRV
IPv4 address IPv4 address Channel binds to IPv4 stack
IPv6 address IPv4 address Channel fails to resolve CONNAME
IPv4 and 6 host name IPv4 address Channel binds to IPv4 stack
IPv4 address IPv6 address Channel maps CONNAME to IPv6 5
IPv6 address IPv6 address Channel binds IPv6 stack
IPv4 and 6 host name IPv6 address Channel binds IPv6 stack
IPv4 address IPv4 and 6 host name Channel binds to IPv4 stack
IPv6 address IPv4 and 6 host name Channel binds to IPv6 stack
IPv4 and 6 host name IPv4 and 6 host name Channel binds to stack determined by IPADDRV
IPv6 only IPv4 address   Channel maps CONNAME to IPv6 5
IPv6 address   Channel binds to IPv6 stack
IPv4 and 6 host name   Channel binds to IPv6 stack
Any address IPv4 address Channel fails to resolve LOCLADDR
IPv4 address IPv6 address Channel maps CONNAME to IPv6 5
IPv6 address IPv6 address Channel binds to IPv6 stack
IPv4 and 6 host name IPv6 address Channel binds to IPv6 stack
IPv4 address IPv4 and 6 host name Channel maps CONNAME to IPv6 5
IPv6 address IPv4 and 6 host name Channel binds to IPv6 stack
IPv4 and 6 host name IPv4 and 6 host name Channel binds to IPv6 stack

Notes:

  1. IPv4 address. An IPv4 host name that resolves only to an IPv4 network address or a specific dotted notation IPv4 address, for example 1.2.3.4. This note applies to all occurrences of 'IPv4 address' in this table.
  2. IPv6 address. An IPv6 host name that resolves only to an IPv6 network address or a specific hexadecimal notation IPv6 address, for example 4321:54bc. This note applies to all occurrences of 'IPv6 address' in this table.
  3. IPv4 and 6 host name. A host name that resolves to both IPv4 and IPv6 network addresses. This note applies to all occurrences of 'IPv4 and 6 host name' in this table.
  4. Any address. IPv4 address, IPv6 address, or IPv4 and 6 host name. This note applies to all occurrences of 'Any address' in this table.
  5. Maps IPv4 CONNAME to IPv4 mapped IPv6 address. IPv6 stack implementations that do not support IPv4 mapped IPv6 addressing fail to resolve the CONNAME. Mapped addresses might require protocol translators in order to be used. The use of mapped addresses is not recommended.

LONGRTY(integer)

When a sender, server, or cluster-sender channel is attempting to connect to the remote queue manager, and the count specified by SHORTRTY has been exhausted, this parameter specifies the maximum number of further attempts that are made to connect to the remote queue manager, at intervals specified by LONGTMR.

If this count is also exhausted without success, an error is logged to the operator, and the channel is stopped. The channel must then be restarted with a command (it is not started automatically by the channel initiator).

The value must be in the range zero through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

LONGTMR(integer)

For long retry attempts, this parameter is the maximum number of seconds to wait before reattempting connection to the remote queue manager.

The time is approximate; zero means that another connection attempt is made as soon as possible.

The interval between retries might be extended if the channel has to wait to become active.

The value must be in the range zero through 999999999.

Note: For implementation reasons, the maximum retry interval that can be used is 999,999; values exceeding this maximum are treated as 999,999. Similarly, the minimum retry interval that can be used is 2; values less than this minimum are treated as 2.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

MAXINST(integer)

The maximum number of simultaneous instances of an individual server-connection channel that can be started.

The value must be in the range zero through 999999999.

A value of zero prevents all client access on this channel.

If the value of this parameter is reduced to a number that is less than the number of instances of the server-connection channel that are currently running, then those running instances are not affected. However, new instances cannot start until sufficient existing instances have ceased to run so that the number of currently running instances is less than the value of this parameter.

On z/OS, without the Client Attachment feature installed, a maximum of five instances are allowed on the channel named SYSTEM.ADMIN.SVRCONN. If MAXINST is set to a larger number than five, it is interpreted as zero without the CAF installed.

This parameter is valid only for channels with a channel type (CHLTYPE) of SVRCONN.

MAXINSTC(integer)

The maximum number of simultaneous individual server-connection channels that can be started from a single client. In this context, connections that originate from the same remote network address are regarded as coming from the same client.

The value must be in the range zero through 999999999.

A value of zero prevents all client access on this channel.

If the value of this parameter is reduced to a number that is less than the number of instances of the server-connection channel that is currently running from individual clients, then those running instances are not affected. However, new instances from those clients cannot start until sufficient instances have ceased to run that the number of running instances is less than the value of this parameter.

On z/OS, without the Client Attachment feature installed, only a maximum of five instances are allowed on the channel named SYSTEM.ADMIN.SVRCONN.

This parameter is valid only for channels with a channel type (CHLTYPE) of SVRCONN.

MAXMSGL(integer)

Specifies the maximum message length that can be transmitted on the channel. This parameter is compared with the value for the partner and the actual maximum used is the lower of the two values. The value is ineffective if the MQCB function is being executed and the channel type (CHLTYPE) is SVRCONN.

The value zero means the maximum message length for the queue manager.

On platforms other than z/OS, specify a value in the range zero through to the maximum message length for the queue manager.

On z/OS, specify a value in the range zero through 104857600 bytes (100 MB).

See the MAXMSGL parameter of the ALTER QMGR command for more information.

MCANAME(string)

Message channel agent name.

This parameter is reserved, and if specified must only be set to blanks (maximum length 20 characters).

MCATYPE

Specifies whether the message-channel-agent program on an outbound message channel runs as a thread or a process.

PROCESS

The message channel agent runs as a separate process.

THREAD

The message channel agent runs as a separate thread

In situations where a threaded listener is required to service many incoming requests, resources can become strained. In this case, use multiple listener processes and target incoming requests at specific listeners though the port number specified on the listener.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLUSSDR, or CLUSRCVR. It is not supported on z/OS.

On z/OS, it is supported only for channels with a channel type of CLUSRCVR. When specified in a CLUSRCVR definition, MCATYPE is used by a remote machine to determine the corresponding CLUSSDR definition.

MCAUSER(string)

Message channel agent user identifier.

Note: An alternative way of providing a user ID for a channel to run under is to use channel authentication records. With channel authentication records, different connections can use the same channel while using different credentials. If both MCAUSER on the channel is set and channel authentication records are used to apply to the same channel, the channel authentication records take precedence. The MCAUSER on the channel definition is only used if the channel authentication record uses USERSRC(CHANNEL). For more details, see Channel authentication records .

This parameter interacts with PUTAUT , see the definition of that parameter for more information.

If it is nonblank, it is the user identifier that is to be used by the message channel agent for authorization to access WebSphere MQ resources, including (if PUTAUT is DEF) authorization to put the message to the destination queue for receiver or requester channels.

If it is blank, the message channel agent uses its default user identifier.

The default user identifier is derived from the user ID that started the receiving channel. The possible values are:

  • On z/OS, the user ID assigned to the channel-initiator started task by the z/OS started-procedures table.
  • For TCP/IP, other than z/OS, the user ID from the inetd.conf entry, or the user that started the listener.
  • For SNA, other than z/OS, the user ID from the SNA server entry or, in the absence of this user ID the incoming attach request, or the user that started the listener.
  • For NetBIOS or SPX, the user ID that started the listener.

The maximum length of the string is 64 characters on Windows and 12 characters on other platforms. On Windows, you can optionally qualify a user identifier with the domain name in the format user@domain.

This parameter is not valid for channels with a channel type (CHLTYPE) of SDR, SVR, CLNTCONN, CLUSSDR.

MODENAME(string)

LU 6.2 mode name (maximum length 8 characters).

This parameter is valid only for channels with a transport type (TRPTYPE) of LU 6.2. If TRPTYPE is not LU 6.2, the data is ignored and no error message is issued.

If specified, this parameter must be set to the SNA mode name unless the CONNAME contains a side-object name, in which case it must be set to blanks. The actual name is then taken from the CPI-C Communications Side Object, or APPC side information data set.

This parameter is not valid for channels with a channel type (CHLTYPE) of RCVR or SVRCONN.

MONCHL

Controls the collection of online monitoring data for channels:

QMGR

Collect monitoring data according to the setting of the queue manager parameter MONCHL.

OFF

Monitoring data collection is turned off for this channel.

LOW

If the value of the queue manager MONCHL parameter is not NONE, online monitoring data collection is turned on, with a low rate of data collection, for this channel.

MEDIUM

If the value of the queue manager MONCHL parameter is not NONE, online monitoring data collection is turned on, with a moderate rate of data collection, for this channel.

HIGH

If the value of the queue manager MONCHL parameter is not NONE, online monitoring data collection is turned on, with a high rate of data collection, for this channel.

Changes to this parameter take effect only on channels started after the change occurs.

For cluster channels, the value of this parameter is not replicated in the repository and, therefore, not used in the auto-definition of cluster-sender channels. For auto-defined cluster-sender channels, the value of this parameter is taken from the queue manager attribute MONACLS. This value might then be overridden in the channel auto-definition exit.

MRDATA(string)

Channel message-retry exit user data. The maximum length is 32 characters.

This parameter is passed to the channel message-retry exit when it is called.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MREXIT(string)

Channel message-retry exit name.

The format and maximum length of the name is the same as for MSGEXIT, however you can only specify one message-retry exit.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MRRTY(integer)

The number of times the channel tries again before it decides it cannot deliver the message.

This parameter controls the action of the MCA only if the message-retry exit name is blank. If the exit name is not blank, the value of MRRTY is passed to the exit to use, but the number of retries performed (if any) is controlled by the exit, and not by this parameter.

The value must be in the range zero through 999999999. A value of zero means that no retries are performed.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MRTMR(integer)

The minimum interval of time that must pass before the channel can try the MQPUT operation again. This time interval is in milliseconds.

This parameter controls the action of the MCA only if the message-retry exit name is blank. If the exit name is not blank, the value of MRTMR is passed to the exit to use, but the retry interval is controlled by the exit, and not by this parameter.

The value must be in the range zero through 999 999 999. A value of zero means that the retry is performed as soon as possible (if the value of MRRTY is greater than zero).

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, or CLUSRCVR.

MSGDATA(string)

User data for the channel message exit. The maximum length is 32 characters.

This data is passed to the channel message exit when it is called.

On AIX, HP-UX, Linux, Solaris, and Windows, you can specify data for more than one exit program by specifying multiple strings separated by commas. The total length of the field must not exceed 999 characters.

On IBM i, you can specify up to 10 strings, each of length 32 characters. The first string of data is passed to the first message exit specified, the second string to the second exit, and so on.

On z/OS, you can specify up to eight strings, each of length 32 characters. The first string of data is passed to the first message exit specified, the second string to the second exit, and so on.

On other platforms, you can specify only one string of message exit data for each channel.

Note: This parameter is accepted but ignored for server-connection and client-connection channels.

MSGEXIT(string)

Channel message exit name.

If this name is nonblank, the exit is called at the following times:

  • Immediately after a message has been retrieved from the transmission queue (sender or server), or immediately before a message is put to a destination queue (receiver or requester).

    The exit is given the entire application message and transmission queue header for modification.

  • At initialization and termination of the channel.

On AIX, HP-UX, Linux, Solaris, and Windows, you can specify the name of more than one exit program by specifying multiple strings separated by commas. However, the total number of characters specified must not exceed 999.

On IBM i, you can specify the names of up to 10 exit programs by specifying multiple strings separated by commas.

On z/OS, you can specify the names of up to eight exit programs by specifying multiple strings separated by commas.

On other platforms, you can specify only one message exit name for each channel.

For channels with a channel type (CHLTYPE) of CLNTCONN or SVRCONN, this parameter is accepted but ignored, because message exits are not invoked for such channels.

The format and maximum length of the name depends on the environment:

  • On UNIX and Linux systems, it is of the form:

          libraryname(functionname)
    
    The maximum length of the string is 128 characters.
  • On Windows, it is of the form:

          dllname(functionname)
    
    where dllname is specified without the suffix (".DLL"). The maximum length of the string is 128 characters.
  • On IBM i, it is of the form:

          progname libname
    
    where program name occupies the first 10 characters and libname the second 10 characters (both padded to the right with blanks if necessary). The maximum length of the string is 20 characters.
  • On z/OS, it is a load module name, maximum length 8 characters (128 characters are allowed for exit names for client-connection channels, subject to a maximum total length including commas of 999).

NETPRTY(integer)

The priority for the network connection. Distributed queuing chooses the path with the highest priority if there are multiple paths available. The value must be in the range zero through 9; zero is the lowest priority.

This parameter is valid only for CLUSRCVR channels.

NPMSPEED

The class of service for nonpersistent messages on this channel:

FAST

Fast delivery for nonpersistent messages; messages might be lost if the channel is lost. Messages are retrieved using MQGMO_SYNCPOINT_IF_PERSISTENT and so are not included in the batch unit of work.

NORMAL

Normal delivery for nonpersistent messages.
If the sending side and the receiving side do not agree about this parameter, or one does not support it, NORMAL is used.

This parameter is valid only for channels with a CHLTYPE of SDR, SVR, RCVR, RQSTR, CLUSSDR, or CLUSRCVR.

PASSWORD(string)

Password used by the message channel agent when attempting to initiate a secure LU 6.2 session with a remote message channel agent. The maximum length is 12 characters.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, or CLUSSDR. On z/OS, it is supported only for channels with a channel type (CHLTYPE) of CLNTCONN.

Although the maximum length of the parameter is 12 characters, only the first 10 characters are used.

PROPCTL

Property control attribute.

Specifies what happens to properties of messages when the message is about to be sent to a V6 or prior queue manager (a queue manager that does not understand the concept of a property descriptor).

This parameter is applicable to Sender, Server, Cluster Sender, and Cluster Receiver channels.

This parameter is optional.

Permitted values are:

COMPAT

COMPAT allows applications which expect JMS-related properties to be in an MQRFH2 header in the message data to continue to work unmodified.

Message properties Result
The message contains a property with a prefix of mcd., jms., usr. or mqext. All optional message properties (where the Support value is MQPD_SUPPORT_OPTIONAL), except properties in the message descriptor or extension, are placed in one or more MQRFH2 headers in the message data before the message it sent to the remote queue manager.
The message does not contain a property with a prefix of mcd., jms., usr. or mqext. All message properties, except properties in the message descriptor or extension, are removed from the message before the message is sent to the remote queue manager.
The message contains a property where the Support field of the property descriptor is not set to MQPD_SUPPORT_OPTIONAL The message is rejected with reason MQRC_UNSUPPORTED_PROPERTY and treated in accordance with its report options.
The message contains one or more properties where the Support field of the property descriptor is set to MQPD_SUPPORT_OPTIONAL but other fields of the property descriptor are set to non-default values. The properties with non-default values are removed from the message before the message is sent to the remote queue manager.
The MQRFH2 folder that would contain the message property needs to be assigned with the content='properties' attribute The properties are removed to prevent MQRFH2 headers with unsupported syntax flowing to a V6 or prior queue manager.

NONE

All properties of the message, except properties in the message descriptor or extension, are removed from the message before the message is sent to the remote queue manager.

If the message contains a property where the Support field of the property descriptor is not set to MQPD_SUPPORT_OPTIONAL then the message is rejected with reason MQRC_UNSUPPORTED_PROPERTY and treated in accordance with its report options.

ALL

All properties of the message are included with the message when it is sent to the remote queue manager. The properties, except properties in the message descriptor (or extension), are placed in one or more MQRFH2 headers in the message data.
PUTAUT

Specifies which user identifiers are used to establish authority to put messages to the destination queue (for messages channels) or to execute an MQI call (for MQI channels).

DEF

The default user ID is used. On z/OS, DEF might involve using both the user ID received from the network and that derived from MCAUSER.

CTX

The user ID from the UserIdentifier field of the message descriptor is used. On z/OS, CTX might involve also using the user ID received from the network or that derived from MCAUSER, or both.

ONLYMCA

The default user ID is used. Any user ID received from the network is not used. This value is supported only on z/OS.

ALTMCA

The user ID from the UserIdentifier field of the message descriptor is used. Any user ID received from the network is not used. This value is supported only on z/OS.

On z/OS, the user IDs that are checked, and how many user IDs are checked, depends on the setting of the MQADMIN RACF class hlq.RESLEVEL profile. Depending on the level of access the user ID of the channel initiator has to hlq.RESLEVEL, zero, one or two user IDs are checked.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, RQSTR, CLUSRCVR, or, on z/OS only, SVRCONN. CTX and ALTMCA are not valid for SVRCONN channels.

QMNAME(string)

Queue manager name.

For channels with a channel type (CHLTYPE) of CLNTCONN, this parameter is the name of a queue manager to which an application that is running in a client environment and using the client channel definition table can request connection. This parameter need not be the name of the queue manager on which the channel is defined, to allow a client to connect to different queue managers.

For channels of other types, this parameter is not valid.

QSGDISP

This parameter applies to z/OS only.

Specifies the disposition of the object to which you are applying the command (that is, where it is defined and how it behaves).

QSGDISP ALTER
COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(COPY). Any object residing in the shared repository, or any object defined using a command that had the parameters QSGDISP(QMGR), is not affected by this command.
GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). Any object residing on the page set of the queue manager that executes the command (except a local copy of the object) is not affected by this command. If the command is successful, the following command is generated and sent to all active queue managers in the queue-sharing group to attempt to refresh local copies on page set zero:

 DEFINE CHANNEL(channel-name) CHLTYPE(type) 
REPLACE QSGDISP(COPY)
The ALTER for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with QSGDISP(QMGR) or QSGDISP(COPY). Any object residing in the shared repository is unaffected.
QMGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(QMGR). Any object residing in the shared repository, or any local copy of such an object, is not affected by this command.

RCVDATA(string)

Channel receive exit user data (maximum length 32 characters).

This parameter is passed to the channel receive exit when it is called.

On AIX, HP-UX, Linux, Solaris, and Windows, you can specify data for more than one exit program by specifying multiple strings separated by commas. The total length of the field must not exceed 999 characters.

On IBM i, you can specify up to 10 strings, each of length 32 characters. The first string of data is passed to the first receive exit specified, the second string to the second exit, and so on.

On z/OS, you can specify up to eight strings, each of length 32 characters. The first string of data is passed to the first receive exit specified, the second string to the second exit, and so on.

On other platforms, you can specify only one string of receive exit data for each channel.

RCVEXIT(string)

Channel receive exit name.

If this name is nonblank, the exit is called at the following times:

  • Immediately before the received network data is processed.

    The exit is given the complete transmission buffer as received. The contents of the buffer can be modified as required.

  • At initialization and termination of the channel.

On AIX, HP-UX, Linux, Solaris, and Windows, you can specify the name of more than one exit program by specifying multiple strings separated by commas. However, the total number of characters specified must not exceed 999.

On IBM i, you can specify the names of up to 10 exit programs by specifying multiple strings separated by commas.

On z/OS, you can specify the names of up to eight exit programs by specifying multiple strings separated by commas.

On other platforms, you can specify only one receive exit name for each channel.

The format and maximum length of the name is the same as for MSGEXIT.

REPLACE and NOREPLACE

Whether the existing definition (and on z/OS, with the same disposition) is to be replaced with this one. This parameter is optional. Any object with a different disposition is not changed.

REPLACE

The definition replaces any existing definition of the same name. If a definition does not exist, one is created. REPLACE does not alter the channel status.

NOREPLACE

The definition does not replace any existing definition of the same name.
SCYDATA(string)

Channel security exit User data (maximum length 32 characters).

This parameter is passed to the channel security exit when it is called.

SCYEXIT(string)

Channel security exit name.

If this name is nonblank, the exit is called at the following times:

  • Immediately after establishing a channel.

    Before any messages are transferred, the exit is able to instigate security flows to validate connection authorization.

  • Upon receipt of a response to a security message flow.

    Any security message flows received from the remote processor on the remote queue manager are given to the exit.

  • At initialization and termination of the channel.

The format and maximum length of the name is the same as for MSGEXIT but only one name is allowed.

SENDDATA(string)

Channel send exit user data. The maximum length is 32 characters.

This parameter is passed to the channel send exit when it is called.

On AIX, HP-UX, Linux, Solaris, and Windows, you can specify data for more than one exit program by specifying multiple strings separated by commas. The total length of the field must not exceed 999 characters.

On IBM i, you can specify up to 10 strings, each of length 32 characters. The first string of data is passed to the first send exit specified, the second string to the second exit, and so on.

On z/OS, you can specify up to eight strings, each of length 32 characters. The first string of data is passed to the first send exit specified, the second string to the second exit, and so on.

On other platforms, you can specify only one string of send exit data for each channel.

SENDEXIT(string)

Channel send exit name.

If this name is nonblank, the exit is called at the following times:

  • Immediately before data is sent out on the network.

    The exit is given the complete transmission buffer before it is transmitted. The contents of the buffer can be modified as required.

  • At initialization and termination of the channel.

On AIX, HP-UX, Linux, Solaris, and Windows, you can specify the name of more than one exit program by specifying multiple strings separated by commas. However, the total number of characters specified must not exceed 999.

On IBM i, you can specify the names of up to 10 exit programs by specifying multiple strings separated by commas.

On z/OS, you can specify the names of up to eight exit programs by specifying multiple strings separated by commas.

On other platforms, you can specify only one send exit name for each channel.

The format and maximum length of the name is the same as for MSGEXIT.

SEQWRAP(integer)

When this value is reached, sequence numbers wrap to start again at 1.

This value is nonnegotiable and must match in both the local and remote channel definitions.

The value must be in the range 100 through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RCVR, RQSTR, CLUSSDR, or CLUSRCVR.

SHARECNV(integer)

Specifies the maximum number of conversations that can be sharing each TCP/IP channel instance. A SHARECNV value of:

1

Specifies no sharing of conversations over a TCP/IP channel instance. Client heartbeating is available whether in an MQGET call or not. Read ahead and client asynchronous consumption are also available, and channel quiescing is more controllable.

0

Specifies no sharing of conversations over a TCP/IP channel instance. The channel instance runs in a mode before that of WebSphere MQ version 7.0, regarding:

  • Administrator stop-quiesce
  • Heartbeating
  • Read ahead
  • Client asynchronous consumption

The value must be in the range zero through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of CLNTCONN or SVRCONN. If the client-connection SHARECNV value does not match the server-connection SHARECNV value, the lower of the two values is used. This parameter is ignored for channels with a transport type (TRPTYPE) other than TCP.

All the conversations on a socket are received by the same thread.

High SHARECNV limits have the advantage of reducing queue manager thread usage. However, if many conversations sharing a socket are all busy, there is a possibility of delays as the conversations contend with one another to use the receiving thread. In this situation, a lower SHARECNV value is better.

The number of shared conversations does not contribute to the MAXINST or MAXINSTC totals.

SHORTRTY(integer)

The maximum number of attempts that are made by a sender, server, or cluster-sender channel to connect to the remote queue manager, at intervals specified by SHORTTMR, before the (normally longer) LONGRTY and LONGTMR are used.

Retry attempts are made if the channel fails to connect initially (whether it is started automatically by the channel initiator or by an explicit command), and also if the connection fails after the channel has successfully connected. However, if the cause of the failure is such that more attempts are unlikely to be successful, they are not attempted.

The value must be in the range zero through 999999999.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

SHORTTMR(integer)

For short retry attempts, this parameter is the maximum number of seconds to wait before reattempting connection to the remote queue manager.

The time is approximate; zero means that another connection attempt is made as soon as possible.

The interval between retries might be extended if the channel has to wait to become active.

The value must be in the range zero through 999999999.

Note: For implementation reasons, the maximum retry interval that can be used is 999999; values exceeding this maximum are treated as 999999. Similarly, the minimum retry interval that can be used is 2; values less than this minimum are treated as 2.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, CLUSSDR, or CLUSRCVR.

SSLCAUTH

Defines whether WebSphere MQ requires a certificate from the SSL client. The initiating end of the channel acts as the SSL client, so this parameter applies to the end of the channel that receives the initiation flow, which acts as the SSL server.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, SVRCONN, CLUSRCVR, SVR, or RQSTR.

The parameter is used only for channels with SSLCIPH specified. If SSLCIPH is blank, the data is ignored and no error message is issued.

REQUIRED

WebSphere MQ requires and validates a certificate from the SSL client.

OPTIONAL

The peer SSL client system might still send a certificate. If it does, the contents of this certificate are validated as normal.
SSLCIPH(string)

SSLCIPH specifies the CipherSpec that is used on the channel. The maximum length is 32 characters. This parameter is valid on all channel types which use transport type TRPTYPE(TCP). If the SSLCIPH parameter is blank, no attempt is made to use SSL on the channel.

Note: When SSLCIPH is used with a telemetry channel, it means SSL Cipher Suite . See the SSLCIPH description in ALTER CHANNEL (MQTT) .

Specify the name of the CipherSpec you are using. The CipherSpecs that can be used with WebSphere MQ SSL support are shown in the following table. The SSLCIPH values must specify the same CipherSpec on both ends of the channel.

A table describing the CipherSpecs you can use with WebSphere MQ SSL and TLS support.

CipherSpec name Protocol used Data integrity Encryption algorithm Encryption bits FIPS 1 Suite B 128 bit Suite B 192 bit
NULL_MD5 a SSL 3.0 MD5 None 0 No No No
NULL_SHA a SSL 3.0 SHA-1 None 0 No No No
RC4_MD5_EXPORT 2 a SSL 3.0 MD5 RC4 40 No No No
RC4_MD5_US a SSL 3.0 MD5 RC4 128 No No No
RC4_SHA_US a SSL 3.0 SHA-1 RC4 128 No No No
RC2_MD5_EXPORT 2 a SSL 3.0 MD5 RC2 40 No No No
DES_SHA_EXPORT 2 a SSL 3.0 SHA-1 DES 56 No No No
RC4_56_SHA_EXPORT1024 3 b SSL 3.0 SHA-1 RC4 56 No No No
DES_SHA_EXPORT1024 3 b SSL 3.0 SHA-1 DES 56 No No No
TRIPLE_DES_SHA_US a SSL 3.0 SHA-1 3DES 168 No No No
TLS_RSA_WITH_AES_128_CBC_SHA a TLS 1.0 SHA-1 AES 128 Yes No No
TLS_RSA_WITH_AES_256_CBC_SHA 4 a TLS 1.0 SHA-1 AES 256 Yes No No
TLS_RSA_WITH_DES_CBC_SHA a TLS 1.0 SHA-1 DES 56 No 5 No No
TLS_RSA_WITH_3DES_EDE_CBC_SHA a 8 TLS 1.0 SHA-1 3DES 168 Yes No No
FIPS_WITH_DES_CBC_SHA b SSL 3.0 SHA-1 DES 56 No 6 No No
FIPS_WITH_3DES_EDE_CBC_SHA b SSL 3.0 SHA-1 3DES 168 No 7 No No
TLS_RSA_WITH_AES_128_GCM_SHA256 b TLS 1.2 AEAD AES-128 GCM AES 128 Yes No No
TLS_RSA_WITH_AES_256_GCM_SHA384 b TLS 1.2 AEAD AES-256 GCM AES 256 Yes No No
TLS_RSA_WITH_AES_128_CBC_SHA256 b TLS 1.2 SHA-256 AES 128 Yes No No
TLS_RSA_WITH_AES_256_CBC_SHA256 b TLS 1.2 SHA-256 AES 256 Yes No No
ECDHE_ECDSA_RC4_128_SHA256 b TLS 1.2 SHA-1 RC4 128 No No No
ECDHE_ECDSA_3DES_EDE_CBC_SHA256 b 8 TLS 1.2 SHA-1 3DES 168 Yes No No
ECDHE_RSA_RC4_128_SHA256 b TLS 1.2 SHA_1 RC4 128 No No No
ECDHE_RSA_3DES_EDE_CBC_SHA256 b 8 TLS 1.2 SHA-1 3DES 168 Yes No No
ECDHE_ECDSA_AES_128_CBC_SHA256 b TLS 1.2 SHA-256 AES 128 Yes No No
ECDHE_ECDSA_AES_256_CBC_SHA384 b TLS 1.2 SHA-384 AES 256 Yes No No
ECDHE_RSA_AES_128_CBC_SHA256 b TLS 1.2 SHA-256 AES 128 Yes No No
ECDHE_RSA_AES_256_CBC_SHA384 b TLS 1.2 SHA-384 AES 256 Yes No No
ECDHE_ECDSA_AES_128_GCM_SHA256 b TLS 1.2 AEAD AES-128 GCM AES 128 Yes Yes No
ECDHE_ECDSA_AES_256_GCM_SHA384 b TLS 1.2 AEAD AES-256 GCM AES 256 Yes No Yes
ECDHE_RSA_AES_128_GCM_SHA256 b TLS 1.2 AEAD AES-128 GCM AES 128 Yes No No
ECDHE_RSA_AES_256_GCM_SHA384 b TLS 1.2 AEAD AES-256 GCM AES 256 Yes No No
TLS_RSA_WITH_NULL_SHA256 b TLS 1.2 SHA-256 None 0 No No No
ECDHE_RSA_NULL_SHA256 b TLS 1.2 SHA-1 None 0 No No No
ECDHE_ECDSA_NULL_SHA256 b TLS 1.2 SHA-1 None 0 No No No
TLS_RSA_WITH_NULL_NULL b TLS 1.2 None None 0 No No No
TLS_RSA_WITH_RC4_128_SHA256 b TLS 1.2 SHA-1 RC4 128 No No No

Notes:

  1. Specifies whether the CipherSpec is FIPS-certified on a FIPS-certified platform. See Federal Information Processing Standards (FIPS) for an explanation of FIPS.
  2. The maximum handshake key size is 512 bits. If either of the certificates exchanged during the SSL handshake has a key size greater than 512 bits, a temporary 512-bit key is generated for use during the handshake.
  3. The handshake key size is 1024 bits.
  4. This CipherSpec cannot be used to secure a connection from the WebSphere MQ Explorer to a queue manager unless the appropriate unrestricted policy files are applied to the JRE used by the Explorer.
  5. This CipherSpec was FIPS 140-2 certified before 19 May 2007.
  6. This CipherSpec was FIPS 140-2 certified before 19 May 2007. The name FIPS_WITH_DES_CBC_SHA is historical and reflects the fact that this CipherSpec was previously (but is no longer) FIPS-compliant. This CipherSpec is deprecated and its use is not recommended.
  7. The name FIPS_WITH_3DES_EDE_CBC_SHA is historical and reflects the fact that this CipherSpec was previously (but is no longer) FIPS-compliant. The use of this CipherSpec is deprecated.
  8. When WebSphere MQ is configured for FIPS 140-2 compliant operation, this CipherSpec can be used to transfer up to 32 GB of data before the connection is terminated with error AMQ9288. To avoid this error, either avoid using triple DES, or enable secret key reset when using this CipherSpec in a FIPS 140-2 configuration.


Platform support:

a  Available on all supported platforms.
b  Available only on UNIX, Linux, and Windows platforms.
  Available only on IBM i platforms.

When you request a personal certificate, you specify a key size for the public and private key pair. The key size that is used during the SSL handshake can depend on the size stored in the certificate and on the CipherSpec:

  • On z/OS, Windows, UNIX and Linux systems, when a CipherSpec name includes _EXPORT, the maximum handshake key size is 512 bits. If either of the certificates exchanged during the SSL handshake has a key size greater than 512 bits, a temporary 512-bit key is generated for use during the handshake.
  • On Windows, UNIX and Linux systems, when a CipherSpec name includes _EXPORT1024, the handshake key size is 1024 bits.
  • Otherwise the handshake key size is the size stored in the certificate.

SSLPEER(string)

Specifies the filter to use to compare with the Distinguished Name of the certificate from the peer queue manager or client at the other end of the channel. (A Distinguished Name is the identifier of the SSL certificate.) If the Distinguished Name in the certificate received from the peer does not match the SSLPEER filter, the channel does not start.

Note: An alternative way of restricting connections into channels by matching against the SSL or TLS Subject Distinguished Name, is to use channel authentication records. With channel authentication records, different SSL or TLS Subject Distinguished Name patterns can be applied to the same channel. If both SSLPEER on the channel and a channel authentication record are used to apply to the same channel, the inbound certificate must match both patterns in order to connect. For more information, see Channel authentication records .

This parameter is optional; if it is not specified, the Distinguished Name of the peer is not checked at channel start up. (The Distinguished Name from the certificate is still written into the SSLPEER definition held in memory, and passed to the security exit). If SSLCIPH is blank, the data is ignored and no error message is issued.

This parameter is valid for all channel types.

The SSLPEER value is specified in the standard form used to specify a Distinguished Name. For example:

 SSLPEER('SERIALNUMBER=4C:D0:49:D5:02:5F:38,CN="H1_C_FR1",O=IBM,C=GB')

You can use a semi-colon as a separator instead of a comma.

The possible attribute types supported are:

Attribute types supported by SSLPEER.

A two column table descibing the attributes supported by the SSLPEER attribute

Summary attribute Description
SERIALNUMBER Certificate serial number
MAIL Email address
E Email address (Deprecated in preference to MAIL)
UID or USERID User identifier
CN Common Name
T Title
OU Organizational Unit name
DC Domain component
O Organization name
STREET Street / First line of address
L Locality name
ST (or SP or S) State or Province name
PC Postal code / zip code
C Country
UNSTRUCTUREDNAME Host name
UNSTRUCTUREDADDRESS IP address
DNQ Distinguished name qualifier
WebSphere MQ accepts only uppercase letters for the attribute types.

If any of the unsupported attribute types are specified in the SSLPEER string, an error is output either when the attribute is defined or at run time (depending on which platform you are running on), and the string is deemed not to have matched the Distinguished Name of the flowed certificate.

If the Distinguished Name of the flowed certificate contains multiple OU (organizational unit) attributes, and SSLPEER specifies these attributes to be compared, they must be defined in descending hierarchical order. For example, if the Distinguished Name of the flowed certificate contains the OUs OU=Large Unit, OU=Medium Unit, OU=Small Unit, specifying the following SSLPEER values works:

 ('OU=Large Unit,OU=Medium Unit')
('OU=*,OU=Medium Unit,OU=Small Unit')
('OU=*,OU=Medium Unit')

but specifying the following SSLPEER values fails:

 ('OU=Medium Unit,OU=Small Unit')
('OU=Large Unit,OU=Small Unit')
('OU=Medium Unit')
('OU=Small Unit, Medium Unit, Large Unit')

As indicated in these examples, attributes at the low end of the hierarchy can be omitted. For example, ('OU=Large Unit,OU=Medium Unit') is equivalent to ('OU=Large Unit,OU=Medium Unit,OU=*')

If two DNs are equal in all respects except for their DC values, the same matching rules apply as for OUs except that in DC values the left-most DC is the lowest-level (most specific) and the comparison ordering differs accordingly.

Any or all the attribute values can be generic, either an asterisk (*) on its own, or a stem with initiating or trailing asterisks. Asterisks allow the SSLPEER to match any Distinguished Name value, or any value starting with the stem for that attribute.

If an asterisk is specified at the beginning or end of any attribute value in the Distinguished Name on the certificate, you can specify '\*' to check for an exact match in SSLPEER. For example, if you have an attribute of CN='Test*' in the Distinguished Name of the certificate, you can use the following command:

 SSLPEER('CN=Test\*')

The maximum length of the parameter is 1024 bytes on Windows, IBM i, UNIX and Linux platforms, and 256 bytes on z/OS.

STATCHL

Controls the collection of statistics data for channels:

QMGR

The value of the STATCHL parameter of the queue manager is inherited by the channel.

OFF

Statistics data collection is turned off for this channel.

LOW

If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on, with a low rate of data collection, for this channel.

MEDIUM

If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on, with a moderate rate of data collection, for this channel.

HIGH

If the value of the STATCHL parameter of the queue manager is not NONE, statistics data collection is turned on, with a high rate of data collection, for this channel.

Changes to this parameter take effect only on channels started after the change occurs.

For cluster channels, the value of this parameter is not replicated in the repository and used in the auto-definition of cluster-sender channels. For auto-defined cluster-sender channels, the value of this parameter is taken from the attribute STATACLS of the queue manager. This value might then be overridden in the channel auto-definition exit.

This parameter is valid only on AIX, IBM i, HP-UX, Linux, Solaris, and Windows.

TPNAME(string)

LU 6.2 transaction program name (maximum length 64 characters).

This parameter is valid only for channels with a transport type (TRPTYPE) of LU 6.2.

Set this parameter to the SNA transaction program name, unless the CONNAME contains a side-object name in which case set it to blanks. The actual name is taken instead from the CPI-C Communications Side Object, or the APPC side information data set.

On Windows SNA Server, and in the side object on z/OS, the TPNAME is wrapped to uppercase.

This parameter is not valid for channels with a channel type (CHLTYPE) of RCVR.

TRPTYPE

Transport type to be used.

On AIX, IBM i, HP-UX, Linux, Solaris, and Windows, and z/OS, this parameter is optional because, if you do not enter a value, the value specified in the SYSTEM.DEF.channel-type definition is used. However, no check is made that the correct transport type has been specified if the channel is initiated from the other end. On z/OS, if the SYSTEM.DEF.channel-type definition does not exist, the default is LU62.

This parameter is required on all other platforms.

LU62

SNA LU 6.2

NETBIOS

NetBIOS (supported only on Windows, and DOS; it also applies to z/OS for defining client-connection channels that connect to servers on the platforms supporting NetBIOS)

SPX

Sequenced packet exchange (supported only on Windows, and DOS; it also applies to z/OS for defining client-connection channels that connect to servers on the platforms supporting SPX)

TCP

Transmission Control Protocol - part of the TCP/IP protocol suite
USEDLQ

Determines whether the dead-letter queue is used when messages cannot be delivered by channels.

NO

Messages that cannot be delivered by a channel are treated as a failure. The channel either discards the message, or the channel ends, in accordance with the NPMSPEED setting.

YES

When the DEADQ queue manager attribute provides the name of a dead-letter queue, then it is used, else the behavior is as for NO. YES is the default value.
USERID(string)

Task user identifier. The maximum length is 12 characters.

This parameter is used by the message channel agent when attempting to initiate a secure LU 6.2 session with a remote message channel agent.

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, or CLUSSDR. On z/OS, it is supported only for CLNTCONN channels.

Although the maximum length of the parameter is 12 characters, only the first 10 characters are used.

On the receiving end, if passwords are kept in encrypted format and the LU 6.2 software is using a different encryption method, an attempt to start the channel fails with invalid security details. You can avoid invalid security details by modifying the receiving SNA configuration to either:

  • Turn off password substitution, or
  • Define a security user ID and password.

XMITQ(string)

Transmission queue name.

The name of the queue from which messages are retrieved. See Rules for naming WebSphere MQ objects .

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR or SVR. For these channel types, this parameter is required.


Sender channel

Syntax diagram for a sender channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

                                                         (1)   
>>-ALTER CHANNEL--(-- channel-name--)--CHLTYPE--(--SDR--)-------->

>--+------------------------+----------------------------------->
   '-BATCHHB--(-- integer--)-'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-BATCHINT--(-- integer--)-----'   

>--+------------------------+----------------------------------->
   '-BATCHSZ--(-- integer--)-'   

   .-CMDSCOPE(' ')-----------------. (4)   
>--+-------------------------------+---------------------------->
   |                           (3) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (3)               |       
   '-CMDSCOPE(*)-------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   '-ZLIBHIGH-'          

>--+-----------------------+--+------------------------+-------->
   '-CONNAME--(-- string--)-'  '-CONVERT--(--+-NO--+--)-'   
                                            '-YES-'        

                                     (4)   
>--+-------------------------------+---------------------------->
   '-DEFCDISP--(--+-PRIVATE---+--)-'       
                  +-FIXSHARED-+            
                  '-SHARED----'            

>--+---------------------+--+------------------------+---------->
   '-DESCR--(-- string--)-'  '-DISCINT--(-- integer--)-'   

>--+--------------------------+--+--------------------------+--->
   |                      (2) |  '-KAINT--(--+- integer-+--)-'   
   '-HBINT--(-- integer--)-----'              '-AUTO----'        

>--+------------------------+--+------------------------+------->
   '-LOCLADDR--(-- string--)-'  '-LONGRTY--(-- integer--)-'   

>--+------------------------+--+------------------------+------->
   '-LONGTMR--(-- integer--)-'  '-MAXMSGL--(-- integer--)-'   

>--+-----------------------+------------------------------------>
   '-MCANAME--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |                            (5) |   
   '-MCATYPE--(--+-PROCESS-+--)-----'   
                 '-THREAD--'            

>--+-----------------------+--+----------------------------+---->
   '-MCAUSER--(-- string--)-'  |                        (6) |   
                              '-MODENAME--(-- string--)-----'   

>--+--------------------------+--------------------------------->
   '-MONCHL--(--+-QMGR---+--)-'   
                +-OFF----+        
                +-LOW----+        
                +-MEDIUM-+        
                '-HIGH---'        

>--+-------------------------------+---------------------------->
   |             .-+---+--.        |   
   |             | '-,-'  |        |   
   |             V        |    (7) |   
   '-MSGDATA--(---- string-+--)-----'   

>--+-------------------------------+---------------------------->
   |             .-+---+--.        |   
   |             | '-,-'  |        |   
   |             V        |    (7) |   
   '-MSGEXIT--(---- string-+--)-----'   

>--+--------------------------------+--------------------------->
   |                            (2) |   
   '-NPMSPEED--(--+-FAST---+--)-----'   
                  '-NORMAL-'            

>--+--------------------------------+--------------------------->
   |                        (6) (8) |   
   '-PASSWORD--(-- string--)---------'   

                                  .-QSGDISP(QMGR)------. (4)   
>--+---------------------------+--+--------------------+-------->
   '-PROPCTL--(--+-ALL----+--)-'  +-QSGDISP(COPY)------+       
                 +-NONE---+       |                (3) |       
                 '-COMPAT-'       +-QSGDISP(GROUP)-----+       
                                  '-QSGDISP(PRIVATE)---'       

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-RCVDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-RCVEXIT--(---- string-----+--)-'   

>--+-----------------------+--+-----------------------+--------->
   '-SCYDATA--(-- string--)-'  '-SCYEXIT--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+--.        |   
   |              | '-,-'  |        |   
   |              V        |    (7) |   
   '-SENDDATA--(---- string-+--)-----'   

>--+--------------------------------+--------------------------->
   |              .-+---+--.        |   
   |              | '-,-'  |        |   
   |              V        |    (7) |   
   '-SENDEXIT--(---- string-+--)-----'   

>--+------------------------+--+-------------------------+------>
   '-SEQWRAP--(-- integer--)-'  '-SHORTRTY--(-- integer--)-'   

>--+-------------------------+--+-----------------------+------->
   '-SHORTTMR--(-- integer--)-'  '-SSLCIPH--(-- string--)-'   

>--+-----------------------+------------------------------------>
   '-SSLPEER--(-- string--)-'   

                                 (9)   
>--+---------------------------+-------------------------------->
   '-STATCHL--(--+-QMGR---+--)-'       
                 +-OFF----+            
                 +-LOW----+            
                 +-MEDIUM-+            
                 '-HIGH---'            

>--+--------------------------+--------------------------------->
   |                      (6) |   
   '-TPNAME--(-- string--)-----'   

>--+---------------------------------+-------------------------->
   |                      (10)       |   
   '-TRPTYPE--(--+-DECNET-------+--)-'   
                 +-LU62---------+        
                 |         (11) |        
                 +-NETBIOS------+        
                 |     (11)     |        
                 +-SPX----------+        
                 '-TCP----------'        

>--+-----------------------+------------------------------------>
   '-USEDLQ--(--+-NO--+--)-'   
                '-YES-'        

>--+------------------------------+--+---------------------+---><
   |                      (6) (8) |  '-XMITQ--(-- string--)-'   
   '-USERID--(-- string--)---------'                            


Notes:

  1. This parameter must follow immediately after the channel name except on z/OS.
  2. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows and z/OS.
  3. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  4. Valid only on z/OS.
  5. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, and Windows.
  6. Valid only if TRPTYPE is LU62.
  7. You can specify more than one value on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS only.
  8. Not valid on z/OS.
  9. This parameter is valid only on AIX, HP-UX, Linux, IBM i, Solaris, and Windows.
  10. Valid only on HP OpenVMS.
  11. Valid only Windows.

The parameters are described in ALTER CHANNEL .


Server channel

Syntax diagram for a server channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

                                                         (1)   
>>-ALTER CHANNEL--(-- channel-name--)--CHLTYPE--(--SVR--)-------->

>--+-------------------------------+---------------------------->
   '-AUTOSTART--(--+-DISABLED-+--)-'   
                   '-ENABLED--'        

>--+------------------------+----------------------------------->
   '-BATCHHB--(-- integer--)-'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-BATCHINT--(-- integer--)-----'   

>--+------------------------+----------------------------------->
   '-BATCHSZ--(-- integer--)-'   

   .-CMDSCOPE(' ')-----------------. (4)   
>--+-------------------------------+---------------------------->
   |                           (3) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (3)               |       
   '-CMDSCOPE(*)-------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   '-ZLIBHIGH-'          

>--+-----------------------+--+------------------------+-------->
   '-CONNAME--(-- string--)-'  '-CONVERT--(--+-NO--+--)-'   
                                            '-YES-'        

                                     (4)   
>--+-------------------------------+---------------------------->
   '-DEFCDISP--(--+-PRIVATE---+--)-'       
                  +-FIXSHARED-+            
                  '-SHARED----'            

>--+---------------------+--+------------------------+---------->
   '-DESCR--(-- string--)-'  '-DISCINT--(-- integer--)-'   

>--+--------------------------+--+--------------------------+--->
   |                      (2) |  '-KAINT--(--+- integer-+--)-'   
   '-HBINT--(-- integer--)-----'              '-AUTO----'        

>--+------------------------+--+------------------------+------->
   '-LOCLADDR--(-- string--)-'  '-LONGRTY--(-- integer--)-'   

>--+------------------------+--+------------------------+------->
   '-LONGTMR--(-- integer--)-'  '-MAXMSGL--(-- integer--)-'   

>--+-----------------------+------------------------------------>
   '-MCANAME--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |                            (5) |   
   '-MCATYPE--(--+-PROCESS-+--)-----'   
                 '-THREAD--'            

>--+-----------------------+--+----------------------------+---->
   '-MCAUSER--(-- string--)-'  |                        (6) |   
                              '-MODENAME--(-- string--)-----'   

>--+--------------------------+--------------------------------->
   '-MONCHL--(--+-QMGR---+--)-'   
                +-OFF----+        
                +-LOW----+        
                +-MEDIUM-+        
                '-HIGH---'        

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-MSGDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-MSGEXIT--(---- string-----+--)-'   

>--+--------------------------------+--------------------------->
   |                            (2) |   
   '-NPMSPEED--(--+-FAST---+--)-----'   
                  '-NORMAL-'            

>--+--------------------------------+--------------------------->
   |                        (6) (8) |   
   '-PASSWORD--(-- string--)---------'   

                                  .-QSGDISP(QMGR)------. (4)   
>--+---------------------------+--+--------------------+-------->
   '-PROPCTL--(--+-ALL----+--)-'  +-QSGDISP(COPY)------+       
                 +-NONE---+       |                (3) |       
                 '-COMPAT-'       +-QSGDISP(GROUP)-----+       
                                  '-QSGDISP(PRIVATE)---'       

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-RCVDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-RCVEXIT--(---- string-----+--)-'   

>--+-----------------------+--+-----------------------+--------->
   '-SCYDATA--(-- string--)-'  '-SCYEXIT--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (7) |    |   
   '-SENDDATA--(---- string-----+--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (7) |    |   
   '-SENDEXIT--(---- string-----+--)-'   

>--+------------------------+--+-------------------------+------>
   '-SEQWRAP--(-- integer--)-'  '-SHORTRTY--(-- integer--)-'   

>--+-------------------------+---------------------------------->
   '-SHORTTMR--(-- integer--)-'   

>--+------------------------------+----------------------------->
   '-SSLCAUTH--(--+-OPTIONAL-+--)-'   
                  '-REQUIRED-'        

>--+-----------------------+--+-----------------------+--------->
   '-SSLCIPH--(-- string--)-'  '-SSLPEER--(-- string--)-'   

                                 (9)   
>--+---------------------------+-------------------------------->
   '-STATCHL--(--+-QMGR---+--)-'       
                 +-OFF----+            
                 +-LOW----+            
                 +-MEDIUM-+            
                 '-HIGH---'            

>--+--------------------------+--------------------------------->
   |                      (6) |   
   '-TPNAME--(-- string--)-----'   

>--+---------------------------------+-------------------------->
   |                      (10)       |   
   '-TRPTYPE--(--+-DECNET-------+--)-'   
                 +-LU62---------+        
                 |         (11) |        
                 +-NETBIOS------+        
                 |     (11)     |        
                 +-SPX----------+        
                 '-TCP----------'        

>--+-----------------------+------------------------------------>
   '-USEDLQ--(--+-NO--+--)-'   
                '-YES-'        

>--+------------------------------+--+---------------------+---><
   |                      (6) (8) |  '-XMITQ--(-- string--)-'   
   '-USERID--(-- string--)---------'                            


Notes:

  1. This parameter must follow immediately after the channel name except on z/OS.
  2. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows and z/OS.
  3. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  4. Valid only on z/OS.
  5. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, and Windows.
  6. Valid only if TRPTYPE is LU62.
  7. You can specify more than one value on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS only.
  8. Not valid on z/OS.
  9. This parameter is valid only on AIX, HP-UX, Linux, IBM i, Solaris, and Windows.
  10. Valid only on HP OpenVMS.
  11. Valid only on Windows.

The parameters are described in ALTER CHANNEL .


Receiver channel

Syntax diagram for a receiver channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

                                                          (1)   
>>-ALTER CHANNEL--(-- channel-name--)--CHLTYPE--(--RCVR--)------->

>--+-------------------------------+---------------------------->
   '-AUTOSTART--(--+-DISABLED-+--)-'   
                   '-ENABLED--'        

>--+------------------------+----------------------------------->
   '-BATCHSZ--(-- integer--)-'   

   .-CMDSCOPE(' ')-----------------. (3)   
>--+-------------------------------+---------------------------->
   |                           (2) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (2)               |       
   '-CMDSCOPE(*)-------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   +-ZLIBHIGH-+          
                   '-ANY------'          

                                     (3)   
>--+-------------------------------+---------------------------->
   '-DEFCDISP--(--+-PRIVATE---+--)-'       
                  +-FIXSHARED-+            
                  '-SHARED----'            

>--+---------------------+--+--------------------------+-------->
   '-DESCR--(-- string--)-'  |                      (4) |   
                            '-HBINT--(-- integer--)-----'   

>--+--------------------------+--+------------------------+----->
   '-KAINT--(--+- integer-+--)-'  '-MAXMSGL--(-- integer--)-'   
               '-AUTO----'                                    

>--+-----------------------+--+--------------------------+------>
   '-MCAUSER--(-- string--)-'  '-MONCHL--(--+-QMGR---+--)-'   
                                           +-OFF----+        
                                           +-LOW----+        
                                           +-MEDIUM-+        
                                           '-HIGH---'        

>--+----------------------+--+----------------------+----------->
   '-MRDATA--(-- string--)-'  '-MREXIT--(-- string--)-'   

>--+----------------------+--+----------------------+----------->
   '-MRRTY--(-- integer--)-'  '-MRTMR--(-- integer--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (5) |    |   
   '-MSGDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (5) |    |   
   '-MSGEXIT--(---- string-----+--)-'   

>--+--------------------------------+--------------------------->
   |                            (4) |   
   '-NPMSPEED--(--+-FAST---+--)-----'   
                  '-NORMAL-'            

>--+-------------------------------+---------------------------->
   '-PUTAUT--(--+-DEF---------+--)-'   
                +-CTX---------+        
                |         (3) |        
                +-ONLYMCA-----+        
                |        (3)  |        
                '-ALTMCA------'        

   .-QSGDISP(QMGR)------. (3)   
>--+--------------------+--------------------------------------->
   +-QSGDISP(COPY)------+       
   |                (2) |       
   +-QSGDISP(GROUP)-----+       
   '-QSGDISP(PRIVATE)---'       

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (5) |    |   
   '-RCVDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (5) |    |   
   '-RCVEXIT--(---- string-----+--)-'   

>--+-----------------------+--+-----------------------+--------->
   '-SCYDATA--(-- string--)-'  '-SCYEXIT--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (5) |    |   
   '-SENDDATA--(---- string-----+--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (5) |    |   
   '-SENDEXIT--(---- string-----+--)-'   

>--+------------------------+----------------------------------->
   '-SEQWRAP--(-- integer--)-'   

>--+------------------------------+----------------------------->
   '-SSLCAUTH--(--+-OPTIONAL-+--)-'   
                  '-REQUIRED-'        

>--+-----------------------+--+-----------------------+--------->
   '-SSLCIPH--(-- string--)-'  '-SSLPEER--(-- string--)-'   

                                 (6)   
>--+---------------------------+-------------------------------->
   '-STATCHL--(--+-QMGR---+--)-'       
                 +-OFF----+            
                 +-LOW----+            
                 +-MEDIUM-+            
                 '-HIGH---'            

>--+--------------------------------+--------------------------->
   |                      (7)       |   
   '-TRPTYPE--(--+-DECNET------+--)-'   
                 +-LU62--------+        
                 |         (8) |        
                 +-NETBIOS-----+        
                 |     (8)     |        
                 +-SPX---------+        
                 '-TCP---------'        

>--+-----------------------+-----------------------------------><
   '-USEDLQ--(--+-NO--+--)-'   
                '-YES-'        


Notes:

  1. This parameter must follow immediately after the channel name except on z/OS.
  2. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  3. Valid only on z/OS.
  4. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS.
  5. You can specify more than one value on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS only.
  6. This parameter is valid only on AIX, HP-UX, Linux, IBM i, Solaris, and Windows.
  7. Valid only on HP OpenVMS.
  8. Valid only on Windows.

The parameters are described in ALTER CHANNEL .


Requester channel

Syntax diagram for a requester channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

>>-ALTER CHANNEL--(-- channel-name--)---------------------------->

                        (1)   
>--CHLTYPE--(--RQSTR--)----------------------------------------->

>--+-------------------------------+---------------------------->
   '-AUTOSTART--(--+-DISABLED-+--)-'   
                   '-ENABLED--'        

>--+------------------------+----------------------------------->
   '-BATCHSZ--(-- integer--)-'   

   .-CMDSCOPE(' ')-----------------. (3)   
>--+-------------------------------+---------------------------->
   |                           (2) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (2)               |       
   '-CMDSCOPE(*)-------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   +-ZLIBHIGH-+          
                   '-ANY------'          

>--+-----------------------+------------------------------------>
   '-CONNAME--(-- string--)-'   

                                     (3)   
>--+-------------------------------+---------------------------->
   '-DEFCDISP--(--+-PRIVATE---+--)-'       
                  +-FIXSHARED-+            
                  '-SHARED----'            

>--+---------------------+--+--------------------------+-------->
   '-DESCR--(-- string--)-'  |                      (4) |   
                            '-HBINT--(-- integer--)-----'   

>--+--------------------------+--+------------------------+----->
   '-KAINT--(--+- integer-+--)-'  '-LOCLADDR--(-- string--)-'   
               '-AUTO----'                                    

>--+------------------------+--+-----------------------+-------->
   '-MAXMSGL--(-- integer--)-'  '-MCANAME--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |                            (5) |   
   '-MCATYPE--(--+-PROCESS-+--)-----'   
                 '-THREAD--'            

>--+-----------------------+--+----------------------------+---->
   '-MCAUSER--(-- string--)-'  |                        (6) |   
                              '-MODENAME--(-- string--)-----'   

>--+--------------------------+--+----------------------+------->
   '-MONCHL--(--+-QMGR---+--)-'  '-MRDATA--(-- string--)-'   
                +-OFF----+                                  
                +-LOW----+                                  
                +-MEDIUM-+                                  
                '-HIGH---'                                  

>--+----------------------+--+----------------------+----------->
   '-MREXIT--(-- string--)-'  '-MRRTY--(-- integer--)-'   

>--+----------------------+------------------------------------->
   '-MRTMR--(-- integer--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-MSGDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-MSGEXIT--(---- string-----+--)-'   

>--+--------------------------------+--------------------------->
   |                            (4) |   
   '-NPMSPEED--(--+-FAST---+--)-----'   
                  '-NORMAL-'            

>--+--------------------------------+--------------------------->
   |                        (8) (6) |   
   '-PASSWORD--(-- string--)---------'   

>--+-------------------------------+---------------------------->
   '-PUTAUT--(--+-DEF---------+--)-'   
                +-CTX---------+        
                |         (3) |        
                +-ONLYMCA-----+        
                |        (3)  |        
                '-ALTMCA------'        

   .-QSGDISP(QMGR)------. (3)   
>--+--------------------+--------------------------------------->
   +-QSGDISP(COPY)------+       
   |                (2) |       
   +-QSGDISP(GROUP)-----+       
   '-QSGDISP(PRIVATE)---'       

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-RCVDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (7) |    |   
   '-RCVEXIT--(---- string-----+--)-'   

>--+-----------------------+--+-----------------------+--------->
   '-SCYDATA--(-- string--)-'  '-SCYEXIT--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (7) |    |   
   '-SENDDATA--(---- string-----+--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (7) |    |   
   '-SENDEXIT--(---- string-----+--)-'   

>--+------------------------+----------------------------------->
   '-SEQWRAP--(-- integer--)-'   

>--+------------------------------+----------------------------->
   '-SSLCAUTH--(--+-OPTIONAL-+--)-'   
                  '-REQUIRED-'        

>--+-----------------------+--+-----------------------+--------->
   '-SSLCIPH--(-- string--)-'  '-SSLPEER--(-- string--)-'   

                                 (9)   
>--+---------------------------+-------------------------------->
   '-STATCHL--(--+-QMGR---+--)-'       
                 +-OFF----+            
                 +-LOW----+            
                 +-MEDIUM-+            
                 '-HIGH---'            

>--+--------------------------+--------------------------------->
   |                      (6) |   
   '-TPNAME--(-- string--)-----'   

>--+---------------------------------+-------------------------->
   |                      (10)       |   
   '-TRPTYPE--(--+-DECNET-------+--)-'   
                 +-LU62---------+        
                 |         (11) |        
                 +-NETBIOS------+        
                 |     (11)     |        
                 +-SPX----------+        
                 '-TCP----------'        

>--+-----------------------+------------------------------------>
   '-USEDLQ--(--+-NO--+--)-'   
                '-YES-'        

>--+------------------------------+----------------------------><
   |                      (8) (6) |   
   '-USERID--(-- string--)---------'   


Notes:

  1. This parameter must follow immediately after the channel name except on z/OS.
  2. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  3. Valid only on z/OS.
  4. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS.
  5. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, and Windows.
  6. Valid only if TRPTYPE is LU62.
  7. You can specify more than one value on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS only.
  8. Not valid on z/OS.
  9. This parameter is valid only on AIX, HP-UX, Linux, IBM i, Solaris, and Windows.
  10. Valid only on HP OpenVMS.
  11. Valid only on Windows.

The parameters are described in ALTER CHANNEL .


Client-connection channel

Syntax diagram for a client-connection channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

>>-ALTER CHANNEL--(-- channel-name--)---------------------------->

                           (1)   
>--CHLTYPE--(--CLNTCONN--)-------------------------------------->

>--+-------------------------------+---------------------------->
   '-AFFINITY--(--+-PREFERRED-+--)-'   
                  '-NONE------'        

>--+-------------------------+---------------------------------->
   '-CLNTWGHT--(-- integer--)-'   

   .-CMDSCOPE(' ')-----------------. (3)   
>--+-------------------------------+---------------------------->
   |                           (2) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (2)               |       
   '-CMDSCOPE(*)-------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   '-ZLIBHIGH-'          

>--+-----------------------+--+---------------------+----------->
   '-CONNAME--(-- string--)-'  '-DESCR--(-- string--)-'   

>--+--------------------------+--+--------------------------+--->
   |                      (4) |  '-KAINT--(--+- integer-+--)-'   
   '-HBINT--(-- integer--)-----'              '-AUTO----'        

>--+------------------------+--+------------------------+------->
   '-LOCLADDR--(-- string--)-'  '-MAXMSGL--(-- integer--)-'   

>--+----------------------------+------------------------------->
   |                        (5) |   
   '-MODENAME--(-- string--)-----'   

>--+----------------------------+--+----------------------+----->
   |                        (5) |  '-QMNAME--(-- string--)-'   
   '-PASSWORD--(-- string--)-----'                             

   .-QSGDISP(QMGR)------. (3)   
>--+--------------------+--------------------------------------->
   +-QSGDISP(COPY)------+       
   |                (2) |       
   +-QSGDISP(GROUP)-----+       
   '-QSGDISP(PRIVATE)---'       

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (6) |    |   
   '-RCVDATA--(---- string-----+--)-'   

>--+-------------------------------+---------------------------->
   |             .-+---+------.    |   
   |             | '-,-'      |    |   
   |             V        (6) |    |   
   '-RCVEXIT--(---- string-----+--)-'   

>--+-----------------------+--+-----------------------+--------->
   '-SCYDATA--(-- string--)-'  '-SCYEXIT--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (6) |    |   
   '-SENDDATA--(---- string-----+--)-'   

>--+--------------------------------+--------------------------->
   |              .-+---+------.    |   
   |              | '-,-'      |    |   
   |              V        (6) |    |   
   '-SENDEXIT--(---- string-----+--)-'   

>--+-------------------------+--+-----------------------+------->
   '-SHARECNV--(-- integer--)-'  '-SSLCIPH--(-- string--)-'   

>--+-----------------------+--+--------------------------+------>
   '-SSLPEER--(-- string--)-'  |                      (5) |   
                              '-TPNAME--(-- string--)-----'   

>--+--------------------------------+--------------------------->
   |                      (7)       |   
   '-TRPTYPE--(--+-DECNET------+--)-'   
                 +-LU62--------+        
                 |         (8) |        
                 +-NETBIOS-----+        
                 |     (8)     |        
                 +-SPX---------+        
                 '-TCP---------'        

>--+--------------------------+--------------------------------><
   |                      (5) |   
   '-USERID--(-- string--)-----'   


Notes:

  1. This parameter must follow immediately after the channel name except on z/OS.
  2. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  3. Valid only on z/OS.
  4. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS.
  5. Valid only if TRPTYPE is LU62.
  6. You can specify more than one value on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS only.
  7. Valid only on HP OpenVMS.
  8. Valid only for clients to be run on DOS and Windows.

The parameters are described in ALTER CHANNEL .


Server-connection channel

Syntax diagram for a server-connection channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

>>-ALTER CHANNEL--(-- channel-name--)--CHLTYPE--(-- SVRCONN--)--->

   .-CMDSCOPE(' ')------------------. (2)   
>--+--------------------------------+--------------------------->
   |                            (1) |       
   +-CMDSCOPE--(-- qmgr-name-- )-----+       
   |             (1)                |       
   '-CMDSCOPE(*)--------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   +-ZLIBHIGH-+          
                   '-ANY------'          

                                     (2)   
>--+-------------------------------+---------------------------->
   '-DEFCDISP--(--+-PRIVATE---+--)-'       
                  +-FIXSHARED-+            
                  '-SHARED----'            

                            (2)                                
>--+----------------------+------+-------------------------+---->
   '-DESCR--(--  string--)-'      '-DISCINT--(--  integer--)-'   

>--+-----------------------+--+--------------------------+------>
   '-HBINT--(--  integer--)-'  '-KAINT--(--+- integer-+--)-'   
                                          '-AUTO----'        

>--+------------------------+--+-------------------------+------>
   '-MAXINST--(-- integer--)-'  '-MAXINSTC--(-- integer--)-'   

>--+-------------------------+--+------------------------+------>
   '-MAXMSGL--(--  integer--)-'  '-MCAUSER--(--  string--)-'   

>--+--------------------------+--------------------------------->
   '-MONCHL--(--+-QMGR---+--)-'   
                +-OFF----+        
                +-LOW----+        
                +-MEDIUM-+        
                '-HIGH---'        

>--+-------------------------------+---------------------------->
   |        (2)                    |   
   '-PUTAUT------(--+-DEF-----+--)-'   
                    '-ONLYMCA-'        

   .-QSGDISP(QMGR)------. (2)                                  
>--+--------------------+------+---------------------------+---->
   +-QSGDISP(COPY)------+      |             .-+---+--.    |   
   |                (1) |      |             | '-,-'  |    |   
   +-QSGDISP(GROUP)-----+      |             V        |    |   
   '-QSGDISP(PRIVATE)---'      '-RCVDATA--(---- string-+--)-'   

>--+---------------------------+--+------------------------+---->
   |             .-+---+--.    |  '-SCYDATA--(--  string--)-'   
   |             | '-,-'  |    |                               
   |             V        |    |                               
   '-RCVEXIT--(---- string-+--)-'                               

>--+------------------------+--+----------------------------+--->
   '-SCYEXIT--(--  string--)-'  |              .-+---+--.    |   
                               |              | '-,-'  |    |   
                               |              V        |    |   
                               '-SENDDATA--(---- string-+--)-'   

>--+----------------------------+------------------------------->
   |              .-+---+--.    |   
   |              | '-,-'  |    |   
   |              V        |    |   
   '-SENDEXIT--(---- string-+--)-'   

>--+--------------------------+--------------------------------->
   '-SHARECNV--(--  integer--)-'   

>--+------------------------------+----------------------------->
   '-SSLCAUTH--(--+-OPTIONAL-+--)-'   
                  '-REQUIRED-'        

>--+------------------------+--+------------------------+------->
   '-SSLCIPH--(--  string--)-'  '-SSLPEER--(--  string--)-'   

>--+--------------------------------+--------------------------><
   '-TRPTYPE--(--+-LU62--------+--)-'   
                 |         (3) |        
                 +-NETBIOS-----+        
                 |     (3)     |        
                 +-SPX---------+        
                 '-TCP---------'        


Notes:

  1. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  2. Valid only on z/OS.
  3. Valid only for clients to be run on Windows.

The parameters are described in ALTER CHANNEL .


Cluster-sender channel

Syntax diagram for a cluster-sender channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

>>-ALTER CHANNEL--(-- channel-name--)---------------------------->

                          (1) (2)                               
>--CHLTYPE--(--CLUSSDR--)----------+------------------------+--->
                                   '-BATCHHB--(-- integer--)-'   

>--+-------------------------+--+------------------------+------>
   '-BATCHINT--(-- integer--)-'  '-BATCHSZ--(-- integer--)-'   

>--+----------------------+--+----------------------------+----->
   '-CLUSNL--(-- nlname--)-'  '-CLUSTER--(-- clustername--)-'   

>--+-------------------------+--+-------------------------+----->
   '-CLWLPRTY--(-- integer--)-'  '-CLWLRANK--(-- integer--)-'   

>--+-------------------------+---------------------------------->
   '-CLWLWGHT--(-- integer--)-'   

   .-CMDSCOPE(' ')-----------------. (4)   
>--+-------------------------------+---------------------------->
   |                           (3) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (3)               |       
   '-CMDSCOPE(*)-------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   '-ZLIBHIGH-'          

>--+-----------------------+--+------------------------+-------->
   '-CONNAME--(-- string--)-'  '-CONVERT--(--+-NO--+--)-'   
                                            '-YES-'        

>--+---------------------+--+------------------------+---------->
   '-DESCR--(-- string--)-'  '-DISCINT--(-- integer--)-'   

>--+----------------------+--+--------------------------+------->
   '-HBINT--(-- integer--)-'  '-KAINT--(--+- integer-+--)-'   
                                         '-AUTO----'        

>--+------------------------+--+------------------------+------->
   '-LOCLADDR--(-- string--)-'  '-LONGRTY--(-- integer--)-'   

>--+------------------------+--+------------------------+------->
   '-LONGTMR--(-- integer--)-'  '-MAXMSGL--(-- integer--)-'   

>--+-----------------------+------------------------------------>
   '-MCANAME--(-- string--)-'   

>--+--------------------------------+--------------------------->
   |                            (5) |   
   '-MCATYPE--(--+-PROCESS-+--)-----'   
                 '-THREAD--'            

>--+-----------------------+--+----------------------------+---->
   '-MCAUSER--(-- string--)-'  |                        (6) |   
                              '-MODENAME--(-- string--)-----'   

>--+--------------------------+--------------------------------->
   '-MONCHL--(--+-QMGR---+--)-'   
                +-OFF----+        
                +-LOW----+        
                +-MEDIUM-+        
                '-HIGH---'        

>--+---------------------------+-------------------------------->
   |             .-+---+--.    |   
   |             | '-,-'  |    |   
   |             V        |    |   
   '-MSGDATA--(---- string-+--)-'   

>--+---------------------------+-------------------------------->
   |             .-+---+--.    |   
   |             | '-,-'  |    |   
   |             V        |    |   
   '-MSGEXIT--(---- string-+--)-'   

>--+----------------------------+------------------------------->
   '-NPMSPEED--(--+-FAST---+--)-'   
                  '-NORMAL-'        

>--+--------------------------------+--------------------------->
   |                        (6) (7) |   
   '-PASSWORD--(-- string--)---------'   

                                  .-QSGDISP(QMGR)------. (4)   
>--+---------------------------+--+--------------------+-------->
   '-PROPCTL--(--+-ALL----+--)-'  +-QSGDISP(COPY)------+       
                 +-NONE---+       |                (3) |       
                 '-COMPAT-'       +-QSGDISP(GROUP)-----+       
                                  '-QSGDISP(PRIVATE)---'       

>--+---------------------------+-------------------------------->
   |             .-+---+--.    |   
   |             | '-,-'  |    |   
   |             V        |    |   
   '-RCVDATA--(---- string-+--)-'   

>--+---------------------------+--+-----------------------+----->
   |             .-+---+--.    |  '-SCYDATA--(-- string--)-'   
   |             | '-,-'  |    |                              
   |             V        |    |                              
   '-RCVEXIT--(---- string-+--)-'                              

>--+-----------------------+--+----------------------------+---->
   '-SCYEXIT--(-- string--)-'  |              .-+---+--.    |   
                              |              | '-,-'  |    |   
                              |              V        |    |   
                              '-SENDDATA--(---- string-+--)-'   

>--+----------------------------+--+------------------------+--->
   |              .-+---+--.    |  '-SEQWRAP--(-- integer--)-'   
   |              | '-,-'  |    |                               
   |              V        |    |                               
   '-SENDEXIT--(---- string-+--)-'                               

>--+-------------------------+--+-------------------------+----->
   '-SHORTRTY--(-- integer--)-'  '-SHORTTMR--(-- integer--)-'   

>--+-----------------------+--+-----------------------+--------->
   '-SSLCIPH--(-- string--)-'  '-SSLPEER--(-- string--)-'   

                                 (8)   
>--+---------------------------+-------------------------------->
   '-STATCHL--(--+-QMGR---+--)-'       
                 +-OFF----+            
                 +-LOW----+            
                 +-MEDIUM-+            
                 '-HIGH---'            

>--+--------------------------+--------------------------------->
   |                      (6) |   
   '-TPNAME--(-- string--)-----'   

>--+--------------------------------+--------------------------->
   '-TRPTYPE--(--+-LU62--------+--)-'   
                 |         (9) |        
                 +-NETBIOS-----+        
                 |     (9)     |        
                 +-SPX---------+        
                 '-TCP---------'        

>--+-----------------------+------------------------------------>
   '-USEDLQ--(--+-NO--+--)-'   
                '-YES-'        

>--+------------------------------+----------------------------><
   |                      (6) (7) |   
   '-USERID--(-- string--)---------'   


Notes:

  1. This parameter must follow immediately after the channel name except on z/OS.
  2. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS.
  3. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  4. Valid only on z/OS.
  5. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, and Windows.
  6. Valid only if TRPTYPE is LU62.
  7. Not valid on z/OS.
  8. This parameter is valid only on AIX, HP-UX, Linux, IBM i, Solaris, and Windows.
  9. Valid only Windows.

The parameters are described in ALTER CHANNEL .


Cluster-receiver channel

Syntax diagram for a cluster-receiver channel when using the ALTER CHANNEL command.

   
ALTER CHANNEL

>>-ALTER CHANNEL--(-- channel-name--)---------------------------->

                           (1) (2)   
>--CHLTYPE--(--CLUSRCVR--)-------------------------------------->

>--+------------------------+--+-------------------------+------>
   '-BATCHHB--(-- integer--)-'  '-BATCHINT--(-- integer--)-'   

>--+------------------------+--+----------------------+--------->
   '-BATCHSZ--(-- integer--)-'  '-CLUSNL--(-- nlname--)-'   

>--+----------------------------+------------------------------->
   '-CLUSTER--(-- clustername--)-'   

>--+-------------------------+--+-------------------------+----->
   '-CLWLPRTY--(-- integer--)-'  '-CLWLRANK--(-- integer--)-'   

>--+-------------------------+---------------------------------->
   '-CLWLWGHT--(-- integer--)-'   

   .-CMDSCOPE(' ')-----------------. (4)   
>--+-------------------------------+---------------------------->
   |                           (3) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (3)               |       
   '-CMDSCOPE(*)-------------------'       

>--+-------------------------------+---------------------------->
   |             .-,----------.    |   
   |             V            |    |   
   '-COMPHDR--(----+-NONE---+-+--)-'   
                   '-SYSTEM-'          

>--+---------------------------------+-------------------------->
   |             .-,------------.    |   
   |             V              |    |   
   '-COMPMSG--(----+-NONE-----+-+--)-'   
                   +-RLE------+          
                   +-ZLIBFAST-+          
                   '-ZLIBHIGH-'          

>--+-----------------------+--+------------------------+-------->
   '-CONNAME--(-- string--)-'  '-CONVERT--(--+-NO--+--)-'   
                                            '-YES-'        

>--+---------------------+--+------------------------+---------->
   '-DESCR--(-- string--)-'  '-DISCINT--(-- integer--)-'   

>--+----------------------+--+--------------------------+------->
   '-HBINT--(-- integer--)-'  '-KAINT--(--+- integer-+--)-'   
                                         '-AUTO----'        

>--+------------------------+--+------------------------+------->
   '-LOCLADDR--(-- string--)-'  '-LONGRTY--(-- integer--)-'   

>--+------------------------+--+------------------------+------->
   '-LONGTMR--(-- integer--)-'  '-MAXMSGL--(-- integer--)-'   

>--+-----------------------+--+----------------------------+---->
   '-MCANAME--(-- string--)-'  '-MCATYPE--(--+-PROCESS-+--)-'   
                                            '-THREAD--'        

>--+-----------------------+--+----------------------------+---->
   '-MCAUSER--(-- string--)-'  |                        (5) |   
                              '-MODENAME--(-- string--)-----'   

>--+--------------------------+--+----------------------+------->
   '-MONCHL--(--+-QMGR---+--)-'  '-MRDATA--(-- string--)-'   
                +-OFF----+                                  
                +-LOW----+                                  
                +-MEDIUM-+                                  
                '-HIGH---'                                  

>--+----------------------+--+----------------------+----------->
   '-MREXIT--(-- string--)-'  '-MRRTY--(-- integer--)-'   

>--+----------------------+--+---------------------------+------>
   '-MRTMR--(-- integer--)-'  |             .-+---+--.    |   
                             |             | '-,-'  |    |   
                             |             V        |    |   
                             '-MSGDATA--(---- string-+--)-'   

>--+---------------------------+--+------------------------+---->
   |             .-+---+--.    |  '-NETPRTY--(-- integer--)-'   
   |             | '-,-'  |    |                               
   |             V        |    |                               
   '-MSGEXIT--(---- string-+--)-'                               

>--+----------------------------+------------------------------->
   '-NPMSPEED--(--+-FAST---+--)-'   
                  '-NORMAL-'        

>--+---------------------------+-------------------------------->
   '-PROPCTL--(--+-ALL----+--)-'   
                 +-NONE---+        
                 '-COMPAT-'        

>--+-------------------------------+---------------------------->
   '-PUTAUT--(--+-DEF---------+--)-'   
                +-CTX---------+        
                |         (4) |        
                +-ONLYMCA-----+        
                |        (4)  |        
                '-ALTMCA------'        

   .-QSGDISP(QMGR)------. (4)                                  
>--+--------------------+------+---------------------------+---->
   +-QSGDISP(COPY)------+      |             .-+---+--.    |   
   |                (3) |      |             | '-,-'  |    |   
   +-QSGDISP(GROUP)-----+      |             V        |    |   
   '-QSGDISP(PRIVATE)---'      '-RCVDATA--(---- string-+--)-'   

>--+---------------------------+--+-----------------------+----->
   |             .-+---+--.    |  '-SCYDATA--(-- string--)-'   
   |             | '-,-'  |    |                              
   |             V        |    |                              
   '-RCVEXIT--(---- string-+--)-'                              

>--+-----------------------+--+----------------------------+---->
   '-SCYEXIT--(-- string--)-'  |              .-+---+--.    |   
                              |              | '-,-'  |    |   
                              |              V        |    |   
                              '-SENDDATA--(---- string-+--)-'   

>--+----------------------------+--+------------------------+--->
   |              .-+---+--.    |  '-SEQWRAP--(-- integer--)-'   
   |              | '-,-'  |    |                               
   |              V        |    |                               
   '-SENDEXIT--(---- string-+--)-'                               

>--+-------------------------+--+-------------------------+----->
   '-SHORTRTY--(-- integer--)-'  '-SHORTTMR--(-- integer--)-'   

>--+------------------------------+----------------------------->
   '-SSLCAUTH--(--+-OPTIONAL-+--)-'   
                  '-REQUIRED-'        

>--+-----------------------+--+-----------------------+--------->
   '-SSLCIPH--(-- string--)-'  '-SSLPEER--(-- string--)-'   

                                 (6)   
>--+---------------------------+-------------------------------->
   '-STATCHL--(--+-QMGR---+--)-'       
                 +-OFF----+            
                 +-LOW----+            
                 +-MEDIUM-+            
                 '-HIGH---'            

>--+--------------------------+--------------------------------->
   |                      (5) |   
   '-TPNAME--(-- string--)-----'   

>--+--------------------------------+--------------------------->
   '-TRPTYPE--(--+-LU62--------+--)-'   
                 |         (7) |        
                 +-NETBIOS-----+        
                 |     (7)     |        
                 +-SPX---------+        
                 '-TCP---------'        

>--+-----------------------+-----------------------------------><
   '-USEDLQ--(--+-NO--+--)-'   
                '-YES-'        


Notes:

  1. This parameter must follow immediately after the channel name except on z/OS.
  2. Valid only on AIX, HP OpenVMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS.
  3. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  4. Valid only on z/OS.
  5. Valid only if TRPTYPE is LU62.
  6. This parameter is valid only on AIX, HP-UX, Linux, IBM i, Solaris, and Windows.
  7. Valid only on Windows.

The parameters are described in ALTER CHANNEL .


ALTER CHANNEL (MQTT)

Syntax diagram for a telemetry channel when using the ALTER CHANNEL command. This is separate from the regular ALTER CHANNEL syntax diagram and parameter descriptions.

   
>>-ALTER CHANNEL--(-- channel-name--)--CHLTYPE--(-- MQTT--)------->

>--+------------------------+--+-----------------------+-------->
   '-BACKLOG--(-- integer--)-'  '-JAASCFG--(-- string--)-'   

>--+------------------------+--+-----------------------+-------->
   '-LOCLADDR--(-- string--)-'  '-MCAUSER--(-- string--)-'   

>--+---------------------+--+-----------------------+----------->
   '-PORT--(-- integer--)-'  '-SSLCIPH--(-- string--)-'   

>--+--------------------+--+-----------------------+------------>
   '-SSLCAUTH(OPTIONAL)-'  '-SSLKEYP--(-- string--)-'   

>--+-----------------------+--+---------------+----------------><
   '-SSLKEYR--(-- string--)-'  '-USECLTID(YES)-'   



Parameter descriptions for ALTER CHANNEL (MQTT)

(channel-name)

The name of the new channel definition.

The name must not be the same as any existing channel defined on this queue manager (unless REPLACE or ALTER is specified).

The maximum length of the string is 20 characters, and the string must contain only valid characters; see Rules for naming WebSphere MQ objects .

CHLTYPE

Channel type. This parameter is required.

MQTT

Telemetry channel
BACKLOG(integer)

The number of outstanding connection requests that the telemetry channel can support at any one time. When the backlog limit is reached, any further clients trying to connect will be refused connection until the current backlog is processed.

The value is in the range 0 - 999999999.

The default value is 4096.

JAASCFG(string)

The file path of the JAAS configuration.
LOCLADDR(string)

LOCLADDR is the local communications address for the channel. Use this parameter if you want a channel to use a particular IP address, port, or port range for outbound communications. LOCLADDR might be useful in recovery scenarios where a channel is restarted on a different TCP/IP stack. LOCLADDR is also useful to force a channel to use an IPv4 or IPv6 stack on a dual-stack system. You can also use LOCLADDR to force a channel to use a dual-mode stack on a single-stack system.

This parameter is valid only for channels with a transport type (TRPTYPE) of TCP. If TRPTYPE is not TCP, the data is ignored and no error message is issued.

The value is the optional IP address, and optional port or port range used for outbound TCP/IP communications. The format for this information is as follows:

 LOCLADDR([ip-addr][(low-port[,high-port])][,[ip-addr][(low-port[,high-port])]])

The maximum length of LOCLADDR, including multiple addresses, is MQ_LOCAL_ADDRESS_LENGTH.

If you omit LOCLADDR, a local address is automatically allocated.

Note, that you can set LOCLADDR for a C client using the Client Channel Definition Table (CCDT).

All the parameters are optional. Omitting the ip-addr part of the address is useful to enable the configuration of a fixed port number for an IP firewall. Omitting the port number is useful to select a particular network adapter without having the identify a unique local port number. The TCP/IP stack generates a unique port number.

Specify [,[ip-addr][(low-port[,high-port])]] multiple times for each additional local address. Use multiple local addresses if you want to specify a specific subset of local network adapters. You can also use [,[ip-addr][(low-port[,high-port])]] to represent a particular local network address on different servers that are part of a multi-instance queue manager configuration.

ip-addr
ip-addr is specified in one of three forms:

IPv4 dotted decimal

For example 192.0.2.1

IPv6 hexadecimal notation

For example 2001:DB8:0:0:0:0:0:0

Alphanumeric host name form

For example WWW.EXAMPLE.COM
low-port and high-port
low-port and high-port are port numbers enclosed in parentheses.
Table 3 shows how the LOCLADDR parameter can be used:

Examples of how the LOCLADDR parameter can be used

LOCLADDR Meaning
9.20.4.98 Channel binds to this address locally
9.20.4.98, 9.20.4.99 Channel binds to either IP address. The address might be two network adapters on one server, or a different network adapter on two different servers in a multi-instance configuration.
9.20.4.98(1000) Channel binds to this address and port 1000 locally
9.20.4.98(1000,2000) Channel binds to this address and uses a port in the range 1000 - 2000 locally
(1000) Channel binds to port 1000 locally
(1000,2000) Channel binds to port in range 1000 - 2000 locally

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, CLUSSDR, CLUSRCVR, or MQTT.

On CLUSSDR channels, the IP address and port to which the outbound channel binds, is a combination of fields. It is a concatenation of the IP address, as defined in the LOCLADDR parameter, and the port range from the cluster cache. If there is no port range in the cache, the port range defined in the LOCLADDR parameter is used. This port range does not apply to z/OS.

Even though this parameter is similar in form to CONNAME, it must not be confused with it. The LOCLADDR parameter specifies the characteristics of the local communications, whereas the CONNAME parameter specifies how to reach a remote queue manager.

When a channel is started, the values specified for CONNAME and LOCLADDR determine the IP stack to be used for communication; see Table 3 and Local Address (LOCLADDR) .

If the appropriate IP stack for the local address is not installed or configured, the channel fails to start and an error message is generated.

For channels with a channel type (CHLTYPE) of MQTT the usage of this parameter is slightly different. Specifically, a telemetry channel (MQTT) LOCLADDR parameter expects only an IPv4 or IPv6 IP address, or a valid host name as a string. This string must not contain a port number or port range. If an IP address is entered, only the address format is validated. The IP address itself is not validated.

How the IP stack to be used for communication is determined

Protocols supported CONNAME LOCLADDR Action of channel
IPv4 only IPv4 address 1   Channel binds to IPv4 stack
IPv6 address 2   Channel fails to resolve CONNAME
IPv4 and 6 host name 3   Channel binds to IPv4 stack
IPv4 address IPv4 address Channel binds to IPv4 stack
IPv6 address IPv4 address Channel fails to resolve CONNAME
IPv4 and 6 host name IPv4 address Channel binds to IPv4 stack
Any address 4 IPv6 address Channel fails to resolve LOCLADDR
IPv4 address IPv4 and 6 host name Channel binds to IPv4 stack
IPv6 address IPv4 and 6 host name Channel fails to resolve CONNAME
IPv4 and 6 host name IPv4 and 6 host name Channel binds to IPv4 stack
IPv4 and IPv6 IPv4 address   Channel binds to IPv4 stack
IPv6 address   Channel binds to IPv6 stack
IPv4 and 6 host name   Channel binds to stack determined by IPADDRV
IPv4 address IPv4 address Channel binds to IPv4 stack
IPv6 address IPv4 address Channel fails to resolve CONNAME
IPv4 and 6 host name IPv4 address Channel binds to IPv4 stack
IPv4 address IPv6 address Channel maps CONNAME to IPv6 5
IPv6 address IPv6 address Channel binds IPv6 stack
IPv4 and 6 host name IPv6 address Channel binds IPv6 stack
IPv4 address IPv4 and 6 host name Channel binds to IPv4 stack
IPv6 address IPv4 and 6 host name Channel binds to IPv6 stack
IPv4 and 6 host name IPv4 and 6 host name Channel binds to stack determined by IPADDRV
IPv6 only IPv4 address   Channel maps CONNAME to IPv6 5
IPv6 address   Channel binds to IPv6 stack
IPv4 and 6 host name   Channel binds to IPv6 stack
Any address IPv4 address Channel fails to resolve LOCLADDR
IPv4 address IPv6 address Channel maps CONNAME to IPv6 5
IPv6 address IPv6 address Channel binds to IPv6 stack
IPv4 and 6 host name IPv6 address Channel binds to IPv6 stack
IPv4 address IPv4 and 6 host name Channel maps CONNAME to IPv6 5
IPv6 address IPv4 and 6 host name Channel binds to IPv6 stack
IPv4 and 6 host name IPv4 and 6 host name Channel binds to IPv6 stack

Notes:

  1. IPv4 address. An IPv4 host name that resolves only to an IPv4 network address or a specific dotted notation IPv4 address, for example 1.2.3.4. This note applies to all occurrences of 'IPv4 address' in this table.
  2. IPv6 address. An IPv6 host name that resolves only to an IPv6 network address or a specific hexadecimal notation IPv6 address, for example 4321:54bc. This note applies to all occurrences of 'IPv6 address' in this table.
  3. IPv4 and 6 host name. A host name that resolves to both IPv4 and IPv6 network addresses. This note applies to all occurrences of 'IPv4 and 6 host name' in this table.
  4. Any address. IPv4 address, IPv6 address, or IPv4 and 6 host name. This note applies to all occurrences of 'Any address' in this table.
  5. Maps IPv4 CONNAME to IPv4 mapped IPv6 address. IPv6 stack implementations that do not support IPv4 mapped IPv6 addressing fail to resolve the CONNAME. Mapped addresses might require protocol translators in order to be used. The use of mapped addresses is not recommended.

MCAUSER(string)

Message channel agent user identifier.

Note: An alternative way of providing a user ID for a channel to run under is to use channel authentication records. With channel authentication records, different connections can use the same channel while using different credentials. If both MCAUSER on the channel is set and channel authentication records are used to apply to the same channel, the channel authentication records take precedence. The MCAUSER on the channel definition is only used if the channel authentication record uses USERSRC(CHANNEL). For more details, see Channel authentication records .

This parameter interacts with PUTAUT , see the definition of that parameter for more information.

If it is nonblank, it is the user identifier that is to be used by the message channel agent for authorization to access WebSphere MQ resources, including (if PUTAUT is DEF) authorization to put the message to the destination queue for receiver or requester channels.

If it is blank, the message channel agent uses its default user identifier.

The default user identifier is derived from the user ID that started the receiving channel. The possible values are:

  • For TCP/IP, the user ID from the inetd.conf entry, or the user that started the listener.
  • For SNA, the user ID from the SNA server entry or, in the absence of this user ID the incoming attach request, or the user that started the listener.
  • For NetBIOS or SPX, the user ID that started the listener.

The maximum length of the string is 64 characters on Windows and 12 characters on other platforms. On Windows, you can optionally qualify a user identifier with the domain name in the format user@domain.

PORT(integer)

The port number for TCP/IP. This parameter is the port number on which the listener is to stop listening. It is valid only if the transmission protocol is TCP/IP.

The PORT parameter accepts a value of zero. This value causes an available port to be assigned to the channel.
SSLCAUTH

Defines whether WebSphere MQ requires a certificate from the SSL client. The initiating end of the channel acts as the SSL client, so this parameter applies to the end of the channel that receives the initiation flow, which acts as the SSL server.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, SVRCONN, CLUSRCVR, SVR, RQSTR, or MQTT.

The parameter is used only for channels with SSLCIPH specified. If SSLCIPH is blank, the data is ignored and no error message is issued.

REQUIRED

WebSphere MQ requires and validates a certificate from the SSL client.

OPTIONAL

The peer SSL client system might still send a certificate. If it does, the contents of this certificate are validated as normal.
SSLCIPH(string)

When SSLCIPH is used with a telemetry channel, it means SSL Cipher Suite . The SSL cipher suite is the one supported by the JVM that is running the telemetry (MQXR) service. If the SSLCIPH parameter is blank, no attempt is made to use SSL on the channel.

Here is an alphabetic list of the SSL cipher suites that are currently supported:

  • SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
  • SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
  • SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
  • SSL_DH_anon_WITH_AES_128_CBC_SHA
  • SSL_DH_anon_WITH_DES_CBC_SHA
  • SSL_DH_anon_WITH_RC4_128_MD5
  • SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
  • SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • SSL_DHE_DSS_WITH_AES_128_CBC_SHA
  • SSL_DHE_DSS_WITH_DES_CBC_SHA
  • SSL_DHE_DSS_WITH_RC4_128_SHA
  • SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
  • SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • SSL_DHE_RSA_WITH_AES_128_CBC_SHA
  • SSL_DHE_RSA_WITH_DES_CBC_SHA
  • SSL_KRB5_EXPORT_WITH_DES_CBC_40_MD5
  • SSL_KRB5_EXPORT_WITH_DES_CBC_40_SHA
  • SSL_KRB5_EXPORT_WITH_RC4_40_MD5
  • SSL_KRB5_EXPORT_WITH_RC4_40_SHA
  • SSL_KRB5_WITH_3DES_EDE_CBC_MD5
  • SSL_KRB5_WITH_3DES_EDE_CBC_SHA
  • SSL_KRB5_WITH_DES_CBC_MD5
  • SSL_KRB5_WITH_DES_CBC_SHA
  • SSL_KRB5_WITH_RC4_128_MD5
  • SSL_KRB5_WITH_RC4_128_SHA
  • SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
  • SSL_RSA_EXPORT_WITH_RC4_40_MD5
  • SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
  • SSL_RSA_FIPS_WITH_AES_128_CBC_SHA256
  • SSL_RSA_FIPS_WITH_AES_256_CBC_SHA256
  • SSL_RSA_FIPS_WITH_DES_CBC_SHA
  • SSL_RSA_WITH_3DES_EDE_CBC_SHA
  • SSL_RSA_WITH_AES_128_CBC_SHA
  • SSL_RSA_WITH_AES_128_CBC_SHA256
  • SSL_RSA_WITH_AES_256_CBC_SHA256
  • SSL_RSA_WITH_DES_CBC_SHA
  • SSL_RSA_WITH_NULL_MD5
  • SSL_RSA_WITH_NULL_SHA
  • SSL_RSA_WITH_NULL_SHA256
  • SSL_RSA_WITH_RC4_128_MD5
  • SSL_RSA_WITH_RC4_128_SHA

If you plan to use SHA-2 cipher suites, see System requirements for using SHA-2 cipher suites with MQTT channels .

SSLKEYP(string)

The store for digital certificates and their associated private keys. If you do not specify a key file, SSL is not used.
SSLKEYR(string)

The password for the key repository. If no passphrase is entered, then unencrypted connections must be used.
USECLTID

Decide whether you want to use the MQTT client ID for the new connection as the WebSphere MQ user ID for that connection. If this property is specified, the user name supplied by the client is ignored.


Related concepts :


Related reference :


ALTER COMMINFO

Use the MQSC command ALTER COMMINFO to alter the parameters of a communication information object.

IBM i UNIX and Linux Windows z/OS
X X X X

Parameters not specified in the ALTER COMMINFO command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT COMMINFO

   
ALTER COMMINFO

>>-ALTER COMMINFO--(-- comminfo name--)--+------------------+---->
                                        +-BRIDGE(DISABLED)-+   
                                        '-BRIDGE(ENABLED)--'   

>--+-----------------------+--+-------------------+------------->
   +-CCSID(ASPUB)----------+  +-COMMEV(DISABLED)--+   
   '-CCSID--(-- codepage--)-'  +-COMMEV(ENABLED)---+   
                              '-COMMEV(EXCEPTION)-'   

>--+------------+--+--------------------------+----------------->
   '-DESCR(' ')-'  +-ENCODING(ASPUB)----------+   
                   +-ENCODING(NORMAL)---------+   
                   +-ENCODING(REVERSED)-------+   
                   +-ENCODING(S390)-----------+   
                   +-ENCODING(TNS)------------+   
                   '-ENCODING--(-- encoding--)-'   

>--+------------------------------+----------------------------->
   '-GRPADDR--(-- group address--)-'   

>--+-----------------------------------+--+----------------+---->
   '-MCHBINT--(-- heartbeat interval--)-'  +-MCPROP(ALL)----+   
                                          +-MCPROP(REPLY)--+   
                                          +-MCPROP(USER)---+   
                                          +-MCPROP(NONE)---+   
                                          '-MCPROP(COMPAT)-'   

>--+--------------------------------+--------------------------->
   '-MONINT--(-- monitor interval--)-'   

>--+--------------------------------+--+----------------+------->
   '-MSGHIST--(-- message history--)-'  +-NSUBHIST(NONE)-+   
                                       '-NSUBHIST(ALL)--'   

>--+-------------------------+---------------------------------><
   '-PORT--(-- port number--)-'   



Parameter descriptions for ALTER COMMINFO

(comminfo name)

Name of the communications information object. This parameter is required.

The name must not be the same as any other communications information object name currently defined on this queue manager. See Rules for naming WebSphere MQ objects .

BRIDGE

Controls whether publications from applications not using Multicast are bridged to applications using Multicast. Bridging does not apply to topics that are marked as MCAST(ONLY). As these topics can only be Multicast traffic, it is not applicable to bridge to the queue's publish/subscribe domain.

DISABLED
Publications from applications not using Multicast are not bridged to applications that do use Multicast.
ENABLED
Publications from applications not using Multicast are bridged to applications that do use Multicast.

CCSID(integer)

The coded character set identifier that messages are transmitted on. Specify a value in the range 1 through 65535.

The CCSID must specify a value that is defined for use on your platform, and use a character set that is appropriate to the queue manager's platform. If you use this parameter to change the CCSID, applications that are running when the change is applied continue to use the original CCSID therefore you must stop and restart all running applications before you continue. Running applications include the command server and channel programs. Stop and restart all running applications, stop and restart the queue manager after changing this parameter.

The CCSID can also be set to ASPUB which means that the coded character set is taken from that supplied in the published message.

COMMEV

Controls whether event messages are generated for Multicast handles that are created using this COMMINFO object. Events will only be generated if they are enabled using the MONINT parameter.

DISABLED
Publications from applications not using Multicast are not bridged to applications that do use Multicast.
ENABLED
Publications from applications not using Multicast are bridged to applications that do use Multicast.
EXCEPTION
Event messages are written if the message reliability is below the reliability threshold The reliability threshold is set to 90 by default.

DESCR(string)

Plain-text comment. It provides descriptive information about the communication information object when an operator issues the DISPLAY COMMINFO command (see DISPLAY COMMINFO ).

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

ENCODING

The encoding that the messages are transmitted in.

ASPUB
The encoding of the message is taken from that supplied in the published message.
NORMAL
REVERSED
S390
TNS
encoding

GRPADDR

The group IP address or DNS name.

It is the responsibility of the administrator to manage the group addresses. It is possible for all multicast clients to use the same group address for every topic; only the messages that match outstanding subscriptions on the client are delivered. Using the same group address can be inefficient because every client has to examine and process every multicast packet in the network. It is more efficient to allocate different IP group addresses to different topics or sets of topics, but this allocation requires careful management, especially if other non-MQ multicast applications are in use on the network.

MCHBINT

The heartbeat interval is measured in milliseconds, and specifies the frequency at which the transmitter notifies any receivers that there is no further data available.

MCPROP

The multicast properties control how many of the MQMD properties and user properties flow with the message.

All
All user properties and all the fields of the MQMD are transported.
Reply
Only user properties, and MQMD fields that deal with replying to the messages, are transmitted. These properties are:

  • MsgType
  • MessageId
  • CorrelId
  • ReplyToQ
  • ReplyToQmgr

User
Only the user properties are transmitted.
NONE
No user properties or MQMD fields are transmitted.
COMPAT
This value causes the transmission of the message to be done in a compatible mode to RMM allowing some inter-operation with the current XMS applications and Broker RMM applications.

MONINT(integer)

How frequently, in seconds, that monitoring information is updated. If events messages are enabled, this parameter also controls how frequently event messages are generated about the status of the Multicast handles created using this COMMINFO object.

A value of 0 means that there is no monitoring.

MSGHIST

The maximum message history is the amount of message history that is kept by the system to handle retransmissions in the case of NACKs (negative acknowledgments).

A value of 0 gives the least level of reliability.

NSUBHIST

The new subscriber history controls whether a subscriber joining a publication stream receives as much data as is currently available, or receives only publications made from the time of the subscription.

NONE
A value of NONE causes the transmitter to transmit only publication made from the time of the subscription.
ALL
A value of ALL causes the transmitter to retransmit as much history of the topic as is known. In some circumstances, this retransmission can give a similar behavior to retained publications.

Note: Using the value of ALL might have a detrimental effect on performance if there is a large topic history because all the topic history is retransmitted.

PORT(integer)

The port number to transmit on.


ALTER LISTENER

Use MQSC command ALTER LISTENER to alter the parameters of an existing WebSphere MQ listener definition. If the listener is already running, any changes you make to its definition are effective only after the next time that the listener is started.

IBM i UNIX and Linux Windows z/OS
X X X  

Parameters not specified in the ALTER LISTENER command result in the existing values for those parameters being left unchanged.


Synonym : ALT LSTR

   
ALTER LISTENER

>>-ALTER LISTENER--(-- listener-name--)-------------------------->

                   (1)                                        
>--+-TRPTYPE(LU62)--------+--+----------------------------+----->
   |                  (1) |  |                        (2) |   
   +-TRPTYPE(NETBIOS)-----+  '-ADAPTER--(-- integer--)-----'   
   |              (1)     |                                   
   +-TRPTYPE(SPX)---------+                                   
   '-TRPTYPE(TCP)---------'                                   

>--+--------------------------------+--------------------------->
   |                        (3) (4) |   
   '-BACKLOG--(-- integer--)---------'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-COMMANDS--(-- integer--)-----'   

>--+------------------------------+--+---------------------+---->
   '-CONTROL--(--+-MANUAL----+--)-'  '-DESCR--(-- string--)-'   
                 +-QMGR------+                                 
                 '-STARTONLY-'                                 

>--+--------------------------+--------------------------------->
   |                      (3) |   
   '-IPADDR--(-- string--)-----'   

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-LOCLNAME--(-- string--)-----'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-NTBNAMES--(-- integer--)-----'   

>--+-------------------------+---------------------------------->
   |                     (3) |   
   '-PORT--(-- integer--)-----'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-SESSIONS--(-- integer--)-----'   

>--+---------------------------+-------------------------------->
   |                       (4) |   
   '-SOCKET--(-- integer--)-----'   

>--+--------------------------+--------------------------------><
   |                      (5) |   
   '-TPNAME--(-- string--)-----'   


Notes:

  1. Valid only on Windows.
  2. Valid only on Windows when TRPTYPE is NETBIOS.
  3. Valid when TRPTYPE is TCP.
  4. Valid on Windows when TRPTYPE is SPX.
  5. Valid only on Windows when TRPTYPE is LU62.


Parameter descriptions for ALTER LISTENER

(listener-name)

Name of the WebSphere MQ listener definition (see Rules for naming WebSphere MQ objects ). This is required.

The name must not be the same as any other listener definition currently defined on this queue manager (unless REPLACE is specified).

ADAPTER(integer)

The adapter number on which NetBIOS listens. This parameter is valid only on Windows when TRPTYPE is NETBIOS.

BACKLOG(integer)

The number of concurrent connection requests that the listener supports.

COMMANDS(integer)

The number of commands that the listener can use. This parameter is valid only on Windows when TRPTYPE is NETBIOS.

CONTROL(string)

Specifies how the listener is to be started and stopped.:

MANUAL
The listener is not to be started automatically or stopped automatically. It is to be controlled by use of the START LISTENER and STOP LISTENER commands.
QMGR
The listener being defined is to be started and stopped at the same time as the queue manager is started and stopped.
STARTONLY
The listener is to be started at the same time as the queue manager is started, but is not requested to stop when the queue manager is stopped.

DESCR(string)

Plain-text comment. It provides descriptive information about the listener when an operator issues the DISPLAY LISTENER command (see DISPLAY LISTENER ).

It should contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

IPADDR(string)

IP address for the listener specified in IPv4 dotted decimal, IPv6 hexadecimal notation, or alphanumeric host name form. If you do not specify a value for this parameter, the listener listens on all configured IPv4 and IPv6 stacks.

LIKE(listener-name)

The name of a listener, with parameters that are used to model this definition.

This parameter applies only to the DEFINE LISTENER command.

If this field is not filled in, and you do not complete the parameter fields related to the command, the values are taken from the default definition for listeners on this queue manager. This is equivalent to specifying:

 LIKE(SYSTEM.DEFAULT.LISTENER)

A default listener is provided but it can be altered by the installation of the default values required. See Rules for naming WebSphere MQ objects .

LOCLNAME(string)

The NetBIOS local name that the listener uses. This parameter is valid only on Windows when TRPTYPE is NETBIOS.

NTBNAMES(integer)

The number of names that the listener can use. This parameter is valid only on Windows when TRPTYPE is NETBIOS.

PORT(integer)

The port number for TCP/IP. This is valid only when TRPTYPE is TCP. It must not exceed 65535.

SESSIONS(integer)

The number of sessions that the listener can use. This parameter is valid only on Windows when TRPTYPE is NETBIOS.

SOCKET(integer)

The SPX socket on which to listen. This is valid only if TRPTYPE is SPX.

TPNAME(string)

The LU 6.2 transaction program name (maximum length 64 characters). This parameter is valid only on Windows when TRPTYPE is LU62.

TRPTYPE(string)

The transmission protocol to be used:

LU62
SNA LU 6.2. This is valid only on Windows.
NETBIOS
NetBIOS. This is valid only on Windows.
SPX
Sequenced packet exchange. This is valid only on Windows.
TCP
TCP/IP.


ALTER NAMELIST

Use the MQSC command ALTER NAMELIST to alter a list of names. This list is most commonly a list of cluster names or queue names.

IBM i UNIX and Linux Windows z/OS
X X X 2CR

Parameters not specified in the ALTER NAMELIST command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT NL

   
ALTER NAMELIST

>>-ALTER NAMELIST--(-- name--)----------------------------------->

   .-CMDSCOPE(' ')-----------------. (2)   
>--+-------------------------------+---------------------------->
   |                           (1) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (1)               |       
   '-CMDSCOPE(*)-------------------'       

>--+---------------------+--+---------------------------+------->
   '-DESCR--(-- string--)-'  |           .-,--------.    |   
                            |           V          |    |   
                            '-NAMES--(----+------+-+--)-'   
                                          '- name-'          

                        (2)  .-QSGDISP(QMGR)------. (2)   
>--+------------------+------+--------------------+------------><
   +-NLTYPE(NONE)-----+      +-QSGDISP(COPY)------+       
   +-NLTYPE(QUEUE)----+      |                (1) |       
   +-NLTYPE(Q)--------+      +-QSGDISP(GROUP)-----+       
   +-NLTYPE(CLUSTER)--+      '-QSGDISP(PRIVATE)---'       
   '-NLTYPE(AUTHINFO)-'                                   


Notes:

  1. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  2. Valid only on z/OS.


Usage notes

On UNIX systems, the command is valid only on AIX, HP-UX, and Solaris.


Parameter descriptions for ALTER NAMELIST

(name)

Name of the list.

The name must not be the same as any other namelist name currently defined on this queue manager (unless REPLACE or ALTER is specified). See Rules for naming WebSphere MQ objects .

CMDSCOPE

This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group.

CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP.

' '

The command is executed on the queue manager on which it was entered.

qmgr-name

The command is executed on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

You can specify a queue manager name other than the queue manager on which it was entered, only if you are using a shared queue environment and if the command server is enabled.

*

The command is executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of specifying * is the same as entering the command on every queue manager in the queue-sharing group.

DESCR(string)

Plain-text comment. It provides descriptive information about the namelist when an operator issues the DISPLAY NAMELIST command (see DISPLAY NAMELIST ).

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: If characters are used that are not in the coded character set identifier (CCSID) for this queue manager, they might be translated incorrectly if the information is sent to another queue manager.

NAMES(name, ...)

List of names.

The names can be of any type, but must conform to the rules for naming WebSphere MQ objects, with a maximum length of 48 characters.

An empty list is valid: specify NAMES(). The maximum number of names in the list is 256.

NLTYPE

Indicates the type of names in the namelist.

This parameter is valid only on z/OS.

NONE
The names are of no particular type.
QUEUE or Q
A namelist that holds a list of queue names.
CLUSTER
A namelist that is associated with clustering, containing a list of the cluster names.
AUTHINFO
This namelist is associated with SSL and contains a list of authentication information object names.

Namelists Used for clustering must have NLTYPE(CLUSTER) or NLTYPE(NONE).

Namelists Used for SSL must have NLTYPE(AUTHINFO).

QSGDISP

This parameter applies to z/OS only.

Specifies the disposition of the object to which you are applying the command (that is, where it is defined and how it behaves).

QSGDISP ALTER
COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(COPY). Any object residing in the shared repository, or any object defined using a command that had the parameters QSGDISP(QMGR), is not affected by this command.
GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). Any object residing on the page set of the queue manager that executes the command (except a local copy of the object) is not affected by this command. If the command is successful, the following command is generated and sent to all active queue managers in the queue-sharing group to attempt to refresh local copies on page set zero:

 DEFINE NAMELIST(name) 
REPLACE QSGDISP(COPY)
The ALTER for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with QSGDISP(QMGR) or QSGDISP(COPY). Any object residing in the shared repository is unaffected.
QMGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(QMGR). Any object residing in the shared repository, or any local copy of such an object, is not affected by this command.


ALTER PROCESS

Use the MQSC command ALTER PROCESS to alter the parameters of an existing WebSphere MQ process definition.

IBM i UNIX and Linux Windows z/OS
X X X 2CR

Parameters not specified in the ALTER PROCESS command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT PRO

   
ALTER PROCESS

>>-ALTER PROCESS--(-- process-name--)---------------------------->

>--+------------------------+----------------------------------->
   '-APPLICID--(-- string--)-'   

>--+--------------------------------+--------------------------->
   '-APPLTYPE--(--+- integer----+--)-'   
                  +-CICS-------+        
                  +-DEF--------+        
                  +-DOS--------+        
                  +-IMS--------+        
                  +-MVS--------+        
                  +-NOTESAGENT-+        
                  +-NSK--------+        
                  +-OPENVMS----+        
                  +-OS2--------+        
                  +-OS400------+        
                  +-UNIX-------+        
                  +-WINDOWS----+        
                  +-WINDOWSNT--+        
                  '-WLM--------'        

   .-CMDSCOPE(' ')-----------------. (2)   
>--+-------------------------------+---------------------------->
   |                           (1) |       
   +-CMDSCOPE--(-- qmgr-name--)-----+       
   |             (1)               |       
   '-CMDSCOPE(*)-------------------'       

>--+---------------------+--+------------------------+---------->
   '-DESCR--(-- string--)-'  '-ENVRDATA--(-- string--)-'   

   .-QSGDISP(QMGR)------. (2)                               
>--+--------------------+------+------------------------+------><
   +-QSGDISP(COPY)------+      '-USERDATA--(-- string--)-'   
   |                (1) |                                   
   +-QSGDISP(GROUP)-----+                                   
   '-QSGDISP(PRIVATE)---'                                   


Notes:

  1. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  2. Valid only on z/OS.


Parameter descriptions for ALTER PROCESS

(process-name)

Name of the WebSphere MQ process definition (see Rules for naming WebSphere MQ objects ). process-name is required.

The name must not be the same as any other process definition currently defined on this queue manager (unless REPLACE is specified).

APPLICID(string)

The name of the application to be started. The name might typically be a fully qualified file name of an executable object. Qualifying the file name is particularly important if you have multiple WebSphere MQ installations, to ensure the correct version of the application is run. The maximum length is 256 characters.

For a CICS application the name is a CICS transaction ID, and for an IMS™ application it is an IMS transaction ID.

On z/OS, for distributed queuing, it must be "CSQX start".

APPLTYPE(string)

The type of application to be started. Valid application types are:

integer

A system-defined application type in the range zero through 65 535 or a user-defined application type in the range 65 536 through 999 999 999.

For certain values in the system range, a parameter from the following list can be specified instead of a numeric value:

CICS

Represents a CICS transaction.

DOS

Represents a DOS application.

IMS

Represents an IMS transaction.

MVS™

Represents a z/OS application (batch or TSO).

NOTESAGENT

Represents a Lotus Notes agent.

NSK

Represents an HP Integrity NonStop Server application.

OPENVMS

Represents an HP OpenVMS application.

OS400

Represents an IBM i application.

UNIX

Represents a UNIX application.

WINDOWS

Represents a Windows application.

WINDOWSNT

Represents a Windows NT, Windows 2000, or Windows XP application.

WLM

Represents a z/OS workload manager application.

DEF

Specifying DEF causes the default application type for the platform at which the command is interpreted to be stored in the process definition. This default cannot be changed by the installation. If the platform supports clients, the default is interpreted as the default application type of the server.

Only use application types (other than user-defined types) that are supported on the platform at which the command is executed:

  • On HP OpenVMS, OPENVMS is supported
  • On z/OS, CICS, DOS, IMS, MVS, OS2, UNIX, WINDOWS, WINDOWSNT, WLM, and DEF are supported
  • On IBM i, OS400, CICS, and DEF are supported
  • On UNIX systems, UNIX, OS2, DOS, WINDOWS, CICS, and DEF are supported
  • On Windows, WINDOWSNT, DOS, WINDOWS, OS2, UNIX, CICS, and DEF are supported

CMDSCOPE

This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group.

CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP.

' '

The command is executed on the queue manager on which it was entered.

qmgr-name

The command is executed on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

In a shared queue environment, you can provide a different queue manager name from the one you are using to enter the command. The command server must be enabled.

*

The command is executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect is the same as entering the command on every queue manager in the queue-sharing group.

DESCR(string)

Plain-text comment. It provides descriptive information about the object when an operator issues the DISPLAY PROCESS command.

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: Use characters from the coded character set identifier (CCSID) for this queue manager. Other characters might be translated incorrectly if the information is sent to another queue manager.

ENVRDATA(string)

A character string that contains environment information pertaining to the application to be started. The maximum length is 128 characters.

The meaning of ENVRDATA is determined by the trigger-monitor application. The trigger monitor provided by WebSphere MQ appends ENVRDATA to the parameter list passed to the started application. The parameter list consists of the MQTMC2 structure, followed by one blank, followed by ENVRDATA with trailing blanks removed.

Note:

  1. On z/OS, ENVRDATA is not used by the trigger-monitor applications provided by WebSphere MQ.
  2. On z/OS, if APPLTYPE is WLM, the default values for the ServiceName and ServiceStep fields in the work information header (MQWIH) can be supplied in ENVRDATA. The format must be:

     SERVICENAME=servname,SERVICESTEP=stepname
    
    where:

    SERVICENAME=

    is the first 12 characters of ENVRDATA.

    servname

    is a 32-character service name. It can contain embedded blanks or any other data, and have trailing blanks. It is copied to the MQWIH as is.

    SERVICESTEP=

    is the next 13 characters of ENVRDATA.

    stepname

    is a 1 - 8 character service step name. It is copied as-is to the MQWIH, and padded to eight characters with blanks.
    If the format is incorrect, the fields in the MQWIH are set to blanks.
  3. On UNIX systems, ENVRDATA can be set to the ampersand character to make the started application run in the background.

QSGDISP

This parameter applies to z/OS only.

Specifies the disposition of the object to which you are applying the command (that is, where it is defined and how it behaves).

QSGDISP ALTER
COPY The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(COPY). Any object residing in the shared repository, or any object defined using a command that had the parameters QSGDISP(QMGR), is not affected by this command.
GROUP The object definition resides in the shared repository. The object was defined using a command that had the parameters QSGDISP(GROUP). On the page set of the queue manager that executes the command, only a local copy of the object is altered by this command. If the command is successful, the following command is generated.

 DEFINE PROCESS(process-name)
REPLACE QSGDISP(COPY)
The command is sent to all active queue managers in the queue-sharing group to attempt to refresh local copies on page set zero. The ALTER for the group object takes effect regardless of whether the generated command with QSGDISP(COPY) fails.
PRIVATE The object resides on the page set of the queue manager that executes the command, and was defined with QSGDISP(QMGR) or QSGDISP(COPY). Any object residing in the shared repository is unaffected.
QMGR The object definition resides on the page set of the queue manager that executes the command. The object was defined using a command that had the parameters QSGDISP(QMGR). Any object residing in the shared repository, or any local copy of such an object, is not affected by this command.

USERDATA(string)

A character string that contains user information pertaining to the application defined in the APPLICID that is to be started. The maximum length is 128 characters.

The meaning of USERDATA is determined by the trigger-monitor application. The trigger monitor provided by WebSphere MQ simply passes USERDATA to the started application as part of the parameter list. The parameter list consists of the MQTMC2 structure (containing USERDATA), followed by one blank, followed by ENVRDATA with trailing blanks removed.

For WebSphere MQ message channel agents, the format of this field is a channel name of up to 20 characters. See Managing objects for triggering for information about what APPLICID to provide to message channel agents.

For Microsoft Windows, the character string must not contain double quotation marks if the process definition is going to be passed to runmqtrm.


ALTER PSID

Use the MQSC command ALTER PSID to change the expansion method for a page set.

IBM i UNIX and Linux Windows z/OS
      CR

Parameters not specified in the ALTER PSID command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Synonym : ALT PSID

   
ALTER PSID

                                  .-EXPAND(USER)---.   
>>-ALTER PSID--(-- psid-number--)--+----------------+-----------><
                                  +-EXPAND(SYSTEM)-+   
                                  '-EXPAND(NONE)---'   



Parameter descriptions for ALTER PSID

(psid-number)

Identifier of the page set. This is required.

EXPAND

Controls how the queue manager should expand a page set when it becomes nearly full, and further pages are required in it.

USER

The secondary extent size that was specified when the page set was defined is used. If no secondary extent size was specified, or if it was specified as zero, then no dynamic page set expansion can take place.

At restart, if a previously used page set has been replaced with a data set that is smaller, it is expanded until it reaches the size of the previously used data set. Only one extent is required to reach this size.

SYSTEM

A secondary extent size that is approximately 10 per cent of the current size of the page set is used. It might be rounded up depending on the characteristics of the DASD.

The secondary extent size that was specified when the page set was defined is ignored; dynamic expansion can occur if it was zero or not specified.

NONE

No further page set expansion is to take place.


ALTER QMGR

Use the MQSC command ALTER QMGR to alter the queue manager parameters for the local queue manager.
IBM i UNIX and Linux Windows z/OS
X X X 2CR

Parameters not specified in the ALTER QMGR command result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column; see Using commands on z/OS . This information is divided into three sections:


ALTER QMGR


Synonym : ALT QMGR

   
>>-ALTER QMGR--+------------------------------+--+-------+------>
               '-| queue manager attributes |-'  '-FORCE-'   

   .-CMDSCOPE(' ')------------------. (2)   
>--+--------------------------------+--------------------------><
   |                            (1) |       
   +-CMDSCOPE--(-- qmgr-name-- )-----+       
   |             (1)                |       
   '-CMDSCOPE(*)--------------------'       

Queue manager attributes

|--+----------------------------------+------------------------->
   |                              (3) |   
   '-ACCTCONO--(--+-DISABLED-+--)-----'   
                  '-ENABLED--'            

>--+-----------------------------+------------------------------>
   |                         (3) |   
   '-ACCTINT--(--  integer--)-----'   

>--+----------------------------+------------------------------->
   |                        (3) |   
   '-ACCTMQI--(--+-OFF-+--)-----'   
                 '-ON--'            

>--+---------------------------+-------------------------------->
   |                       (4) |   
   '-ACCTQ--(--+-OFF--+--)-----'   
               +-ON---+            
               '-NONE-'            

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-ACTCHL--(--  integer--)-----'   

>--+------------------------------+----------------------------->
   '-ACTIVREC--(--+-DISABLED-+--)-'   
                  +-MSG------+        
                  '-QUEUE----'        

>--+----------------------------------+------------------------->
   |                              (3) |   
   '-ACTVCONO--(--+-DISABLED-+--)-----'   
                  '-ENABLED--'            

>--+----------------------------+------------------------------->
   |                        (3) |   
   '-ACTVTRC--(--+-OFF-+--)-----'   
                 '-ON--'            

>--+---------------------------------+-------------------------->
   |                             (2) |   
   '-ADOPTCHK--(--+-ALL-----+--)-----'   
                  +-NETADDR-+            
                  +-NONE----+            
                  '-QMNAME--'            

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-ADOPTMCA--(--+-ALL-+--)-----'   
                  '-NO--'            

>--+---------------------------------+-------------------------->
   '-AUTHOREV--(--+-DISABLED----+--)-'   
                  |         (5) |        
                  '-ENABLED-----'        

>--+----------------------------------+------------------------->
   |                              (2) |   
   '-BRIDGEEV--(--+-DISABLED-+--)-----'   
                  '-ENABLED--'            

>--+---------------------------+-------------------------------->
   |                       (3) |   
   '-CCSID--(--  integer--)-----'   

>--+---------------------------------+-------------------------->
   |                             (6) |   
   '-CERTVPOL--(--+-ANY-----+--)-----'   
                  '-RFC5280-'            

>--+-----------------------------------+------------------------>
   |                               (2) |   
   '-CFCONLOS--(--+-TERMINATE-+--)-----'   
                  '-TOLERATE--'            

>--+------------------------------+----------------------------->
   |                          (3) |   
   '-CHAD--(--+-DISABLED-+--)-----'   
              '-ENABLED--'            

>--+--------------------------------+--------------------------->
   |                            (3) |   
   '-CHADEV--(--+-DISABLED-+--)-----'   
                '-ENABLED--'            

>--+-----------------------------+------------------------------>
   |                         (4) |   
   '-CHADEXIT--(--  string--)-----'   

>--+------------------------------+----------------------------->
   |                          (2) |   
   '-CHIADAPS--(--  integer--)-----'   

>--+------------------------------+----------------------------->
   |                          (2) |   
   '-CHIDISPS--(--  integer--)-----'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-CHISERVP--(--  string--)-----'   

>--+-----------------------------+------------------------------>
   '-CHLAUTH--(--+-DISABLED-+--)-'   
                 '-ENABLED--'        

>--+--------------------------------+--------------------------->
   |                            (4) |   
   '-CHLEV--(--+-DISABLED--+--)-----'   
               +-ENABLED---+            
               '-EXCEPTION-'            

>--+-----------------------------+------------------------------>
   |                         (4) |   
   '-CLWLDATA--(--  string--)-----'   

>--+-----------------------------+------------------------------>
   |                         (4) |   
   '-CLWLEXIT--(--  string--)-----'   

>--+-----------------------------+------------------------------>
   |                         (4) |   
   '-CLWLLEN--(--  integer--)-----'   

>--+--------------------------+--------------------------------->
   '-CLWLMRUC--(--  integer--)-'   

>--+---------------------------+-------------------------------->
   '-CLWLUSEQ--(--+-LOCAL-+--)-'   
                  '-ANY---'        

>--+----------------------------+------------------------------->
   '-CMDEV--(--+-DISABLED--+--)-'   
               +-ENABLED---+        
               '-NODISPLAY-'        

>--+------------------------------+----------------------------->
   '-CONFIGEV--(--+-DISABLED-+--)-'   
                  '-ENABLED--'        

>--+-----------------------+--+----------------------+---------->
   '-CUSTOM--(--  string--)-'  '-DEADQ--(--  string--)-'   

>--+-------------------------+---------------------------------->
   '-DEFXMITQ--(--  string--)-'   

>--+--------------------------------+--------------------------->
   |                            (5) |   
   '-DEFCLXQ--(--+-SCTQ----+--)-----'   
                 '-CHANNEL-'            

>--+----------------------+--+-----------------------------+---->
   '-DESCR--(--  string--)-'  |                         (2) |   
                             '-DNSGROUP--(--  string--)-----'   

>--+---------------------------+-------------------------------->
   |                       (2) |   
   '-DNSWLM--(--+-NO--+--)-----'   
                '-YES-'            

>--+-----------------------------+------------------------------>
   '-EXPRYINT--(--+-OFF-----+--)-'   
                  '- integer-'        

>--+----------------------------------+------------------------->
   |                              (2) |   
   '- GROUPUR--(--+-DISABLED-+--)-----'   
                  '-ENABLED--'            

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-IGQ--(--+-DISABLED-+--)-----'   
             '-ENABLED--'            

>--+-------------------------------+---------------------------->
   |                           (2) |   
   '-IGQAUT--(--+-DEF-----+--)-----'   
                +-CTX-----+            
                +-ONLYIGQ-+            
                '-ALTIGQ--'            

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-IGQUSER--(--  string--)-----'   

>--+------------------------------+----------------------------->
   '-INHIBTEV--(--+-DISABLED-+--)-'   
                  '-ENABLED--'        

>--+--------------------------+--------------------------------->
   '-IPADDRV-- (--+-IPV4-+--)-'   
                  '-IPV6-'        

>--+-----------------------------+------------------------------>
   '-LOCALEV--(--+-DISABLED-+--)-'   
                 '-ENABLED--'        

>--+----------------------------------+------------------------->
   |                              (3) |   
   '-LOGGEREV--(--+-DISABLED-+--)-----'   
                  '-ENABLED--'            

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-LSTRTMR--(--  integer--)-----'   

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-LUGROUP--(--  string--)-----'   

>--+---------------------------+-------------------------------->
   |                       (2) |   
   '-LUNAME--(--  string--)-----'   

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-LU62ARM--(--  string--)-----'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-LU62CHL--(--  integer--)-----'   

>--+-----------------------------+------------------------------>
   '- MARKINT--(--+- integer-+--)-'   
                  '-NOLIMIT-'        

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-MAXCHL--(--  integer--)-----'   

>--+--------------------------+--------------------------------->
   '-MAXHANDS--(--  integer--)-'   

>--+-----------------------------+------------------------------>
   |                         (3) |   
   '-MAXMSGL--(--  integer--)-----'   

>--+-----------------------------+------------------------------>
   '-MAXPROPL--(--+- integer-+--)-'   
                  '-NOLIMIT-'        

>--+--------------------------+--------------------------------->
   '-MAXUMSGS--(--  integer--)-'   

>--+---------------------------+-------------------------------->
   '-MONACLS--(--+-QMGR---+--)-'   
                 +-OFF----+        
                 +-LOW----+        
                 +-MEDIUM-+        
                 '-HIGH---'        

>--+--------------------------+--+------------------------+----->
   '-MONCHL--(--+-OFF----+--)-'  '-MONQ--(--+-OFF----+--)-'   
                +-NONE---+                  +-NONE---+        
                +-LOW----+                  +-LOW----+        
                +-MEDIUM-+                  +-MEDIUM-+        
                '-HIGH---'                  '-HIGH---'        

>--+------------------------------+----------------------------->
   |                          (2) |   
   '-OPORTMAX--(--  integer--)-----'   

>--+------------------------------+----------------------------->
   |                          (2) |   
   '-OPORTMIN--(--  integer--)-----'   

>--+--------------------------+--------------------------------->
   '-PARENT--(-- parentname--)-'   

>--+-----------------------------+------------------------------>
   '-PERFMEV--(--+-DISABLED-+--)-'   
                 '-ENABLED--'        

>--+----------------------------+------------------------------->
   '-PSCLUS--(--+-ENABLED--+--)-'   
                '-DISABLED-'        

>--+----------------------------+------------------------------->
   '-PSMODE--(--+-ENABLED--+--)-'   
                +-COMPAT---+        
                '-DISABLED-'        

>--+----------------------------+------------------------------->
   '-PSNPMSG--(--+-DISCARD-+--)-'   
                 '-KEEP----'        

>--+----------------------------+------------------------------->
   '-PSNPRES--(--+-NORMAL--+--)-'   
                 +-SAFE----+        
                 +-DISCARD-+        
                 '-KEEP----'        

>--+-----------------------------+------------------------------>
   '-PSRTYCNT--(----integer----)-'   

>--+---------------------------+-------------------------------->
   '-PSSYNCPT--(--+-YES---+--)-'   
                  '-IFPER-'        

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-RCVTIME--(--  integer--)-----'   

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-RCVTMIN--(--  integer--)-----'   

>--+----------------------------------+------------------------->
   |                              (2) |   
   '-RCVTTYPE--(--+-MULTIPLY-+--)-----'   
                  +-ADD------+            
                  '-EQUAL----'            

>--+------------------------------+----------------------------->
   '-REMOTEEV--(--+-DISABLED-+--)-'   
                  '-ENABLED--'        

>--+-------------------------------+---------------------------->
   |                           (4) |   
   '-REPOS--(--  clustername--)-----'   

>--+----------------------------+------------------------------->
   |                        (4) |   
   '-REPOSNL--(--  nlname--)-----'   

>--+------------------------------+----------------------------->
   '-ROUTEREC--(--+-DISABLED-+--)-'   
                  +-MSG------+        
                  '-QUEUE----'        

>--+-------------------------------+---------------------------->
   |                           (3) |   
   '-SCHINIT--(--+-QMGR---+--)-----'   
                 '-MANUAL-'            

>--+--------------------------------+--------------------------->
   |                            (3) |   
   '-SCMDSERV--(--+-QMGR---+--)-----'   
                  '-MANUAL-'            

>--+------------------------------+----------------------------->
   |                          (2) |   
   '-SCYCASE--(--+-UPPER-+--)-----'   
                 '-MIXED-'            

>--+--------------------------------+--------------------------->
   |                            (2) |   
   '-SQQMNAME--(--+-USE----+--)-----'   
                  '-IGNORE-'            

>--+-------------------------+---------------------------------->
   '-SSLCRLNL--(--  nlname--)-'   

>--+----------------------------+------------------------------->
   |                        (6) |   
   '-SSLCRYP--(--  string--)-----'   

>--+---------------------------+-------------------------------->
   '-SSLEV--(--+-DISABLED-+--)-'   
               '-ENABLED--'        

>--+----------------------------+--+------------------------+--->
   |                        (7) |  '-SSLKEYR--(--  string--)-'   
   '-SSLFIPS--(--+-NO--+--)-----'                               
                 '-YES-'                                        

>--+--------------------------+--------------------------------->
   '-SSLRKEYC--(--  integer--)-'   

>--+------------------------------+----------------------------->
   |                          (2) |   
   '-SSLTASKS--(--  integer--)-----'   

>--+--------------------------------+--------------------------->
   |                            (3) |   
   '-STATACLS--(--+-QMGR---+--)-----'   
                  +-OFF----+            
                  +-LOW----+            
                  +-MEDIUM-+            
                  '-HIGH---'            

>--+-------------------------------+---------------------------->
   |                           (3) |   
   '-STATCHL--(--+-NONE---+--)-----'   
                 +-OFF----+            
                 +-LOW----+            
                 +-MEDIUM-+            
                 '-HIGH---'            

>--+-----------------------------+------------------------------>
   |                         (3) |   
   '-STATINT--(--  integer--)-----'   

>--+----------------------------+------------------------------->
   |                        (3) |   
   '-STATMQI--(--+-OFF-+--)-----'   
                 '-ON--'            

>--+---------------------------+-------------------------------->
   |                       (3) |   
   '-STATQ--(--+-OFF--+--)-----'   
               +-ON---+            
               '-NONE-'            

>--+------------------------------+----------------------------->
   '-STRSTPEV--(--+-ENABLED--+--)-'   
                  '-DISABLED-'        

>--+---------------------------------------+-------------------->
   |                                   (6) |   
   '-SUITEB--(--+-NONE------------+--)-----'   
                +-128_BIT---------+            
                +-192_BIT---------+            
                '-128_BIT,192_BIT-'            

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-TCPCHL--(--  integer--)-----'   

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-TCPKEEP--(--+-NO--+--)-----'   
                 '-YES-'            

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-TCPNAME--(--  string--)-----'   

>--+----------------------------------+------------------------->
   |                              (2) |   
   '-TCPSTACK--(--+-SINGLE---+--)-----'   
                  '-MULTIPLE-'            

>--+----------------------------+------------------------------->
   |                        (2) |   
   '-TRAXSTR--(--+-YES-+--)-----'   
                 '-NO--'            

>--+-----------------------------+------------------------------>
   |                         (2) |   
   '-TRAXTBL--(--  integer--)-----'   

>--+--------------------------+--+-------------------------+----|
   '-TREELIFE-- (-- integer--)-'  '-TRIGINT--(--  integer--)-'   


Notes:

  1. Valid only on z/OS when the queue manager is a member of a queue-sharing group.
  2. Valid only on z/OS.
  3. Valid only on IBM i, UNIX, Linux, and Windows.
  4. Valid only on z/OS, UNIX, Linux, and Windows.
  5. Not valid on z/OS.
  6. Valid only on UNIX, Linux, and Windows.
  7. Not valid on IBM i


Parameter descriptions for ALTER QMGR

The parameters you specify override the current values. Attributes that you do not specify are unchanged.

Note:

  1. If you do not specify any parameters, the command completes successfully, but no queue manager options are changed.
  2. Changes made using this command persist when the queue manager is stopped and restarted.

FORCE

Specify this parameter to force completion of the command if both of the following are true:

  • The DEFXMITQ parameter is specified
  • An application has a remote queue open, the resolution for which would be affected by this change

If FORCE is not specified in these circumstances, the command is unsuccessful.


Queue manager parameters

These parameters are the queue manager parameters for the ALTER QMGR command:

ACCTCONO

Specifies whether applications can override the settings of the ACCTQ and ACCTMQI queue manager parameters:

DISABLED

Applications cannot override the settings of the ACCTQ and ACCTMQI parameters.

This is the queue manager's initial default value.

ENABLED

Applications can override the settings of the ACCTQ and ACCTMQI parameters by using the options field of the MQCNO structure of the MQCONNX API call.

Changes to this parameter are effective for connections to the queue manager that occur after the change.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

ACCTINT(integer)

The time interval, in seconds, at which intermediate accounting records are written.

Specify a value in the range 1 through 604800.

Changes to this parameter are effective for connections to the queue manager that occur after the change.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

ACCTMQI

Specifies whether accounting information for MQI data is to be collected:

OFF

MQI accounting data collection is disabled.

This is the queue manager's initial default value.

ON

MQI accounting data collection is enabled.

If queue manager attribute ACCTCONO is set to ENABLED, the value of this parameter can be overridden using the options field of the MQCNO structure.

Changes to this parameter are effective for connections to the queue manager that occur after the change.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

ACCTQ

Specifies whether accounting data is to be collected for all queues. On z/OS, the data collected is class 3 accounting data (thread-level and queue-level accounting).

OFF

Accounting data collection is disabled for all queues which specify QMGR as the value for their ACCTQ parameter.

ON

Accounting data collection is enabled for all queues which specify QMGR as the value of their ACCTQ parameter. On z/OS systems, you must switch on class 3 accounting by the START TRACE command.

NONE

Accounting data collection for all queues is disabled regardless of the value of the ACCTQ parameter of the queue.

Changes to this parameter are effective only for connections to the queue manager occurring after the change to the parameter.

ACTCHL(integer )

The maximum number of channels that can be active at any time, unless the value is reduced below the number of currently active channels.

Specify a value from 1 through 9999 that is not greater than the value of MAXCHL. MAXCHL defines the maximum number of channels available.

If you change this value, you must also review the MAXCHL, LU62CHL, and TCPCHL values to ensure that there is no conflict of values

For an explanation of which channel states are considered active; see Channel states .

If the value of ACTCHL is reduced to less than its value when the channel initiator was initialized, channels continue to run until they stop. When the number of running channels falls below the value of ACTCHL , more channels can be started. Increasing the value of ACTCHL to more than its value when the channel initiator was initialized does not have immediate effect. The higher value of ACTCHL takes effect at the next channel initiator restart.

Sharing conversations do not contribute to the total for this parameter.

This parameter is valid on z/OS only.

ACTIVREC

Specifies whether activity reports are generated if requested in the message:

DISABLED

Activity reports are not generated.

MSG

Activity reports are generated and sent to the reply queue specified by the originator in the message causing the report.

This is the queue manager's initial default value.

QUEUE

Activity reports are generated and sent to SYSTEM.ADMIN.ACTIVITY.QUEUE
See Activity recording .
ACTVCONO

Specifies whether applications can override the settings of the ACTVTRC queue manager parameter:

DISABLED

Applications cannot override the settings of the ACTVTRC queue manager parameter.

This is the queue manager's initial default value.

ENABLED

Applications can override the settings of the ACTVTRC queue manager parameter by using the options field of the MQCNO structure of the MQCONNX API call.

Changes to this parameter are effective for connections to the queue manager that occur after the change.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

ACTVTRC

Specifies whether MQI application activity tracing information is to be collected:

OFF

WebSphere MQ MQI application activity tracing information collection is not enabled.

This is the queue manager's initial default value.

ON

WebSphere MQ MQI application activity tracing information collection is enabled.

If the queue manager attribute ACTVCONO is set to ENABLED, the value of this parameter can be overridden using the options field of the MQCNO structure.

Changes to this parameter are effective for connections to the queue manager that occur after the change.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

ADOPTCHK

Specifies which elements are checked to determine whether an MCA is adopted. The check is made when a new inbound channel is detected with the same name as an already active MCA.

ALL

Check the queue manager name and the network address. Perform this check to prevent your channels from being inadvertently or maliciously shut down.

This is the queue manager's initial default value.

NETADDR

Check the network address.

NONE

Do no checking.

QMNAME

Check the queue manager name.

This parameter is valid on z/OS only.

Changes to this parameter take effect the next time that a channel attempts to adopt an MCA.

ADOPTMCA

Specifies whether an orphaned instance of an MCA restarts immediately when a new inbound channel request matching the ADOPTCHK parameter is detected:

ALL

Adopt all channel types.

This is the queue manager's initial default value.

NO

Adoption of orphaned channels is not required.

This parameter is valid on z/OS only

Changes to this parameter take effect the next time that a channel attempts to adopt an MCA.

AUTHOREV

Specifies whether authorization (Not Authorized) events are generated:

DISABLED

Authorization events are not generated.

This is the queue manager's initial default value.

ENABLED

Authorization events are generated.

This value is not supported on z/OS.

BRIDGEEV

Specifies whether IMS™ Bridge events are generated.

DISABLED

IMS Bridge events are not generated.

This is the queue manager's initial default value.

ENABLED

All IMS Bridge events are generated.

This parameter is valid on z/OS only.

CCSID(integer )

The coded character set identifier for the queue manager. The CCSID is the identifier used with all character string fields defined by the API. If the CCSID in the message descriptor is set to the value MQCCSI_Q_MGR , the value applies to application data in the body of a message. The value is set when the message is put to a queue.

Specify a value in the range 1 through 65535. The CCSID specifies a value that is defined for use on your platform, and use a character set that is appropriate to the platform.

If you use this parameter to change the CCSID, applications that are running when the change is applied continue to use the original CCSID. Therefore, stop and restart all running applications before you continue including the command server and channel programs. To stop and restart all running applications, stop and restart the queue manager after changing the parameter value.

This parameter is not valid on z/OS. See Code page conversion for details of the supported CCSIDs for each platform.

CERTVPOL

Specifies which SSL/TLS certificate validation policy is used to validate digital certificates received from remote partner systems. This attribute can be used to control how strictly the certificate chain validation conforms to industry security standards.

ANY

Apply each of the certificate validation policies supported by the secure sockets library and accept the certificate chain if any of the policies considers the certificate chain valid. This setting can be used for maximum backwards compatibility with older digital certificates which do not comply with the modern certificate standards.

RFC5280

Apply only the RFC 5280 compliant certificate validation policy. This setting provides stricter validation than the ANY setting, but rejects some older digital certificates.

For more information about certificate validation policies, see Certificate validation policies in WebSphere MQ .

This parameter is valid on only UNIX, Linux, and Windows. Changes to the parameter take effect only after a REFRESH SECURITY TYPE(SSL) command is issued.

CFCONLOS

Specifies the action to be taken when the queue manager loses connectivity to the administration structure, or any CF structure with CFCONLOS set to ASQMGR

TERMINATE

The queue manager terminates when connectivity to CF structures is lost.

TOLERATE

The queue manager tolerates loss of connectivity to CF structures without terminating.

This parameter is valid on z/OS only.

All queue managers in the queue-sharing group must be at command level 710 or greater and OPMODE set to NEWFUNC for TOLERATE to be selected.

CHAD

Specifies whether receiver and server-connection channels can be defined automatically:

DISABLED

Auto-definition is not used.

This is the queue manager's initial default value.

ENABLED

Auto-definition is used.

Cluster-sender channels can always be defined automatically, regardless of the setting of this parameter.

This parameter is not valid on z/OS.

CHADEV

Specifies whether channel auto-definition events are generated.

DISABLED

Auto-definition events are not generated.

This is the queue manager's initial default value.

ENABLED

Auto-definition events are generated.

This parameter is not valid on z/OS.

CHADEXIT(string )

Auto-definition exit name.

If this name is nonblank, the exit is called when an inbound request for an undefined receiver, server-connection, or cluster-sender channel is received. It is also called when starting a cluster-receiver channel.

The format and maximum length of the name depends on the environment:

  • On Windows, it is of the form dllname(functionname) where dllname is specified without the suffix .DLL. The maximum length is 128 characters.
  • On IBM i, it is of the form:

          progname libname
    
    where program name occupies the first 10 characters and libname the second 10 characters (both blank-padded to the right if necessary). The maximum length of the string is 20 characters.
  • On UNIX, and Linux, it is of the form libraryname(functionname). The maximum length is 128 characters.
  • On z/OS, it is a load module name, the maximum length is eight characters.

On z/OS, this parameter applies only to cluster-sender and cluster-receiver channels.

CHIADAPS(integer )

The number of channel initiator adapter subtasks to use for processing WebSphere MQ calls.

Specify a value in the range 0 - 9999.

Suggested settings:

  • Test system: 8
  • Production system: 30

This parameter is valid on z/OS only.

Changes to this parameter take effect when the channel initiator is restarted.

CHIDISPS(integer )

The number of dispatchers to use in the channel initiator.

Specify a value in the range 1 through 9999.

Suggested settings:

  • Test system: 5
  • Production system: 20

This parameter is valid on z/OS only.

Changes to this parameter take effect when the channel initiator is restarted.

CHISERVP

This parameter is reserved for IBM use only; it is not for general use.

This parameter is valid on z/OS only.

CHLAUTH

Specifies whether the rules defined by channel authentication records are used. CHLAUTH rules can still be set and displayed regardless of the value of this attribute.

Changes to this parameter take effect the next time that an inbound channel attempts to start.

Channels that are currently started are unaffected by changes to this parameter.

DISABLED

Channel authentication records are not checked.

ENABLED

Channel authentication records are checked.
CHLEV

Specifies whether channel events are generated.

DISABLED

Channel events are not generated.

This is the queue manager's initial default value.

ENABLED

All channel events are generated.

EXCEPTION

All exception channel events are generated.
CLWLDATA(string )

Cluster workload exit data. The maximum length of the string is 32 characters.

This string is passed to the cluster workload exit when it is called.

CLWLEXIT(string )

Cluster workload exit name.

If this name is nonblank, the exit is called when a message is put to a cluster queue. The format and maximum length of the name depends on the environment:

  • On UNIX and Linux systems, it is of the form libraryname(functionname) . The maximum length is 128 characters.
  • On Windows, it is of the form dllname(functionname), where dllname is specified without the suffix .DLL. The maximum length is 128 characters.
  • On z/OS, it is a load module name. The maximum length is eight characters.
  • On IBM i, it is of the form:

          progname libname
    
    where program name occupies the first 10 characters and libname the second 10 characters (both blank-padded to the right if necessary). The maximum length is 20 characters.

This parameter is valid only on HP OpenVMS, IBM i, z/OS, UNIX, Linux, and Windows.

CLWLLEN(integer )

The maximum number of bytes of message data that is passed to the cluster workload exit.

Specify a value:

  • In the range 0 - 100 MB on WebSphere MQ for z/OS systems
  • In the range 0 - 999,999,999 on other platforms

This parameter is valid only on IBM i, z/OS, UNIX, Linux, and Windows.

CLWLMRUC(integer)

The maximum number of most recently used outbound cluster channels.

Specify a value in the range 1 through 999,999,999.

See CLWLMRUC queue manager attribute .

CLWLUSEQ

The attribute applies to queues with the queue attribute CLWLUSEQ set to QMGR. It specifies the behavior of an MQPUT operation when the target queue has a local instance and at least one remote cluster instance. It does not apply if the MQPUT originates from a cluster channel.

Specify either:

LOCAL

The local queue is the only target for MQPUT operations.

This is the queue manager's initial default value.

ANY

The queue manager treats the local queue as another instance of the cluster queue for the purposes of workload distribution.

See CLWLUSEQ queue manager attribute .

CMDEV

Specifies whether command events are generated:

DISABLED

Command events are not generated.

This is the queue manager's initial default value.

ENABLED

Command events are generated for all successful commands.

NODISPLAY

Command events are generated for all successful commands, other than DISPLAY commands.
CMDSCOPE

This parameter applies to z/OS only and specifies how the command is run when the queue manager is a member of a queue-sharing group.

'

The command is run on the queue manager on which it was entered.

qmgr-name

The command is run on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

You can specify a different queue manager. You can do so if you are using a queue-sharing group environment, and if the command server is enabled. You can then specify a different queue manager to the one on which the command is entered.

*

The command is run on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of entering this value is the same as entering the command on every queue manager in the queue-sharing group.

CONFIGEV

Specifies whether configuration events are generated:

ENABLED

Configuration events are generated. After setting this value, issue REFRESH QMGR TYPE(CONFIGEV) commands for all objects to bring the queue manager configuration up to date.

DISABLED

Configuration events are not generated.

This is the queue manager's initial default value.

CUSTOM(string)

The custom attribute for new features.

This attribute is reserved for the configuration of new features before named attributes are introduced. It can contain the values of zero or more attributes as pairs of attribute name and value, separated by at least one space. The attribute name and value pairs have the form NAME(VALUE) . Escape a single quotation mark with another single quotation mark.

No values are defined for Custom .

DEADQ(string )

The local name of a dead-letter queue (or undelivered-message queue) on which messages that cannot be routed to their correct destination are put.

The queue named must be a local queue; see Rules for naming WebSphere MQ objects .

DEFCLXQ

The DEFCLXQ attribute controls which transmission queue is selected by default by cluster-sender channels to get messages from, to send the messages to cluster-receiver channels.

SCTQ

All cluster-sender channels send messages from SYSTEM.CLUSTER.TRANSMIT.QUEUE. The correlID of messages placed on the transmission queue identifies which cluster-sender channel the message is destined for.

SCTQ is set when a queue manager is defined. This behavior is implicit in versions of WebSphere MQ, earlier than version 7.5. In earlier versions, the queue manager attribute DEFCLXQ was not present.

CHANNEL

Each cluster-sender channel sends messages from a different transmission queue. Each transmission queue is created as a permanent dynamic queue from the model queue SYSTEM.CLUSTER.TRANSMIT.MODEL.QUEUE.

If the queue manager attribute, DEFCLXQ, is set to CHANNEL, the default configuration is changed to cluster-sender channels being associated with individual cluster transmission queues. The transmission queues are permanent-dynamic queues created from the model queue SYSTEM.CLUSTER.TRANSMIT.MODEL.QUEUE. Each transmission queue is associated with one cluster-sender channel. As one cluster-sender channel services a cluster transmission queue, the transmission queue contains messages for only one queue manager in one cluster. You can configure clusters so that each queue manager in a cluster contains only one cluster queue. In this case, the message traffic from a queue manager to each cluster queue is transferred separately from messages to other queues.

DEFXMITQ(string )

Local name of the default transmission queue on which messages destined for a remote queue manager are put. The default transmission queue is used if there is no other suitable transmission queue defined.

The cluster transmission queue must not be used as the default transmission queue of the queue manager.

The queue named must be a local transmission queue; see Rules for naming WebSphere MQ objects .

DESCR(string )

Plain-text comment. It provides descriptive information about the queue manager.

It contains only displayable characters. The maximum length of the string is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

If the characters in the descriptive information are in the coded character set identifier (CCSID) for this queue manager they are translated correctly. They are translated when the descriptive information is sent to another queue manager. If they are not in the CCSID for this queue manager, they might be translated incorrectly.

DNSGROUP(string )

DNSGROUP applies if you are using Workload Manager for Dynamic Domain Name Services support (WLM/DNS). DNSGROUP is the name of the group that the TCP listener handling inbound transmissions for the queue-sharing group joins when using WLM/DNS.

The maximum length of this parameter is 18 characters.

If this name is blank, the queue-sharing group name is used.

This parameter is valid on z/OS only.

Changes to this parameter take effect for listeners that are later started. Listeners that are currently started are unaffected by changes to this parameter.

DNSWLM

Specifies whether the TCP listener that handles inbound transmissions for the queue-sharing group registers with WLM/DNS:

NO

The listener is not to register with Workload Manager.

This is the queue manager's initial default value.

YES

The listener is to register with Workload Manager.

This parameter is valid on z/OS only.

Changes to this parameter take effect for listeners that are later started. Listeners that are currently started are unaffected by changes to this parameter.

EXPRYINT

Specifies how often queues are scanned to discard expired messages:

OFF

Queues are not scanned. No internal expiry processing is performed.

integer

The approximate interval in seconds at which queues are scanned. Each time that the expiry interval is reached, the queue manager looks for candidate queues that are worth scanning to discard expired messages.

The queue manager maintains information about the expired messages on each queue, and therefore whether a scan for expired messages is worthwhile. So, only a selection of queues is scanned at any time.

The value must be in the range 1 through 99999999. The minimum scan interval used is 5 seconds, even if you specify a lower value.

You must set the same EXPRYINT value for all queue managers within a queue-sharing group that support this attribute. Shared queues are scanned by only one queue manager in a queue-sharing group. This queue manager is either the first queue manager to restart, or the first queue manager for which EXPRYINT is set.

Changes to EXPRYINT take effect when the current interval expires. Changes also take effect if the new interval is less than the unexpired portion of the current interval. In this case, a scan is scheduled and the new interval value takes immediate effect.

This parameter is valid only on z/OS.

GROUPUR

This parameter controls whether CICS and XA client applications can establish transactions with a GROUP unit of recovery disposition.

This parameter is valid only on z/OS. The property can be enabled only when the queue manager is a member of a queue-sharing group.

ENABLED

CICS and XA client applications can establish transactions with a group unit of recovery disposition by specifying a queue-sharing group name when they connect.

DISABLED

CICS and XA client applications must connect using a queue manager name.
IGQ

Specifies whether intra-group queuing is used.

This parameter is valid only on z/OS when the queue manager is a member of a queue-sharing group.

ENABLED

Message transfer between queue managers within a queue-sharing group Uses the shared transmission queue, SYSTEM.QSG.TRANSMIT.QUEUE .

DISABLED

Message transfer between queue managers within a queue-sharing group Uses non-shared transmission queues and channels. Queue managers that are not part of a queue-sharing group also use this mechanism.

If intra-group queuing is enabled, but the intra-group queuing agent is stopped, issue ALTER QMGR IGQ(ENABLED) to restart it.

IGQAUT

Specifies the type of authority checking and, therefore, the user IDs, to be used by the IGQ agent (IGQA). This parameter establishes the authority to put messages to a destination queue.

This parameter is valid only on z/OS when the queue manager is a member of a queue-sharing group.

DEF

Indicates that the default user ID is used to establish authority to put messages to a destination queue.

For a one user ID check, the default user ID is the user ID of a queue manager within the queue-sharing group. The default user ID is the user ID of the queue manager that put the messages to the SYSTEM.QSG.TRANSMIT.QUEUE . This user ID is referred to as the QSGSEND user ID.

For two user ID checks, the default second user ID is the IGQ user ID.

CTX

Indicates that the user ID from a UserIdentifier field is used to establish authority to put messages to a destination queue. The user ID is the UserIdentifier field in the message descriptor of a message on the SYSTEM.QSG.TRANSMIT.QUEUE.

For one user ID check, the QSGSEND user ID is used.

For two user ID checks, the QSGSEND user ID, the IGQ user ID and the alternate user ID are used. The alternate user ID is taken from the UserIdentifier field in the message descriptor of a message on the SYSTEM.QSG.TRANSMIT.QUEUE. The alternate user ID is referred to as ALT.

ONLYIGQ

Indicates that only the IGQ user ID is used to establish authority to put messages to a destination queue.

For all ID checks, the IGQ user ID is used.

ALTIGQ

Indicates that the IGQ user ID and the ALT user ID are used to establish authority to put messages to a destination queue.

For one user ID check, the IGQ user ID is used.

For two user ID checks, the IGQ user ID and the ALT user ID are used.

IGQUSER

Nominates a user ID to be used by the IGQ agent (IGQA) to establish authority to put messages to a destination queue. The user ID is referred to as the IGQ user ID.

This parameter is valid only on z/OS when the queue manager is a member of a queue-sharing group. Possible values are:

Blanks

Indicates that the user ID of the receiving queue manager within the queue-sharing group is used.

Specific user ID

Indicates that the user ID specified in the IGQUSER parameter of the receiving queue manager is used.

Note:

  1. As the receiving queue manager has authority to all queues it can access, security checking might not be performed for this user ID type.
  2. As the value of blanks has a special meaning, you cannot use IGQUSER to specify a real user ID of blanks.

INHIBTEV

Specifies whether inhibit events are generated. The events are generated for Inhibit Get and Inhibit Put)

ENABLED

Inhibit events are generated.

DISABLED

Inhibit events are not generated.

This is the queue manager's initial default value.

IPADDRV

Specifies which IP protocol is to be used for channel connections.

IPV4

The IPv4 IP address is to be used.

This is the queue manager's initial default value.

IPV6

The IPv6 IP address is to be used.

This parameter is used only in systems running IPv4 and IPv6. It applies to channels defined only with a TRPTYPE of TCP when either of the following two conditions is true:

  • The CONNAME parameter of the channel contains a host name that resolves to both an IPv4 and an IPv6 address, and the LOCLADDR parameter is not specified.
  • The value of the CONNAME and LOCLADDR parameters of the channel is a host name that resolves to both an IPv4 and IPv6 address.

LOCALEV

Specifies whether local error events are generated:

ENABLED

Local error events are generated.

DISABLED

Local error events are not generated.

This is the queue manager's initial default value.

LOGGEREV

Specifies whether recovery log events are generated:

DISABLED

Logger events are not generated.

This is the queue manager's initial default value.

ENABLED

Logger events are generated.

This parameter is valid only on IBM i, UNIX, Linux, and Windows.

LSTRTMR(integer )

The time interval, in seconds, between attempts by WebSphere MQ to restart a listener after an APPC or TCP/IP failure. When the listener is restarted on TCP/IP, it uses the same port and IP address as it used when it first started.

Specify a value in the range 5 through 9999.

This parameter is valid on z/OS only.

Changes to this parameter take effect for listeners that are later started. Listeners that are currently started are unaffected by changes to this parameter.

LUGROUP(string )

The generic LU name to be used by the LU 6.2 listener that handles inbound transmissions for the queue-sharing group. The maximum length of this parameter is eight characters.

If this name is blank, the listener cannot be used.

This parameter is valid on z/OS only.

Changes to this parameter take effect for listeners that are later started. Listeners that are currently started are unaffected by changes to this parameter.

LUNAME(string )

The name of the LU to use for outbound LU 6.2 transmissions. Set this parameter to be the same as the name of the LU to be used by the listener for inbound transmissions. The maximum length of this parameter is eight characters.

If this name is blank, the APPC/MVS default LU name is used. This name is variable, so LUNAME must always be set if you are using LU 6.2

This parameter is valid on z/OS only.

Changes to this parameter take effect when the channel initiator is restarted.

LU62ARM(string )

The suffix of the APPCPM member of SYS1.PARMLIB. This suffix nominates the LUADD for this channel initiator. When automatic restart manager (ARM) restarts the channel initiator, the z/OS command SET APPC= xx is issued.

If you do not provide a value for this parameter, no SET APPC=xx command is issued.

The maximum length of this parameter is two characters.

This parameter is valid on z/OS only.

Changes to this parameter take effect when the channel initiator is restarted.

LU62CHL(integer )

The maximum number of channels that can be current, or clients that can be connected, that use the LU 6.2 transmission protocol.

Specify a value 0- 9999 that is not greater than the value of MAXCHL. MAXCHL defines the maximum number of channels available. If you specify zero, the LU 6.2 transmission protocol is not used.

If you change this value, also review the MAXCHL, LU62CHL, and ACTCHL values. Ensure that there is no conflict of values and if necessary, raise the value of MAXCHL and ACTCHL.

This parameter is valid on z/OS only.

If the value of this parameter is reduced, any current channels that exceed the new limit continue to run until they stop.

MARKINT(integer)

The time interval, expressed in milliseconds, for which messages marked as browsed by a call to MQGET, with the get message option MQGMO_MARK_BROWSE_CO_OP, are expected to remain mark-browsed.

If messages are marked for more than approximately MARKINT milliseconds, the queue manager might automatically unmark messages. It might unmark messages that are marked as browsed for the cooperating set of handles.

This parameter does not affect the state of any message marked as browse by a call to MQGET with the get message option MQGMO_MARK_BROWSE_HANDLE.

Specify a value in the range 0 - 999,999,999.

The special value NOLIMIT indicates that the queue manager does not automatically unmark messages by this process.

MAXCHL(integer )

The maximum number of channels that can be current (including server-connection channels with connected clients).

Specify a value in the range 1- 9999. If you change this value, also review the TCPCHL, LU62CHL , and ACTCHL values to ensure that there is no conflict of values. If necessary, increase the number of active channels with the ACTCHL value. The values of ACTCHL , LU62CHL, and TCPCHL must not be greater than the maximum number of channels.

Suggested settings:

  • Test system: 200
  • Production system: 1000

For an explanation of which channel states are considered current; see Channel states .

If the value of this parameter is reduced, any current channels that exceed the new limit continue to run until they stop.

If the value of MAXCHL is reduced to less than its value when the channel initiator was initialized, channels continue to run until they stop. When the number of running channels falls below the value of MAXCHL, more channels can be started. Increasing the value of MAXCHL to more than its value when the channel initiator was initialized does not have immediate effect. The higher value of MAXCHL takes effect at the next channel initiator restart.

Sharing conversations do not contribute to the total for this parameter.

This parameter is valid on z/OS only.

MAXHANDS(integer )

The maximum number of open handles that any one connection can have at the same time.

This value is a value in the range 0 - 999,999,999.

MAXMSGL(integer )

The maximum length of messages allowed on queues for this queue manager.

This value is in the range 32 KB through 100 MB.

If you reduce the maximum message length for the queue manager, you must also reduce the maximum message length of the SYSTEM.DEFAULT.LOCAL.QUEUE definition. You must also reduce the maximum message length for all other queues connected to the queue manager. This change ensures that the limit of the queue manager is not less than the limit of any of the queues associated with it. If you do not change these lengths, and applications inquire only the MAXMSGL value of the queue, they might not work correctly.

Note that by adding the digital signature and key to the message, WebSphere MQ Advanced Message Security increases the length of the message.

MAXPROPL(integer)

The maximum length of property data in bytes that can be associated with a message.

This value is in the range 0 through 100 MB (104 857 600 bytes).

The special value NOLIMIT indicates that the size of the properties is not restricted, except by the upper limit.

MAXUMSGS(integer )

The maximum number of uncommitted messages within a sync point.

MAXUMSGS is a limit on the number of messages that can be retrieved, plus the number of messages that can be put, within any single sync point. The limit does not apply to messages that are put or retrieved outside sync point.

The number includes any trigger messages and report messages generated within the same unit of recovery.

If existing applications and queue manager processes are putting and getting a larger number of messages in sync point, reducing MAXUMSGS might cause problems. An example of queue manager processes that might be affected is clustering on z/OS.

Specify a value in the range 1 through 999,999,999. The default value is 10000.

MAXUMSGS has no effect on WebSphere MQ Telemetry. WebSphere MQ Telemetry tries to batch requests to subscribe, unsubscribe, send, and receive messages from multiple clients into batches of work within a transaction.

MONACLS

Controls the collection of online monitoring data for auto-defined cluster-sender channels:

QMGR

Collection of online monitoring data is inherited from the setting of the MONCHL parameter of the queue manager.

This is the queue manager's initial default value.

OFF

Monitoring for the channel is switched off.

LOW

Unless MONCHL is NONE, monitoring is switched on with a low rate of data collection with a minimal effect on system performance. The data collected is not likely to be the most current.

MEDIUM

Unless MONCHL is NONE, monitoring is switched on with a moderate rate of data collection with limited effect on system performance.

HIGH

Unless MONCHL is NONE, monitoring is switched on with a high rate of data collection with a likely effect on system performance. The data collected is the most current available.

A change to this parameter takes effect only on channels started after the change occurs. Any channel started before the change to the parameter continues with the value in force at the time that the channel started.

MONCHL

Controls the collection of online monitoring data for channels. The channels defined with MONCHL(QMGR) are affected by changing the QMGR MONCHL attribute.

OFF

Online monitoring data collection is turned off for channels specifying a value of QMGR in their MONCHL parameter.

This is the queue manager's initial default value.

NONE

Online monitoring data collection is turned off for channels regardless of the setting of their MONCHL parameter.

LOW

Online monitoring data collection is turned on, with a low ratio of data collection, for channels specifying a value of QMGR in their MONCHL parameter.

MEDIUM

Online monitoring data collection is turned on, with a moderate ratio of data collection, for channels specifying a value of QMGRin their MONCHL parameter.

HIGH

Online monitoring data collection is turned on, with a high ratio of data collection, for channels specifying a value of QMGR in their MONCHL parameter.

A change to this parameter takes effect only on channels started after the change occurs. Any channel started before the change to the parameter continues with the value in force at the time that the channel started.

MONQ

Controls the collection of online monitoring data for queues.

OFF

Online monitoring data collection is turned off for queues specifying a value of QMGR in their MONQ parameter.

This is the queue manager's initial default value.

NONE

Online monitoring data collection is turned off for queues regardless of the setting of their MONQ parameter.

LOW

Online monitoring data collection is turned on for queues specifying a value of QMGR in their MONQ parameter.

MEDIUM

Online monitoring data collection is turned on for queues specifying a value of QMGR in their MONQ parameter.

HIGH

Online monitoring data collection is turned on for queues specifying a value of QMGR in their MONQ parameter.

In contrast to MONCHL, there is no distinction between the values LOW, MEDIUM , and HIGH. These values all turn data collection on, but do not affect the rate of collection.

Changes to this parameter are effective only for queues opened after the parameter is changed.

OPORTMAX(integer )

The maximum value in the range of port numbers to be used when binding outgoing channels. When all the port numbers in the specified range are used, outgoing channels bind to any available port number.

Specify a value in the range 0 - 65535. A value of zero means that all outgoing channels bind to any available port number.

Specify a corresponding value for OPORTMIN to define a range of port numbers. Ensure that the value you specify for OPORTMAX is greater than or equal to the value you specify for OPORTMIN.

This parameter is valid on z/OS only.

Changes to this parameter take effect for channels that are later started. Channels that are currently started are unaffected by changes to this parameter.

OPORTMIN(integer )

The minimum value in the range of port numbers to be used when binding outgoing channels. When all the port numbers in the specified range are used, outgoing channels bind to any available port number.

Specify a value in the range 0 - 65535.

Specify a corresponding value for OPORTMAX to define a range of port numbers. Ensure that the value you specify for OPORTMIN is less than or equal to the value you specify for OPORTMAX .

This parameter is valid on z/OS only.

Changes to this parameter take effect for channels that are later started. Channels that are currently started are unaffected by changes to this parameter.

PARENT(parentname )

The name of the parent queue manager to which the local queue manager is to connect as its child in a hierarchy.

A blank value indicates that the queue manager has no parent queue manager.

If there is an existing parent queue manager it is disconnected.

WebSphere MQ hierarchical connections require that the queue manager attribute PSMODE is set to ENABLED.

The value of PARENT can be set to a blank value if PSMODE is set to DISABLED.

Before a queue manager can connect to a queue manager as its child in a hierarchy, channels must exist in both directions. The channels must exist between the parent queue manager and the child queue manager.

If a parent is already defined, the ALTER QMGR PARENT command disconnects from the original parent and sends a connection flow to the new parent queue manager.

Successful completion of the command does not mean that the action completed, or that it is going to complete successfully. Use the DIS PUBSUB TYPE(PARENT) ALL command to track the status of the requested parent relationship.

PERFMEV

Specifies whether performance-related events are generated:

ENABLED

Performance-related events are generated.

DISABLED

Performance-related events are not generated.

This is the queue manager's initial default value.

On WebSphere MQ for z/OS, all the queue managers in a queue-sharing group must have the same setting.

PSCLUS

Controls whether this queue manager participates in publish subscribe activity across any clusters in which it is a member. No clustered topic objects can exist in any cluster when modifying from ENABLED to DISABLED.

For more information about PSCLUS and inhibiting clusters publish/subscribe, see Inhibiting clustered publish/subscribe in a cluster .

ENABLED

This queue manager can define clustered topic objects, publish to subscribers on other queue managers, and register subscriptions that receive publications from other queue managers. All queue managers in the cluster running a version of WebSphere MQ that supports this option must specify PSCLUS(ENABLED) for the publish/subscribe activity to function as expected. ENABLED is the default value when a queue manager is created.

DISABLED

This queue manager cannot define clustered topic objects and ignores their definition on any other queue manager in the cluster.

Publications are not forwarded to subscribers elsewhere in the cluster, and subscriptions are not registered other than on the local queue manager.

To ensure that no publish/subscribe activity occurs in the cluster, all queue managers must specify PSCLUS(DISABLED). As a minimum, full repositories must be consistent in enabling or disabling publish/subscribe participation.
PSMODE

Controls whether the publish/subscribe engine and the queued publish/subscribe interface are running. It controls whether applications can publish or subscribe by using the application programming interface. It also controls whether the queues that are monitored by the queued publish/subscribe interface, are monitored.

Changing the PSMODE attribute can change the PSMODE status. Use DISPLAY PUBSUB , or on IBM i DSPMQM, to determine the current state of the publish/subscribe engine and the queued publish/subscribe interface.

COMPAT

The publish/subscribe engine is running. It is therefore possible to publish or subscribe by using the application programming interface.

The queued publish/subscribe interface is not running. Any publish/subscribe messages put to the queues that are monitored by the queued publish/subscribe interfaces are not acted upon.

Use this setting for compatibility with WebSphere Message Broker V6 or earlier versions that use this queue manager. WebSphere Message Broker must read the same queues from which the queued publish/subscribe interface would normally read.

DISABLED

The publish/subscribe engine and the queued publish/subscribe interface are not running. It is therefore not possible to publish or subscribe by using the application programming interface. Any publish/subscribe messages put to the queues that are monitored by the queued publish/subscribe interfaces are not acted upon.

If a queue manager is in a publish/subscribe cluster or hierarchy, it might receive publish/subscribe messages from other queue managers in the cluster or hierarchy. Examples of such messages are publication messages or proxy subscriptions. While PSMODE is set to DISABLED those messages are not processed. For this reason, disable any queue manager in a publish/subscribe cluster or hierarchy only for as long as there is little build-up of messages.

ENABLED

The publish/subscribe engine and the queued publish/subscribe interface are running. It is therefore possible to publish or subscribe by using the application programming interface and the queues that are being monitored by the queued publish/subscribe interface.

This is the queue manager's initial default value.

Note: If a queue manager is in a publish/subscribe cluster or hierarchy, and you change PSMODE to ENABLED, you might have to run the command REFRESH QMGR TYPE(PROXY). The command ensures that non-durable subscriptions are known across the cluster or hierarchy when PSMODE is set back to ENABLED. The circumstance in which you must run the command is as follows. If PSMODE is changed from ENABLED to DISABLED and back to ENABLED, and one or more non-durable subscriptions exist across all three stages.

PSNPMSG

If the queued publish/subscribe interface cannot process a non-persistent input message it might attempt to write the input message to the dead-letter queue. Whether it attempts to do so depends on the report options of the input message. The attempt to write the input message to the dead-letter queue might fail. In this case, the queued publish/subscribe interface might discard the input message. If MQRO_DISCARD_MSG is specified on the input message, the input message is discarded. If MQRO_DISCARD_MSG is not set, setting PSNPMSG to KEEP prevents the input message from being discarded. The default is to discard the input message.

Note: If you specify a value of IFPER for PSSYNCPT, you must not specify a value of KEEP for PSNPMSG .

DISCARD

Non-persistent input messages might be discarded if they cannot be processed.

KEEP

Non-persistent input messages are not discarded if they cannot be processed. In this situation, the queued publish/subscribe interface continues to try to process this message again at appropriate intervals and does not continue processing subsequent messages.
PSNPRES

The PSNPRES attribute controls whether the queued publish/subscribe interface writes an undeliverable reply message to the dead-letter queue, or discards the message. The choice is necessary if the queued publish/subscribe interface cannot deliver a reply message to the reply-to queue.

For new queue managers, the initial value is NORMAL. If you specify a value of IFPER for PSSYNCPT, you must not specify a value of KEEP or SAFE for PSNPRES .

For migrated queue managers on IBM i, UNIX, Linux, and Windows systems, the value depends on DLQNonPersistentResponse and DiscardNonPersistentResponse.

NORMAL

Non-persistent responses which cannot be placed on the reply queue are put on the dead-letter queue. If they cannot be placed on the dead-letter queue then they are discarded.

SAFE

Non-persistent responses which cannot be placed on the reply queue are put on the dead-letter queue. If the response cannot be sent and cannot be placed on the dead-letter queue, the queued publish/subscribe interface backs out of the current operation. It tries again at appropriate intervals, and does not continue processing subsequent messages.

DISCARD

Non-persistent responses which cannot be placed on the reply queue are discarded

KEEP

Non-persistent responses are not placed on the dead-letter queue or discarded. Instead the queued publish/subscribe interface backs out the current operation and then tries it again at appropriate intervals and does not continue processing subsequent messages.

PSRTYCNT

If the queued publish/subscribe interface fails to process a command message under sync point, the unit of work is backed out. The command tries to process the message a number of times again, before the publish/subscribe broker processes the command message according to its report options instead. This situation can arise for a number of reasons. For example, if a publish message cannot be delivered to a subscriber, and it is not possible to put the publication on the dead letter queue.

The initial value for this parameter on a new queue manager is 5.

Range is 0 - 999,999,999.

PSSYNCPT

Controls whether the queued publish/subscribe interface processes command messages (publishes or delete publication messages) under sync point.

YES

All messages are processed under sync point.

IFPER

Only persistent messages are part of the sync point

The initial value of the queue manager is IFPER.

RCVTIME(integer )

The approximate length of time that a TCP/IP channel waits to receive data, including heartbeats, from its partner before returning to the inactive state. This parameter applies only to message channels and not to MQI channels.

This number can be qualified as follows:

  • To specify that this number is a multiplier to apply to the negotiated HBINT value to determine how long a channel is to wait, set RCVTTYPE to MULTIPLY. Specify an RCVTIME value of zero or in the range 2 through 99. If you specify zero, the channel continues to wait indefinitely to receive data from its partner.
  • To specify that RCVTIME is the number of seconds to add to the negotiated HBINT value to determine how long a channel is to wait, set RCVTTYPE to ADD. Specify an RCVTIME value in the range 1 through 999999.
  • To specify that RCVTIME is a value, in seconds, that the channel is to wait, set RCVTTYPE to EQUAL. Specify an RCVTIME value in the range 0 - 999,999. If you specify zero, the channel continues to wait indefinitely to receive data from its partner.

This parameter is valid on z/OS only.

Changes to this parameter take effect for channels that are later started. Channels that are currently started are unaffected by changes to this parameter.

RCVTMIN(integer )

The minimum length of time that a TCP/IP channel waits to receive data, including heartbeats, from its partner before returning to an inactive state. This parameter applies only to message channels (and not to MQI channels).

The TCP/IP channel wait time is relative to the negotiated value of HBINT. If RCVTYPE is MULTIPLY, the resultant value might less than the RCVTMIN. In this case, the TCP/IP channel wait time is set to RCVTMIN.

Specify a value, in seconds, between zero and 999999.

This parameter is valid on z/OS only.

Changes to this parameter take effect for channels that are later started. Channels that are currently started are unaffected by changes to this parameter.

RCVTTYPE

The qualifier to apply to the value in RCVTIME .

MULTIPLY

Specifies that RCVTIME is a multiplier to be applied to the negotiated HBINT value to determine how long a channel waits.

ADD

Specifies that RCVTIME is a value, in seconds, to be added to the negotiated HBINT value to determine how long a channel waits.

EQUAL

Specifies that RCVTIME is a value, in seconds, representing how long the channel waits.

This parameter is valid on z/OS only.

Changes to this parameter take effect for channels that are later started. Channels that are currently started are unaffected by changes to this parameter.

REMOTEEV

Specifies whether remote error events are generated:

DISABLED

Remote error events are not generated.

This is the queue manager's initial default value.

ENABLED

Remote error events are generated.

If you are using the reduced function form of WebSphere MQ for z/OS supplied with WebSphere Application Server, only DISABLED is valid.

REPOS(clustername )

The name of a cluster for which this queue manager provides a repository manager service. The maximum length is 48 characters conforming to the rules for naming WebSphere MQ objects.

No more than one of the resultant values of REPOS and REPOSNL can be nonblank.

If you use the REPOS parameter to create a full repository queue manager, connect it to at least one other full repository queue manager in the cluster. Connect it using a cluster-sender channel. See the information in Components of a cluster for details about using cluster-sender channels with full repository queue managers.

This parameter is valid on IBM i, z/OS, UNIX, Linux, and Windows.

REPOSNL(nlname )

The name of a namelist of clusters for which this queue manager provides a repository manager service.

No more than one of the resultant values of REPOS and REPOSNL can be nonblank.

Both REPOS and REPOSNL might be blank, or REPOS might be blank and the namelist specified by REPOSNL is empty. In these cases, this queue manager does not have a full repository. It might be a client of other repository services that are defined in the cluster.

If you use the REPOSNL parameter to create a full repository queue manager, connect it to other full repository queue managers. Connect it to at least one other full repository queue manager in each cluster specified in the namelist using cluster-sender channels. See the information in Components of a cluster for details about using cluster-sender channels with full repository queue managers.

This parameter is valid on IBM i, z/OS, UNIX, Linux, and Windows.

ROUTEREC

Specifies whether trace-route information is recorded if requested in the message. If this parameter is not set to DISABLED, it controls whether any reply generated is sent to SYSTEM.ADMIN.TRACE.ROUTE.QUEUE, or to the destination specified by the message itself. If ROUTEREC is not DISABLED, messages not yet at the final destination might have information added to them.

DISABLED

Trace-route information is not recorded.

MSG

Trace-route information is recorded and sent to the destination specified by the originator of the message causing the trace route record.

This is the queue manager's initial default value.

QUEUE

Trace-route information is recorded and sent to SYSTEM.ADMIN.TRACE.ROUTE.QUEUE .
SCHINIT

Specifies whether the channel initiator starts automatically when the queue manager starts.

QMGR

The channel initiator starts automatically when the queue manager starts.

MANUAL

The channel initiator does not start automatically.

This parameter is valid only on IBM i, UNIX, Linux, and Windows.

SCMDSERV

Specifies whether the command server starts automatically when the queue manager starts.

QMGR

The command server starts automatically when the queue manager starts.

MANUAL

The command server does not start automatically.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

SCYCASE

Specifies whether the security profiles are uppercase or mixed case.

UPPER

The security profiles are uppercase only. However, MXTOPIC and GMXTOPIC are used for topic security, and can contain mixed-case profiles.

MIXED

The security profiles are mixed case. MQCMDS and MQCONN are used for command and connection security but they can contain only uppercase profiles.

Changes to SCYCASE become effective after you run the following command:

 REFFRESH SECURITY(*) TYPE(CLASSES) 

This parameter is valid only on z/OS

SQQMNAME

The SQQMNAME attribute specifies whether a queue manager in a queue-sharing group opens a shared queue in the same group directly. The processing queue manager calls MQOPEN for a shared queue and sets the ObjectQmgrName parameter for the queue. If the shared queue is in the same queue-sharing group as the processing queue manager, the queue can be opened directly by the processing queue manager. Set the SQQMNAME attribute to control if the queue is opened directly, or by the ObjectQmgrName queue manager.

USE

The ObjectQmgrName is used, and the appropriate transmission queue is opened.

IGNORE

The processing queue manager opens the shared queue directly. Setting the parameter to this value can reduce the traffic in your queue manager network.

This parameter is valid only on z/OS.

SSLCRLNL(nlname)

The name of a namelist of authentication information objects which are used to provide certificate revocation locations to allow enhanced TLS/SSL certificate checking.

If SSLCRLNL is blank, certificate revocation checking is not invoked unless one of the SSL certificates used contains an AuthorityInfoAcces s or CrlDistributionPoint X.509 certificate extension.

Changes to SSLCRLNL, or to the names in a previously specified namelist, or to previously referenced authentication information objects become effective either:

  • On IBM i, UNIX, Linux, and Windows systems when a new channel process is started.
  • For channels that run as threads of the channel initiator on IBM i, UNIX, Linux, and Windows systems, when the channel initiator is restarted.
  • For channels that run as threads of the listener on IBM i, UNIX, Linux, and Windows systems, when the listener is restarted.
  • On z/OS, when the channel initiator is restarted.
  • When a REFRESH SECURITY TYPE(SSL) command is issued.
  • On IBM i queue managers, this parameter is ignored. However, it is used to determine which authentication information objects are written to the AMQCLCHL.TAB file.

SSLCRYP(string)

Sets the name of the parameter string required to configure the cryptographic hardware present on the system.

All supported cryptographic hardware supports the PKCS #11 interface. Specify a string of the following format:

 GSK_PKCS11=<the PKCS #11 driver path and file name>
;<the PKCS #11 token label>;
<the PKCS #11 token password>;<symmetric cipher setting>
;
The PKCS #11 driver path is an absolute path to the shared library providing support for the PKCS #11 card. The PKCS #11 driver file name is the name of the shared library. An example of the value required for the PKCS #11 driver path and file name is /usr/lib/pkcs11/PKCS11_API.so

To access symmetric cipher operations through GSKit, specify the symmetric cipher setting parameter. The value of this parameter is either:

SYMMETRIC_CIPHER_OFF

Do not access symmetric cipher operations.

SYMMETRIC_CIPHER_ON

Access symmetric cipher operations.
If the symmetric cipher setting parameter is not specified, it has the same effect as specifying SYMMETRIC_CIPHER_OF F.

The maximum length of the string is 256 characters.

If you specify a string that is not in the format listed, you get an error.

When the SSLCRYP value is changed, the cryptographic hardware parameters specified become the ones used for new SSL connection environments. The new information becomes effective:

  • When a new channel process is started.
  • For channels that run as threads of the channel initiator, when the channel initiator is restarted.
  • For channels that run as threads of the listener, when the listener is restarted.
  • When a REFRESH SECURITY TYPE(SSL) command is issued.

SSLEV

Specifies whether SSL events are generated.

DISABLED

SSL events are not generated.

This is the queue manager's initial default value.

ENABLED

All SSL events are generated.
SSLFIPS

This parameter is valid only on z/OS, UNIX, Linux, and Windows systems.

SSLFIPS specifies whether only FIPS-certified algorithms are to be used if cryptography is carried out in WebSphere MQ, rather than in cryptographic hardware. If cryptographic hardware is configured, the cryptographic modules used are those modules provided by the hardware product. These might, or might not, be FIPS-certified to a particular level. Whether the modules are FIPS-certified depends on the hardware product in use. For more information about FIPS, see the Federal Information Processing Standards (FIPS) manual.

NO

If you set SSLFIPS to NO, you can use either FIPS certified or non-FIPS certified CipherSpecs.

If the queue manager runs without using cryptographic hardware, refer to the CipherSpecs listed in Specifying CipherSpecs .

This is the queue manager's initial default value.

YES

Specifies that only FIPS-certified algorithms are to be used in the CipherSpecs allowed on all SSL connections from and to this queue manager.

For a listing of appropriate FIPS 140-2 certified CipherSpecs; see Specifying CipherSpecs .

Changes to SSLFIPS become effective either:

  • On UNIX, Linux, and Windows systems, when a new channel process is started.
  • For channels that run as threads of the channel initiator on UNIX, Linux, and Windows systems, when the channel initiator is restarted.
  • For channels that run as threads of the listener on UNIX, Linux, and Windows systems, when the listener is restarted.
  • For channels that run as threads of a process pooling process, when the process pooling process is started or restarted and first runs an SSL channel. If the process pooling process has already run an SSL channel, and you want the change to become effective immediately, run the MQSC command REFRESH SECURITY TYPE(SSL). The process pooling process is amqrmppa on UNIX, Linux, and Windows systems.
  • On z/OS, when the channel initiator is restarted.
  • When aREFRESH SECURITY TYPE(SSL) command is issued, except on z/OS.

SSLKEYR(string)

The name of the Secure Sockets Layer key repository.

The maximum length of the string is 256 characters.

The format of the name depends on the environment:

  • On z/OS, it is the name of a key ring.
  • On IBM i, it is of the form pathname/keyfile, where keyfile is specified without the suffix .kdb , and identifies a GSKit key database file.

    If you specify *SYSTEM, WebSphere MQ uses the system certificate store as the key repository for the queue manager. The queue manager is registered as a server application in the Digital Certificate Manager (DCM). You can assign any server/client certificate in the system store to the queue manager, because you registered it as a server application.

    If you change the SSLKEYR parameter to a value other than *SYSTEM, WebSphere MQ unregisters the queue manager as an application with DCM.

  • On UNIX and Linux, it is of the form pathname/keyfile and on Windows pathname\keyfile , where keyfile is specified without the suffix .kdb, and identifies a GSKit key database file.

On IBM i, UNIX, Linux, and Windows systems, the syntax of this parameter is validated to ensure that it contains a valid, absolute, directory path.

If SSLKEYR is blank, channels using SSL fail to start. If SSLKEYR is set to a value that does not correspond to a key ring or key database file, channels using SSL also fail to start.

Changes to SSLKEYR become effective either:

  • On IBM i, UNIX, Linux, and Windows systems, when a new channel process is started.
  • For channels that run as threads of the channel initiator on IBM i, UNIX, Linux, and Windows systems, when the channel initiator is restarted.
  • For channels that run as threads of the listener on IBM i, UNIX, Linux, and Windows systems, when the listener is restarted.
  • For channels that run as threads of a process pooling process, amqrmppa, when the process pooling process is started or restarted and first runs an SSL channel. If the process pooling process has already run an SSL channel, and you want the change to become effective immediately, run the MQSC command REFRESH SECURITY TYPE(SSL).
  • On z/OS, when the channel initiator is restarted.
  • When a REFRESH SECURITY TYPE(SSL) command is issued.

SSLRKEYC(integer)

The number of bytes to be sent and received within an SSL conversation before the secret key is renegotiated. The number of bytes includes control information.

SSLRKEYC is used only by SSL channels which initiate communication from the queue manager. For example, the sender channel initiates communication in a sender and receiver channel pairing.

If a value greater than zero is specified, the secret key is also renegotiated before message data is sent or received following a channel heartbeat. The count of bytes until the next secret key renegotiation is reset after each successful renegotiation.

Specify a value in the range 0 - 999,999,999. A value of zero means that the secret key is never renegotiated. If you specify an SSL/TLS secret key reset count in the range 1 - 32767 bytes (32 KB), SSL/TLS channels use a secret key reset count of 32 KB. The larger reset count value avoids the cost of excessive key resets which would occur for small SSL/TLS secret key reset values.

Non-zero values less than 4096 (4 KB) might cause channels to fail to start, or might cause inconsistencies in the values of SSLKEYDA, SSLKEYTI, and SSLRKEYS.

SSLTASKS(integer)

The number of server subtasks to use for processing SSL calls. To use SSL channels, you must have at least two of these tasks running.

This parameter is valid only on z/OS.

This value is in the range 0 - 9999. To avoid problems with storage allocation, do not set the SSLTASKS parameter to a value greater than 50.

Changes to this parameter are effective when the channel initiator is restarted.

STATACLS

Specifies whether statistics data is to be collected for auto-defined cluster-sender channels:

QMGR

Collection of statistics data is inherited from the setting of the STATCHL parameter of the queue manager.

This is the queue manager's initial default value.

OFF

Statistics data collection for the channel is switched off.

LOW

Unless STATCHL is NONE, statistics data collection is switched on with a low ratio of data collection with a minimal effect on system performance.

MEDIUM

Unless STATCHL is NONE, statistics data collection is switched on with a moderate ratio of data collection.

HIGH

Unless STATCHL is NONE, statistics data collection is switched on with a high ratio of data collection.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

A change to this parameter takes effect only on channels started after the change occurs. Any channel started before the change to the parameter continues with the value in force at the time that the channel started.

STATCHL

Specifies whether statistics data is to be collected for channels:

NONE

Statistics data collection is turned off for channels regardless of the setting of their STATCHL parameter.

OFF

Statistics data collection is turned off for channels specifying a value of QMGR in their STATCHL parameter.

This is the queue manager's initial default value.

LOW

Statistics data collection is turned on, with a low ratio of data collection, for channels specifying a value of QMGR in their STATCHL parameter.

MEDIUM

Statistics data collection is turned on, with a moderate ratio of data collection, for channels specifying a value of QMGR in their STATCHL parameter.

HIGH

Statistics data collection is turned on, with a high ratio of data collection, for channels specifying a value of QMGR in their STATCHL parameter.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

A change to this parameter takes effect only on channels started after the change occurs. Any channel started before the change to the parameter continues with the value in force at the time that the channel started.

STATINT(integer)

The time interval, in seconds, at which statistics monitoring data is written to the monitoring queue.

Specify a value in the range 1 through 604800.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

Changes to this parameter take immediate effect on the collection of monitoring and statistics data.

STATMQI

Specifies whether statistics monitoring data is to be collected for the queue manager:

OFF

Data collection for MQI statistics is disabled.

This is the queue manager's initial default value.

ON

Data collection for MQI statistics is enabled.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

Changes to this parameter take immediate effect on the collection of monitoring and statistics data.

STATQ

Specifies whether statistics data is to be collected for queues:

NONE

Statistics data collection is turned off for queues regardless of the setting of their STATQ parameter.

OFF

Statistics data collection is turned off for queues specifying a value of QMGR or OFF in their STATQ parameter. OFF is the default value.

ON

Statistics data collection is turned on for queues specifying a value of QMGR or ON in their STATQ parameter.

This parameter is valid only on IBM i, UNIX, Linux, and Windows systems.

Statistics messages are generated only for queues which are opened after statistics collection is enabled. You do not need to restart the queue manager for the new value of STATQ to take effect.

STRSTPEV

Specifies whether start and stop events are generated:

ENABLED

Start and stop events are generated.

This is the queue manager's initial default value.

DISABLED

Start and stop events are not generated.
SUITEB

Specifies whether Suite B-compliant cryptography is used and what strength is required.

NONE

Suite B is not used. NONE is the default

128_BIT

Suite B 128-bit level security is used.

192_BIT

Suite B 192-bit level security is used

128_BIT,192_BIT

Both Suite B 128-bit and 192-bit level security is used
TCPCHL(integer )

The maximum number of channels that can be current, or clients that can be connected, that use the TCP/IP transmission protocol.

The maximum number of sockets used is the sum of the values in TCPCHL and CHIDISPS. The z/OS UNIX System Services MAXFILEPROC parameter (specified in the BPXPRMxx member of SYS1.PARMLIB) controls how many sockets each task is allowed, and thus how many channels each dispatcher is allowed. In this case, the number of channels using TCP/IP is limited to the value of MAXFILEPROC multiplied by the value of CHIDISPS.

Specify a value 0-9999. The value must not be greater than the value of MAXCHL . MAXCHL defines the maximum number of channels available. TCP/IP might not support as many as 9999 channels. If so, the value you can specify is limited by the number of channels TCP/IP can support. If you specify zero, the TCP/IP transmission protocol is not used.

If you change this value, also review the MAXCHL, LU62CHL, and ACTCHL values to ensure that there is no conflict of values. If necessary, raise the value of MAXCHL and ACTCHL.

If the value of this parameter is reduced, any current channels that exceed the new limit continue to run until they stop.

Sharing conversations do not contribute to the total for this parameter.

This parameter is valid on z/OS only.

TCPKEEP

Specifies whether the KEEPALIVE facility is to be used to check that the other end of the connection is still available. If it is unavailable, the channel is closed.

NO

The TCP KEEPALIVE facility is not to be used.

This is the queue manager's initial default value.

YES

The TCP KEEPALIVE facility is to be used as specified in the TCP profile configuration data set. The interval is specified in the KAINT channel attribute.

This parameter is valid on z/OS only.

Changes to this parameter take effect for channels that are later started. Channels that are currently started are unaffected by changes to this parameter.

TCPNAME(string )

The name of either the only, or default, TCP/IP system to be used, depending on the value of TCPSTACK. This name is the name of the z/OS UNIX System Services stack for TCP/IP, as specified in the SUBFILESYSTYPE NAME parameter in the BPXPRMxx member of SYS1.PARMLIB.

The maximum length of this parameter is eight characters.

This parameter is valid on z/OS only.

Changes to this parameter take effect when the channel initiator is restarted.

TCPSTACK

Specifies whether the channel initiator can use only the TCP/IP address space specified in TCPNAME, or optionally bind to any selected TCP/IP address.

SINGLE

The channel initiator can use only the TCP/IP address space specified in TCPNAME.

MULTIPLE

The channel initiator can use any TCP/IP address space available to it.

This parameter is valid on z/OS only.

Changes to this parameter take effect when the channel initiator is restarted.

TRAXSTR

Specifies whether the channel initiator trace starts automatically:

YES

Channel initiator trace is to start automatically.

NO

Channel initiator trace is not to start automatically.

This parameter is valid on z/OS only.

Changes to this parameter take effect when the channel initiator is restarted. To start or stop channel initiator trace without restarting the channel initiator, use the START TRACE or STOP TRACE commands after starting the channel initiator.

TRAXTBL(integer )

The size, in megabytes, of the trace data space of the channel initiator.

Specify a value in the range 2 through 2048.

This parameter is valid on z/OS only.

Note:

  1. Changes to this parameter take effect immediately; any existing trace table contents are lost.
  2. The CHINIT trace is stored in a dataspace called qmidCHIN.CSQXTRDS. When you use large z/OS data spaces, ensure that sufficient auxiliary storage is available on your system to support any related z/OS paging activity. You might also need to increase the size of your SYS1.DUMP data sets.

TREELIFE(integer)

The lifetime, in seconds of non-administrative topics.

Non-administrative topics are those topics created when an application publishes to, or subscribes on, a topic string that does not exist as an administrative node. When this non-administrative node no longer has any active subscriptions, this parameter determines how long the queue manager waits before removing that node. Only non-administrative topics that are in use by a durable subscription remain after the queue manager is recycled.

Specify a value in the range 0 through 604000. A value of 0 means that non-administrative topics are not removed by the queue manager.

TRIGINT(integer )

A time interval expressed in milliseconds.

The TRIGINT parameter is relevant only if the trigger type (TRIGTYPE ) is set to FIRST (see DEFINE QLOCAL for details). In this case trigger messages are normally generated only when a suitable message arrives on the queue, and the queue was previously empty. Under certain circumstances, however, an additional trigger message can be generated with FIRST triggering even if the queue was not empty. These additional trigger messages are not generated more often than every TRIGINT milliseconds; see Special case of trigger type FIRST .

Specify a value in the range 0 - 999,999,999.


ALTER queues

Use the MQSC ALTER command to alter the parameters of a queue. A queue might be a local queue (ALTER QLOCAL), alias queue (ALTER QALIAS), model queue (ALTER QMODEL), a remote queue, a queue-manager alias, or a reply-to queue alias (ALTER QREMOTE).

This section contains the following commands:

These commands are supported on the following platforms:
IBM i UNIX and Linux Windows z/OS
X X X 2CR

Parameters not specified in the ALTER queue commands result in the existing values for those parameters being left unchanged.

For an explanation of the symbols in the z/OS column, see Using commands on z/OS .


Parameter descriptions for ALTER QUEUE

The parameters that are relevant for each type of queue are tabulated in Table 1 . Each parameter is described after the table.

DEFINE and ALTER QUEUE parameters.

Cross-tabulation of queue parameters and queue types. If the parameter applies to the queue type, the cell contains a check mark.

 Parameter Local queue Model queue Alias queue Remote queue
ACCTQ X X    
BOQNAME X X    
BOTHRESH X X    
CFSTRUCT X X    
CLCHNAME X X    
CLUSNL X   X X
CLUSTER X   X X
CLWLPRTY X   X X
CLWLRANK X   X X
CLWLUSEQ X      
CMDSCOPE X X X X
CUSTOM X X X X
DEFBIND X   X X
DEFPRESP X X X X
DEFPRTY X X X X
DEFPSIST X X X X
DEFREADA X X X  
DEFSOPT X X    
DEFTYPE X X    
DESCR X X X X
DISTL X X    
FORCE X   X X
GET X X X  
HARDENBO or NOHARDENBO X X    
INDXTYPE X X    
INITQ X X    
LIKE X X X X
MAXDEPTH X X    
MAXMSGL X X    
MONQ X X    
MSGDLVSQ X X    
NOREPLACE X X X X
NPMCLASS X X    
PROCESS X X    
PROPCTL X X X  
PUT X X X X
queue-name X X X X
QDEPTHHI X X    
QDEPTHLO X X    
QDPHIEV X X    
QDPLOEV X X    
QDPMAXEV X X    
QSGDISP X X X X
QSVCIEV X X    
QSVCINT X X    
REPLACE X X X X
RETINTVL X X    
RNAME       X
RQMNAME       X
SCOPE X   X X
SHARE or NOSHARE X X    
STATQ X X    
STGCLASS X X    
TARGET     X  
TARGQ     X  
TARGTYPE     X  
TRIGDATA X X    
TRIGDPTH X X    
TRIGGER or NOTRIGGER X X    
TRIGMPRI X X    
TRIGTYPE X X    
USAGE X X    
XMITQ       X

queue-name

Local name of the queue, except the remote queue where it is the local definition of the remote queue.

The name must not be the same as any other queue name of any queue type currently defined on this queue manager, unless you specify REPLACE or ALTER. See Rules for naming WebSphere MQ objects .

ACCTQ

Specifies whether accounting data collection is to be enabled for the queue. On z/OS, the data collected is class 3 accounting data (thread-level and queue-level accounting). In order for accounting data to be collected for this queue, accounting data for this connection must also be enabled. Turn on accounting data collection by setting either the ACCTQ queue manager attribute, or the options field in the MQCNO structure on the MQCONNX call.

QMGR

The collection of accounting data is based on the setting of the ACCTQ parameter on the queue manager definition.

ON

Accounting data collection is enabled for the queue unless the ACCTQ queue manager parameter has a value of NONE. On z/OS systems, you must switch on class 3 accounting using the START TRACE command.

OFF

Accounting data collection is disabled for the queue.
BOQNAME(queue-name)

The excessive backout requeue name.

This parameter is supported only on local and model queues.

Use this parameter to set or change the back out queue name attribute of a local or model queue. Apart from allowing its value to be queried, the queue manager does nothing based on the value of this attribute. WebSphere MQ classes for JMS transfers a message that is backed out the maximum number of times to this queue. The maximum is specified by the BOTHRESH attribute.

BOTHRESH(integer)

The backout threshold.

This parameter is supported only on local and model queues.

Use this parameter to set or change the value of the back out threshold attribute of a local or model queue. Apart from allowing its value to be queried, the queue manager does nothing based on the value of this attribute. WebSphere MQ classes for JMS use the attribute to determine how many times back a message out. When the value is exceeded the message is transferred to the queue named by the BOQNAME attribute.

Specify a value in the range 0 - 999,999,999.

CFSTRUCT(structure-name)

Specifies the name of the coupling facility structure where you want messages stored when you use shared queues.

This parameter is supported only on z/OS for local and model queues.

The name:

  • Cannot have more than 12 characters
  • Must start with an uppercase letter (A - Z)
  • Can include only the characters A - Z and 0 - 9

The name of the queue-sharing group to which the queue manager is connected is prefixed to the name you supply. The name of the queue-sharing group is always four characters, padded with @ symbols if necessary. For example, if you use a queue-sharing group named NY03 and you supply the name PRODUCT7, the resultant coupling facility structure name is NY03PRODUCT7. The administrative structure for the queue-sharing group (in this case NY03CSQ_ADMIN) cannot be used for storing messages.

For ALTER QLOCAL, ALTER QMODEL, DEFINE QLOCAL with REPLACE, and DEFINE QMODEL with REPLACE the following rules apply:

  • On a local queue with QSGDISP(SHARED), CFSTRUCT cannot change.

    If you change either the CFSTRUCT or QSGDISP value you must delete and redefine the queue. To preserve any of the messages on the queue you must offload the messages before you delete the queue. Reload the messages after you redefine the queue, or move the messages to another queue.

  • On a model queue with DEFTYPE(SHAREDYN), CFSTRUCT cannot be blank.
  • On a local queue with a QSGDISP other than SHARED, or a model queue with a DEFTYPE other than SHAREDYN, the value of CFSTRUCT does not matter.

For DEFINE QLOCAL with NOREPLACE and DEFINE QMODEL with NOREPLACE, the coupling facility structure:

  • On a local queue with QSGDISP(SHARED) or a model queue with a DEFTYPE(SHAREDYN), CFSTRUCT cannot be blank.
  • On a local queue with a QSGDISP other than SHARED, or a model queue with a DEFTYPE other than SHAREDYN, the value of CFSTRUCT does not matter.

Note: Before you can use the queue, the structure must be defined in the coupling facility Resource Management (CFRM) policy data set.

CLCHNAME(channel name)

This parameter is supported only on transmission queues.

CLCHNAME is the generic name of the cluster-sender channels that use this queue as a transmission queue. The attribute specifies which cluster-sender channels send messages to a cluster-receiver channel from this cluster transmission queue. CLCHNAME is not supported on z/OS.

You can also set the transmission queue attribute CLCHNAME attribute to a cluster-sender channel manually. Messages that are destined for the queue manager connected by the cluster-sender channel are stored in the transmission queue that identifies the cluster-sender channel. They are not stored in the default cluster transmission queue. If you set the CLCHNAME attribute to blanks, the channel switches to the default cluster transmission queue when the channel restarts. The default queue is either SYSTEM.CLUSTER.TRANSMIT.ChannelName or SYSTEM.CLUSTER.TRANSMIT.QUEUE, depending on the value of the queue manager DEFCLXQ attribute.

By specifying asterisks, "*" , in CLCHNAME, you can associate a transmission queue with a set of cluster-sender channels. The asterisks can be at the beginning, end, or any number of places in the middle of the channel name string. CLCHNAME is limited to a length of 48 characters, MQ_OBJECT_NAME_LENGTH. A channel name is limited to 20 characters: MQ_CHANNEL_NAME_LENGTH.

The default queue manager configuration is for all cluster-sender channels to send messages from a single transmission queue, SYSTEM.CLUSTER.TRANSMIT.QUEUE. The default configuration can be changed by modified by changing the queue manager attribute, DEFCLXQ. The default value of the attribute is SCTQ. You can change the value to CHANNEL. If you set the DEFCLXQ attribute to CHANNEL, each cluster-sender channel defaults to using a specific cluster transmission queue, SYSTEM.CLUSTER.TRANSMIT.ChannelName.

CLUSNL(namelist name)

The name of the namelist that specifies a list of clusters to which the queue belongs.

This parameter is supported only on alias, local, and remote queues.

Changes to this parameter do not affect instances of the queue that are already open.

Only one of the resultant values of CLUSNL or CLUSTER can be nonblank; you cannot specify a value for both.

On local queues, this parameter cannot be set for transmission, SYSTEM.CHANNEL.xx, SYSTEM.CLUSTER.xx, or SYSTEM.COMMAND.xx queues, and on z/OS only, for SYSTEM.QSG.xx queues.

This parameter is valid only on AIX, HP Open VMS, HP-UX, Linux, Solaris, Windows, and z/OS.

CLUSTER(cluster name)

The name of the cluster to which the queue belongs.

This parameter is supported only on alias, local, and remote queues.

The maximum length is 48 characters conforming to the rules for naming WebSphere MQ objects. Changes to this parameter do not affect instances of the queue that are already open.

Only one of the resultant values of CLUSNL or CLUSTER can be nonblank; you cannot specify a value for both.

On local queues, this parameter cannot be set for transmission, SYSTEM.CHANNEL.xx, SYSTEM.CLUSTER.xx, or SYSTEM.COMMAND.xx queues, and on z/OS only, for SYSTEM.QSG.xx queues.

This parameter is valid only on AIX, HP Open VMS, HP-UX, Linux, Solaris, Windows, and z/OS.

CLWLPRTY(integer)

Specifies the priority of the queue for the purposes of cluster workload distribution. This parameter is valid only for local, remote, and alias queues. The value must be in the range zero through 9 where zero is the lowest priority and 9 is the highest. For more information about this attribute, see CLWLPRTY queue attribute .
CLWLRANK(integer)

Specifies the rank of the queue for the purposes of cluster workload distribution. This parameter is valid only for local, remote, and alias queues. The value must be in the range zero through 9 where zero is the lowest rank and 9 is the highest. For more information about this attribute, see CLWLRANK queue attribute .
CLWLUSEQ

Specifies the behavior of an MQPUT operation when the target queue has a local instance and at least one remote cluster instance. The parameter has no effect when the MQPUT originates from a cluster channel. This parameter is valid only for local queues.

QMGR

The behavior is as specified by the CLWLUSEQ parameter of the queue manager definition.

ANY

The queue manager is to treat the local queue as another instance of the cluster queue for the purposes of workload distribution.

LOCAL

The local queue is the only target of the MQPUT operation.
CMDSCOPE

This parameter applies to z/OS only. It specifies where the command is run when the queue manager is a member of a queue-sharing group.

CMDSCOPE must be blank, or the local queue manager, if QSGDISP is set to GROUP or SHARED.

''

The command is run on the queue manager on which it was entered.

QmgrName

The command is run on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

You can specify a queue manager name, other than the queue manager on which the command was entered. You can specify another name, only if you are using a queue-sharing group environment and if the command server is enabled.

*

The command is executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of * is the same as entering the command on every queue manager in the queue-sharing group.
CUSTOM(string)

The custom attribute for new features.

This attribute is reserved for the configuration of new features before separate attributes are introduced. It can contain the values of zero or more attributes as pairs of attribute name and value, separated by at least one space. The attribute name and value pairs have the form NAME(VALUE). Single quotation marks must be escaped with another single quotation mark.

This description is updated when features using this attribute are introduced. At the moment, there are no values for CUSTOM.

DEFBIND

Specifies the binding to be used when the application specifies MQOO_BIND_AS_Q_DEF on the MQOPEN call, and the queue is a cluster queue.

OPEN

The queue handle is bound to a specific instance of the cluster queue when the queue is opened.

NOTFIXED

The queue handle is not bound to any instance of the cluster queue. The queue manager selects a specific queue instance when the message is put using MQPUT. It changes that selection later, if the need arises.

GROUP

Allows an application to request that a group of messages is allocated to the same destination instance.

Multiple queues with the same name can be advertised in a queue manager cluster. An application can send all messages to a single instance, MQOO_BIND_ON_OPEN. It can allow a workload management algorithm to select the most suitable destination on a per message basis, MQOO_BIND_NOT_FIXED. It can allow an application to request that a group of messages be all allocated to the same destination instance. The workload balancing reselects a destination between groups of messages, without requiring an MQCLOSE and MQOPEN of the queue.

The MQPUT1 call always behaves as if NOTFIXED is specified.

This parameter is valid only on AIX, HP Open VMS, HP-UX, Linux, IBM i, Solaris, Windows, and z/OS.

DEFPRESP

Specifies the behavior to be used by applications when the put response type, within the MQPMO options, is set to MQPMO_RESPONSE_AS_Q_DEF.

SYNC

Put operations to the queue specifying MQPMO_RESPONSE_AS_Q_DEF are issued as if MQPMO_SYNC_RESPONSE is specified instead.

ASYNC

Put operations to the queue specifying MQPMO_RESPONSE_AS_Q_DEF are issued as if MQPMO_ASYNC_RESPONSE is specified instead; see MQPMO options (MQLONG) .
DEFPRTY(integer)

The default priority of messages put on the queue. The value must be in the range 0 - 9. Zero is the lowest priority, through to the MAXPRTY queue manager parameter. The default value of MAXPRTY is 9.
DEFPSIST

Specifies the message persistence to be used when applications specify the MQPER_PERSISTENCE_AS_Q_DEF option.

NO

Messages on this queue are lost across a restart of the queue manager.

YES

Messages on this queue survive a restart of the queue manager.

On z/OS, N and Y are accepted as synonyms of NO and YES.

DEFREADA

Specifies the default read ahead behavior for non-persistent messages delivered to the client. Enabling read ahead can improve the performance of client applications consuming non-persistent messages.

NO

Non-persistent messages are not read ahead unless the client application is configured to request read ahead.

YES

Non-persistent messages are sent to the client before an application requests them. Non-persistent messages can be lost if the client ends abnormally or if the client does not delete all the messages it is sent.

DISABLED

Read ahead of non-persistent messages in not enabled for this queue. Messages are not sent ahead to the client regardless of whether read ahead is requested by the client application.
DEFSOPT

The default share option for applications opening this queue for input:

EXCL

The open request is for exclusive input from the queue

SHARED

The open request is for shared input from the queue
DEFTYPE

Queue definition type.

This parameter is supported only on model queues.

PERMDYN

A permanent dynamic queue is created when an application issues an MQOPEN MQI call with the name of this model queue specified in the object descriptor (MQOD).

On z/OS, the dynamic queue has a disposition of QMGR.

SHAREDYN

This option is available on z/OS only.

A permanent dynamic queue is created when an application issues an MQOPEN API call with the name of this model queue specified in the object descriptor (MQOD).

The dynamic queue has a disposition of SHARED.

TEMPDYN

A temporary dynamic queue is created when an application issues an MQOPEN API call with the name of this model queue specified in the object descriptor (MQOD).

On z/OS, the dynamic queue has a disposition of QMGR.

Do not specify this value for a model queue definition with a DEFPSIST parameter of YES.

If you specify this option, do not specify INDXTYPE(MSGTOKEN).

DESCR(string)

Plain-text comment. It provides descriptive information about the object when an operator issues the DISPLAY QUEUE command.

It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).

Note: Use characters that are in the coded character set identifier (CCSID) of this queue manager. If you do not do so and if the information is sent to another queue manager, they might be translated incorrectly.

DISTL

DISTL sets whether distribution lists are supported by the partner queue manager.

YES

Distribution lists are supported by the partner queue manager.

NO

Distribution lists are not supported by the partner queue manager.

Note: You do not normally change this parameter, because it is set by the MCA. However you can set this parameter when defining a transmission queue if the distribution list capability of the destination queue manager is known.

This parameter is valid only on AIX, HP Open VMS, HP-UX, Linux, Solaris, and Windows.

FORCE

This parameter applies only to the ALTER command on alias, local and remote queues.

Specify this parameter to force completion of the command in the following circumstances.

For an alias queue, if both of the following are true:

  • The TARGQ parameter is specified
  • An application has this alias queue open

For a local queue, if both of the following are true:

  • The NOSHARE parameter is specified
  • More than one application has the queue open for input

FORCE is also needed if both of the following are true:

  • The USAGE parameter is changed
  • Either one or more messages are on the queue, or one or more applications have the queue open

Do not change the USAGE parameter while there are messages on the queue; the format of messages changes when they are put on a transmission queue.

For a remote queue, if both of the following are true:

  • The XMITQ parameter is changed
  • One or more applications has this queue open as a remote queue

FORCE is also needed if both of the following are true:

  • Any of the RNAME, RQMNAME, or XMITQ parameters are changed
  • One or more applications has a queue open that resolved through this definition as a queue manager alias

Note: FORCE is not required if this definition is in use as a reply-to queue alias only.

If FORCE is not specified in the circumstances described, the command is unsuccessful.

GET

Specifies whether applications are to be permitted to get messages from this queue:

ENABLED

Messages can be retrieved from the queue, by suitably authorized applications.

DISABLED

Applications cannot retrieve messages from the queue.

This parameter can also be changed using the MQSET API call.

HARDENBO&NOHARDENBO

Specifies whether hardening is used to ensure that the count of the number of times that a message is backed out is accurate.

This parameter is supported only on local and model queues.

HARDENBO

The count is hardened.

NOHARDENBO

The count is not hardened.

Note: This parameter affects only WebSphere MQ for z/OS. It can be set on other platforms but is ineffective.

INDXTYPE

The type of index maintained by the queue manager to expedite MQGET operations on the queue. For shared queues, the type of index determines the type of MQGET operations that can be used.

This parameter is supported only on local and model queues.

Messages can be retrieved using a selection criterion only if an appropriate index type is maintained, as the following table shows:

Index type required for different retrieval selection criteria

Retrieval selection criterion Index type required
  Shared queue Other queue
None (sequential retrieval) Any Any
Message identifier MSGID or NONE Any
Correlation identifier CORRELID Any
Message and correlation identifiers MSGID or CORRELID Any
Group identifier GROUPID Any
Grouping GROUPID GROUPID
Message token Not allowed MSGTOKEN
where the value of INDXTYPE parameter has the following values:

NONE

No index is maintained. Use NONE when messages are typically retrieved sequentially or use both the message identifier and the correlation identifier as a selection criterion on the MQGET call.

MSGID

An index of message identifiers is maintained. Use MSGID when messages are typically retrieved using the message identifier as a selection criterion on the MQGET call with the correlation identifier set to NULL.

CORRELID

An index of correlation identifiers is maintained. Use CORRELID when messages are typically retrieved using the correlation identifier as a selection criterion on the MQGET call with the message identifier set to NULL.

GROUPID

An index of group identifiers is maintained. Use GROUPID when messages are retrieved using message grouping selection criteria.

Note:

  1. You cannot set INDXTYPE to GROUPID if the queue is a transmission queue.
  2. The queue must use a CF structure at CFLEVEL(3), to specify a shared queue with INDXTYPE(GROUPID).

MSGTOKEN

An index of message tokens is maintained. Use MSGTOKEN when the queue is a WLM-managed queue that you are using with the Workload Manager functions of z/OS.

Note: You cannot set INDXTYPE to MSGTOKEN if:

  • The queue is a model queue with a definition type of SHAREDYN
  • The queue is a temporary dynamic queue
  • The queue is a transmission queue
  • You specify QSGDISP(SHARED)

For queues that are not shared and do not use grouping or message tokens, the index type does not restrict the type of retrieval selection. However, the index is used to expedite GET operations on the queue, so choose the type that corresponds to the most common retrieval selection.

If you are altering or replacing an existing local queue, you can change the INDXTYPE parameter only in the cases indicated in the following table:

Index type change permitted depending upon queue sharing and presence of messages in the queue.

Queue type NON-SHARED SHARED
Queue state Uncommitted activity No uncommitted activity, messages present No uncommitted activity, and empty Open or messages present Not open, and empty
Change INDXTYPE from: To: Change allowed?
NONE MSGID No Yes Yes No Yes
NONE CORRELID No Yes Yes No Yes
NONE MSGTOKEN No No Yes - -
NONE GROUPID No No Yes No Yes
MSGID NONE No Yes Yes No Yes
MSGID CORRELID No Yes Yes No Yes
MSGID MSGTOKEN No No Yes - -
MSGID GROUPID No No Yes No Yes
CORRELID NONE No Yes Yes No Yes
CORRELID MSGID No Yes Yes No Yes
CORRELID MSGTOKEN No No Yes - -
CORRELID GROUPID No No Yes No Yes
MSGTOKEN NONE No Yes Yes - -
MSGTOKEN MSGID No Yes Yes - -
MSGTOKEN CORRELID No Yes Yes - -
MSGTOKEN GROUPID No No Yes - -
GROUPID NONE No No Yes No Yes
GROUPID MSGID No No Yes No Yes
GROUPID CORRELID No No Yes No Yes
GROUPID MSGTOKEN No No Yes - -

This parameter is supported only on z/OS. On other platforms, all queues are automatically indexed.

INITQ(string)

The local name of the initiation queue on this queue manager, to which trigger messages relating to this queue are written; see Rules for naming WebSphere MQ objects .

This parameter is supported only on local and model queues.

LIKE(qtype-name)

The name of a queue, with parameters that are used to model this definition.

If this field is not completed, the values of undefined parameter fields are taken from one of the following definitions. The choice depends on the queue type:

Queue type Definition
Alias queue SYSTEM.DEFAULT.ALIAS.QUEUE
Local queue SYSTEM.DEFAULT.LOCAL.QUEUE
Model queue SYSTEM.DEFAULT.MODEL.QUEUE
Remote queue SYSTEM.DEFAULT.REMOTE.QUEUE

For example, not completing this parameter is equivalent to defining the following value of LIKE for an alias queue:

 LIKE(SYSTEM.DEFAULT.ALIAS.QUEUE)

If you require different default definitions for all queues, alter the default queue definitions instead of using the LIKE parameter.

On z/OS, the queue manager searches for an object with the name and queue type you specify with a disposition of QMGR, COPY, or SHARED. The disposition of the LIKE object is not copied to the object you are defining.

Note:

  1. QSGDISP (GROUP) objects are not searched.
  2. LIKE is ignored if QSGDISP(COPY) is specified.

MAXDEPTH(integer)

The maximum number of messages allowed on the queue.

This parameter is supported only on local and model queues.

On AIX, HP Open VMS, HP-UX, Linux, Solaris, Windows, and z/OS, specify a value in the range zero through 999999999.

This parameter is valid only on AIX, HP Open VMS, HP-UX, Linux, Solaris, Windows, and z/OS.

On any other WebSphere MQ platform, specify a value in the range zero through 640000.

Other factors can still cause the queue to be treated as full, for example, if there is no further hard disk space available.

If this value is reduced, any messages that are already on the queue that exceed the new maximum remain intact.

MAXMSGL(integer)

The maximum length (in bytes) of messages on this queue.

This parameter is supported only on local and model queues.

On AIX, HP Open VMS, HP-UX, Linux, Solaris, and Windows, specify a value in the range zero to the maximum message length for the queue manager. See the MAXMSGL parameter of the ALTER QMGR command, ALTER QMGR MAXMSGL .

On z/OS, specify a value in the range zero through 100 MB (104 857 600 bytes).

Message length includes the length of user data and the length of headers. For messages put on the transmission queue, there are additional transmission headers. Allow an additional 4000 bytes for all the message headers.

If this value is reduced, any messages that are already on the queue with length that exceeds the new maximum are not affected.

Applications can use this parameter to determine the size of buffer for retrieving messages from the queue. Therefore, the value can be reduced only if it is known that this reduction does not cause an application to operate incorrectly.

Note that by adding the digital signature and key to the message, WebSphere MQ Advanced Message Security increases the length of the message.

MONQ

Controls the collection of online monitoring data for queues.

This parameter is supported only on local and model queues.

QMGR

Collect monitoring data according to the setting of the queue manager parameter MONQ.

OFF

Online monitoring data collection is turned off for this queue.

LOW

If the value of the MONQ parameter of the queue manager is not NONE, online monitoring data collection is turned on for this queue.

MEDIUM

If the value of the MONQ parameter of the queue manager is not NONE, online monitoring data collection is turned on for this queue.

HIGH

If the value of the MONQ parameter of the queue manager is not NONE, online monitoring data collection is turned on for this queue.
There is no distinction between the values LOW, MEDIUM, and HIGH. These values all turn data collection on, but do not affect the rate of collection.

When this parameter is used in an ALTER queue command, the change is effective only when the queue is next opened.

MSGDLVSQ

Message delivery sequence.

This parameter is supported only on local and model queues.

PRIORITY

Messages are delivered (in response to MQGET API calls) in first-in-first-out (FIFO) order within priority.

FIFO

Messages are delivered (in response to MQGET API calls) in FIFO order. Priority is ignored for messages on this queue.

The message delivery sequence parameter can be changed from PRIORITY to FIFO while there are messages on the queue. The order of the messages already on the queue is not changed. Messages added to the queue later take the default priority of the queue, and so might be processed before some of the existing messages.

If the message delivery sequence is changed from FIFO to PRIORITY, the messages put on the queue while the queue was set to FIFO take the default priority.

Note: If INDXTYPE(GROUPID) is specified with MSGDLVSQ(PRIORITY), the priority in which groups are retrieved is based on the priority of the first message within each group. The priorities 0 and 1 are used by the queue manager to optimize the retrieval of messages in logical order. The first message in each group must not use these priorities. If it does, the message is stored as if it was priority two.

NPMCLASS

The level of reliability to be assigned to non-persistent messages that are put to the queue:

NORMAL

Non-persistent messages are lost after a failure, or queue manager shutdown. These messages are discarded on a queue manager restart.

HIGH

The queue manager attempts to retain non-persistent messages on this queue over a queue manager restart or switch over.

You cannot set this parameter on z/OS.

PROCESS(string)

The local name of the WebSphere MQ process.

This parameter is supported only on local and model queues.

This parameter is the name of a process instance that identifies the application started by the queue manager when a trigger event occurs; see Rules for naming WebSphere MQ objects .

The process definition is not checked when the local queue is defined, but it must be available for a trigger event to occur.

If the queue is a transmission queue, the process definition contains the name of the channel to be started. This parameter is optional for transmission queues on AIX, HP Open VMS, HP-UX, IBM i, Linux, Solaris, Windows, and z/OS. If you do not specify it, the channel name is taken from the value specified for the TRIGDATA parameter.

PROPCTL

Property control attribute. The attribute is optional. It is applicable to local, alias, and model queues. For information about how an administrator can use PROPCTL to control applications that access message properties, see Using the PROPCTL queue property to control message properties . Using the PROPCTL channel property to control message properties explains how to use PROPCTL to control the transfer of properties to queue managers running at version 6.0 or earlier.

PROPCTL options are as follows. The options do not affect message properties in the MQMD or MQMD extension.

ALL

Set ALL so that an application can read all the properties of the message either in MQRFH2 headers, or as properties of the message handle.

The ALL option enables applications that cannot be changed to access all the message properties from MQRFH2 headers. Applications that can be changed, can access all the properties of the message as properties of the message handle.

In some cases, the format of data in MQRFH2 headers in the received message might be different to the format in the message when it was sent.

COMPAT

Set COMPAT so that unmodified applications that expect JMS-related properties to be in an MQRFH2 header in the message data continue to work as before. Applications that can be changed, can access all the properties of the message as properties of the message handle.

If the message contains a property with a prefix of mcd., jms., usr., or mqext., all message properties are delivered to the application. If no message handle is supplied, properties are returned in an MQRFH2 header. If a message handle is supplied, all properties are returned in the message handle.

If the message does not contain a property with one of those prefixes, and the application does not provide a message handle, no message properties are returned to the application. If a message handle is supplied, all properties are returned in the message handle.

In some cases, the format of data in MQRFH2 headers in the received message might be different to the format in the message when it was sent.

FORCE

Force all applications to read message properties from MQRFH2 headers.

Properties are always returned in the message data in an MQRFH2 header regardless of whether the application specifies a message handle.

A valid message handle supplied in the MsgHandle field of the MQGMO structure on the MQGET call is ignored. Properties of the message are not accessible using the message handle.

In some cases, the format of data in MQRFH2 headers in the received message might be different to the format in the message when it was sent.

NONE

If a message handle is supplied, all the properties are returned in the message handle.

All message properties are removed from the message body before it is delivered to the application.

V6COMPAT

Set V6COMPAT so that applications that expect to receive the same MQRFH2 created by a sending application, can receive it as it was sent. The data in the MQRFH2 header is subject to character set conversion and numeric encoding changes. If the application sets properties using MQSETMP, the properties are not added to the MQRFH2 header created by the application. The properties are accessible only by using the MQINQMP call. The properties are transmitted in an extra MQRFH2 that is visible to channel exits, but not to MQI programs. If properties are inserted in the MQRFH2 header by the sending application, they are only accessible to the receiving application in the MQRFH2 header. You cannot query properties set this way by calling MQINQMP. This behavior of properties and application created MQRFH2 headers occurs only when V6COMPAT is set.

The receiving application can override the setting of V6COMPAT, by setting an MQGMO_PROPERTIES option, such as MQGMO_PROPERTIES_IN_HANDLE. The default setting of MQGMO_PROPERTIES is MQGMO_PROPERTIES_AS_Q_DEF, which leaves the property setting as defined by the PROPCTL setting on the resolved receiving queue.

Note: If the PSPROP subscription attribute is set to RFH2, the queue manager might add publish/subscribe properties to the psc folder in the application-created MQRFH2 header. Otherwise, the queue manager does not modify the application-created MQRFH2 header.

Special rules apply to setting V6COMPAT:

  1. You must set V6COMPAT on both of the queues accessed by MQPUT and MQGET.

    • You might find the effect of V6COMPAT does not require setting V6COMPAT on the queue that MQPUT writes to. The reason is that in many cases MQPUT does not reorganize the contents of an MQRFH2. Setting V6COMPAT has no apparent effect.
    • V6COMPAT appears to take effect only when it is set on the queue that is accessed by the application receiving the message.

    Despite these appearances, it is important you set V6COMPAT for both the sender and receiver of a message. In some circumstances, V6COMPAT works only if it is set at both ends of the transfer.

  2. If you set V6COMPAT on either an alias queue or a local queue, the result is the same.

    For example, an alias queue, QA1, has a target queue Q1. An application opens QA1. Whichever of the pairs of definitions in Figure 1 are set, the result is the same. A message is placed on Q1, with the MQRFH2 created by the application preserved exactly as it was when it was passed to the queue manager.

    Figure 1. Equivalent definitions of V6COMPAT

     DEFINE QLOCAL(Q1)  PROPCTL(V6COMPAT)
    DEFINE QALIAS(QA1) TARGET(Q1)
    

     DEFINE QLOCAL(Q1)
    DEFINE QALIAS(QA1) TARGET(Q1) PROPCTL(V6COMPAT)
    
  3. You can set V6COMPAT on the transmission queue, or a queue that resolves to a transmission queue. The result is to transmit any MQRFH2 in a message exactly as it was created by an application. You cannot set V6COMPAT on a QREMOTE definition.

    No other PROPCTL queue options behave this way. To control the way message properties are transmitted to a queue manager running WebSphere MQ version 6.0 or earlier, set the PROPCTL channel attribute; see Using the PROPCTL channel property to control message properties .

  4. For publish/subscribe, V6COMPAT must be set on a queue that resolves to the destination for a publication.

    • For unmanaged publish/subscribe, set V6COMPAT on a queue that is in the name resolution path for the queue passed to MQSUB. If a subscription is created administratively, set V6COMPAT on a queue that is in the name resolution path for the destination set for the subscription.
    • For managed publish/subscribe, set V6COMPAT on the model managed durable and managed non-durable queues for subscription topics. The default model managed queues are SYSTEM.MANAGED.DURABLE and SYSTEM.MANAGED.NDURABLE. By using different model queues for different topics, some publications are received with their original MQRFH2, and others with message property control set by other values of PROPCTL.
    • For queued publish/subscribe, you must identify the queues used by the publishing and subscribing applications. Set V6COMPAT on those queues, as if the publisher and subscriber are using point to point messaging.

The effect of setting V6COMPAT on a message sent to another queue manager is as follows:

To a version 7.1 queue manager

If a message contains internally set message properties, or message properties set by MQSETMP, the local queue manager adds an MQRFH2. The additional MQRFH2 is placed before any application created MQRFH2 headers. The local queue manager passes the modified message to the channel.

The new MQRFH2 header is flagged MQRFH_INTERNAL (X'8000000') in the MQRFH2 Flags field; see Flags (MQLONG) .

The channel message, and send and receive exits, are passed the entire message including the additional MQRFH2.

The action of the remote channel depends on whether V6COMPAT is set for the target queue. If it is set, then the internally set properties in the initial MQRFH2 are available to an application in the message handle. The application created MQRFH2 is received unchanged, except for character conversion and numeric encoding transformations.

To a version 7.0.1 queue manager

Internally set properties are discarded. The MQRFH2 header is transferred unmodified.

To a version 6.0 or earlier queue manager

Internally set properties are discarded. The MQRFH2 header is transferred unmodified. PROPCTL channel options are applied after internally set properties are discarded.
PUT

Specifies whether messages can be put on the queue.

ENABLED

Messages can be added to the queue (by suitably authorized applications).

DISABLED

Messages cannot be added to the queue.

This parameter can also be changed using the MQSET API call.

QDEPTHHI(integer)

The threshold against which the queue depth is compared to generate a Queue Depth High event.

This parameter is supported only on local and model queues.

This event indicates that an application put a message on a queue resulting in the number of messages on the queue becoming greater than or equal to the queue depth high threshold. See the QDPHIEV parameter.

The value is expressed as a percentage of the maximum queue depth (MAXDEPTH parameter), and must be in the range zero through 100 and no less than QDEPTHLO.

QDEPTHLO(integer)

The threshold against which the queue depth is compared to generate a Queue Depth Low event.

This parameter is supported only on local and model queues.

This event indicates that an application retrieved a message from a queue resulting in the number of messages on the queue becoming less than or equal to the queue depth low threshold. See the QDPLOEV parameter.

The value is expressed as a percentage of the maximum queue depth (MAXDEPTH parameter), and must be in the range zero through 100 and no greater than QDEPTHHI.

QDPHIEV

Controls whether Queue Depth High events are generated.

This parameter is supported only on local and model queues.

A Queue Depth High event indicates that an application put a message on a queue resulting in the number of messages on the queue becoming greater than or equal to the queue depth high threshold. See the QDEPTHHI parameter.

Note: The value of this parameter can change implicitly, and shared queues on z/OS affect the event. See the description of the Queue Depth High event in Queue Depth High .

ENABLED

Queue Depth High events are generated

DISABLED

Queue Depth High events are not generated
QDPLOEV

Controls whether Queue Depth Low events are generated.

This parameter is supported only on local and model queues.

A Queue Depth Low event indicates that an application retrieved a message from a queue resulting in the number of messages on the queue becoming less than or equal to the queue depth low threshold. See the QDEPTHLO parameter.

Note: The value of this parameter can change implicitly. For more information about this event, and the effect that shared queues on z/OS have on this event, see Queue Depth Low .

ENABLED

Queue Depth Low events are generated

DISABLED

Queue Depth Low events are not generated
QDPMAXEV

Controls whether Queue Full events are generated.

This parameter is supported only on local and model queues.

A Queue Full event indicates th