IBM Websphere MQ - Channel attributes in alphabetical order - Middlewar News
WebSphere MQ for some platforms may not implement all the attributes shown in the list. Exceptions and platform differences are mentioned in the individual attribute descriptions, where relevant.
The keyword that you can specify in MQSC is shown in brackets for each attribute. (Attributes that apply only to WebSphere MQ for z/OS with CICS do not have MQSC keywords.)
The attributes are arranged in alphabetical order, as follows:
* Auto start (AUTOSTART)
* Alter date (ALTDATE)
* Alter time (ALTTIME)
* Batch Heartbeat Interval (BATCHHB)
* Batch interval (BATCHINT)
* Batch size (BATCHSZ)
* Channel name (CHANNEL)
* Channel type (CHLTYPE)
* CICS profile name
* Cluster (CLUSTER)
* Cluster namelist (CLUSNL)
* Connection name (CONNAME)
* Convert message (CONVERT)
* Description (DESCR)
* Disconnect interval (DISCINT)
* Heartbeat interval (HBINT)
* Local Address (LOCLADDR)
* Long retry count (LONGRTY)
* Long retry interval (LONGTMR)
* LU 6.2 mode name (MODENAME)
* LU 6.2 transaction program name (TPNAME)
* Maximum message length (MAXMSGL)
* Maximum transmission size
* Message channel agent name (MCANAME)
* Message channel agent type (MCATYPE)
* Message channel agent user identifier (MCAUSER)
* Message exit name (MSGEXIT)
* Message exit user data (MSGDATA)
* Message-retry exit name (MREXIT)
* Message-retry exit user data (MRDATA)
* Message retry count (MRRTY)
* Message retry interval (MRTMR)
* Nonpersistent message speed (NPMSPEED)
* Password (PASSWORD)
* PUT authority (PUTAUT)
* Queue manager name (QMNAME)
* Receive exit name (RCVEXIT)
* Receive exit user data (RCVDATA)
* Security exit name (SCYEXIT)
* Security exit user data (SCYDATA)
* Send exit name (SENDEXIT)
* Send exit user data (SENDDATA)
* Sequence number wrap (SEQWRAP)
* Sequential delivery
* Short retry count (SHORTRTY)
* Short retry interval (SHORTTMR)
* SSL Cipher Specification (SSLCIPH)
* SSL Client Authentication (SSLCAUTH)
* SSL Peer (SSLPEER)
* Target system identifier
* Transmission queue name (XMITQ)
* Transport type (TRPTYPE)
* User ID (USERID)
Alter date (ALTDATE)
This is the date on which the definition was last altered, in the form yyyy-mm-dd.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS, iSeries, Solaris, and Windows systems only.
Alter time (ALTTIME)
This is the time at which the definition was last altered, in the form hh:mm:ss.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS, iSeries, Solaris, and Windows systems only.
Auto start (AUTOSTART)
In MQSeries for Compaq NonStop Kernel there is no SNA listener process. Each channel initiated from a remote system must have its own, unique TP name on which it can listen. Such channels must be defined to MQSC with the attribute AUTOSTART(ENABLED) to ensure that there is an LU 6.2 responder process listening on this TP name whenever the queue manager is started.
SNA channels defined AUTOSTART(DISABLED) do not listen for incoming SNA requests. LU 6.2 responder processes are not started for such channels.
Batch Heartbeat Interval (BATCHHB)
The batch heartbeat interval allows 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, otherwise a 'heartbeat' is sent to the receiving channel to check.
The value must be in the range zero through 999 999. A value of zero indicates that batch heartbeating is not used.
This parameter is valid for the following channel types:
* Sender
* Server
* Cluster sender
* Cluster receiver
Batch interval (BATCHINT)
WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for OS/2 Warp, and WebSphere MQ for z/OS without CICS, you can specify a period of time, in milliseconds, during which the channel will keep a batch open even if there are no messages on the transmission queue. You can specify any number of milliseconds, from zero through 999 999 999. The default value is zero.
If you do not specify a batch interval, the batch closes when the number of messages specified in BATCHSZ has been sent or when the transmission queue becomes empty. On lightly loaded channels, where the transmission queue frequently becomes empty the effective batch size may be much smaller than BATCHSZ.
You can use the BATCHINT attribute to make your channels more efficient by reducing the number of short batches. Be aware, however, that you may slow down the response time, because batches will last longer and messages will remain uncommitted for longer.
If you specify a BATCHINT, batches close only when one of the following conditions is met:
* The number of messages specified in BATCHSZ have been sent.
* There are no more messages on the transmission queue and a time interval of BATCHINT has elapsed while waiting for messages (since the first message of the batch was retrieved).
Note:
BATCHINT specifies the total amount of time that is spent waiting for messages. It does not include the time spent retrieving messages that are already available on the transmission queue, or the time spent transferring messages.
This attribute applies only to sender, cluster-sender, server, and cluster-receiver channels.
Batch size (BATCHSZ)
The batch size is the maximum number of messages to be sent before a syncpoint is taken. The batch size does not affect the way the channel transfers messages; messages are always transferred individually, but are committed or backed out as a batch.
To improve performance, you can set a batch size to define the maximum number of messages to be transferred between two syncpoints. The batch size to be used is negotiated when a channel starts up, and the lower of the two channel definitions is taken. On some implementations, the batch size is calculated from the lowest of the two channel definitions and the two queue manager MAXUMSGS values. The actual size of a batch can be less than this; for example, a batch completes when there are no messages left on the transmission queue or the batch interval expires.
A large value for the batch size increases throughput, but recovery times are increased because there are more messages to back out and re-send. The default BATCHSZ is 50, and you are advised to try that value first. You might choose a lower value for BATCHSZ if your communications are unreliable, making the need to recover more likely.
Syncpoint procedure needs a unique logical unit of work identifier to be exchanged across the link every time a syncpoint is taken, to coordinate batch commit procedures.
If the synchronized batch commit procedure is interrupted, an in-doubt situation may arise. In-doubt situations are resolved automatically when a message channel starts up. If this resolution is not successful, manual intervention may be necessary, making use of the RESOLVE command.
Some considerations when choosing the number for batch size:
* If the number is too large, the amount of queue space taken up on both ends of the link becomes excessive. Messages take up queue space when they are not committed, and cannot be removed from queues until they are committed.
* If there is likely to be a steady flow of messages, you can improve the performance of a channel by increasing the batch size. However, this has the negative effect of increasing restart times, and very large batches may also affect performance.
* If message flow characteristics indicate that messages arrive intermittently, a batch size of 1 with a relatively large disconnect time interval may provide a better performance.
* The number may be in the range 1 through 9999. However, for data integrity reasons, channels connecting to any of the current platforms, as described in this book, should specify a batch size greater than 1. (A value of 1 is for use with Version 1 products, apart from MQSeries for MVS/ESA.)
For z/OS using CICS it must also be at least 3 less than the value set by the ALTER QMGR MAXUMSGS command.
* Even though nonpersistent messages on a fast channel do not wait for a syncpoint, they do contribute to the batch-size count.
Channel name (CHANNEL)
Specifies the name of the channel definition. The name can contain up to 20 characters, although as both ends of a message channel must have the same name, and other implementations may have restrictions on the size, the actual number of characters may have to be smaller.
Where possible, channel names should be unique to one channel between any two queue managers in a network of interconnected queue managers.
The name must contain characters from the following list:
Alphabetic (A-Z, a-z; note that uppercase and lowercase are significant)
Numerics (0-9)
Period (.)
Forward slash (/)
Underscore (_)
Percentage sign (%)
Notes:
1. Embedded blanks are not allowed, and leading blanks are ignored.
2. On systems using EBCDIC Katakana, you cannot use lowercase characters.
Channel type (CHLTYPE)
Specifies the type of the channel being defined. The possible channel types are:
Message channel types:
* Sender
* Server (not MQSeries for VSE/ESA)
* Cluster-sender (WebSphere MQ for z/OS without CICS, WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp only)
* Receiver
* Requester (not MQSeries for VSE/ESA)
* Cluster-receiver (WebSphere MQ for z/OS without CICS, WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, only)
MQI channel types:
* Client-connection (MQSeries for OS/2 Warp, VSE/ESA, DOS, Windows 3.1, Windows 95, and Windows 98 only, and WebSphere MQ for Windows systems, and UNIX systems only)
Note:
Client-connection channels can also be defined on z/OS for use on other platforms.
* Server-connection (not WebSphere MQ for z/OS using CICS)
The two ends of a channel must have the same name and have compatible types:
* Sender with receiver
* Requester with server
* Requester with sender (for Call_back)
* Server with receiver (server is used as a sender)
* Client-connection with server-connection
* Cluster-sender with cluster-receiver
CICS profile name
This is for z/OS using CICS only, to give extra definition for the session characteristics of the connection when CICS performs a communication session allocation, for example to select a particular COS.
The name must be known to CICS and be one to eight alphanumeric characters long.
Cluster (CLUSTER)
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 cluster-sender and cluster-receiver channels. Up to one of the resultant values of CLUSTER or CLUSNL can be nonblank. If one of the values is nonblank, the other must be blank.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS without CICS, iSeries, Solaris, and Windows systems only.
Cluster namelist (CLUSNL)
The name of the namelist that specifies a list of clusters to which the channel belongs.
This parameter is valid only for cluster-sender and cluster-receiver channels. Up to one of the resultant values of CLUSTER or CLUSNL can be nonblank. If one of the values is nonblank, the other must be blank.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS without CICS, iSeries, Solaris, and Windows systems only.
Connection name (CONNAME)
This is the communications connection identifier. It specifies the particular communications link to be used by this channel.
This attribute is required for sender channels, cluster-sender channels, cluster-receiver channels, requester channels, and client-connection channels. It does not apply to receiver or server-connection channel types.
It is optional for server channels, except on z/OS using CICS where it is required in the channel definition, but is ignored unless the server is initiating the conversation.
For z/OS using CICS this attribute names the CICS communication connection identifier for the session to be used for this channel. The name is one to four alphanumeric characters long.
Otherwise, the name is up to 48 characters for z/OS, 264 characters for other platforms, and:
If the transport type is TCP
This is either the hostname or the network address of the remote machine (or the local machine for cluster-receiver channels). For example, (MACH1.ABC.COM) or (19.22.11.162). It may include the port number, for example (MACHINE(123)). It can include the IP_name of a z/OS dynamic DNS group or a network dispatcher input port.
If the transport type is UDP
For WebSphere MQ for AIX only, UDP is an alternative to TCP. As with TCP/IP, it is either the hostname or the network address of the remote machine.
If the transport type is LU 6.2
For MQSeries for OS/2, and WebSphere MQ for iSeries, Windows systems, and UNIX systems, give the fully-qualified name of the partner LU if the TPNAME and MODENAME are specified. For other versions or if the TPNAME and MODENAME are blank, give the CPI-C side information object name as described in the section in this book about setting up communication for your platform.
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. This can be specified in one of 3 forms:
luname, for example IGY12355
luname/TPname, for example IGY12345/APING
luname/TPname/modename, for example IGY12345/APINGD/#INTER
For the first form, the TP name and mode name must be specified for the TPNAME and MODENAME attributes ; otherwise these attributes 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 attributes 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(R) generic resources group.
For Compaq OpenVMS Alpha, specify the Gateway Node name, the Access Name to the channel program, and the TPNAME used to invoke the remote program. For example: CONNAME('SNAGWY.VMSREQUESTER(HOSTVR)').
For Compaq NonStop Kernel, the value depends on whether SNAX or ICE is used; see Chapter 20, Setting up communication in Compaq NonStop Kernel.
If the transmission protocol is NetBIOS
This is the NetBIOS name defined on the remote machine.
If the transmission protocol is SPX
This is an SPX-style address consisting of a 4-byte network address, a 6-byte node address and a 2-byte socket number. Enter these in hexadecimal, with the network and node addresses separated by a fullstop and the socket number in brackets. For example:
CONNAME('0a0b0c0d.804abcde23a1(5e86)')
If the socket number is omitted, the default WebSphere MQ SPX socket number is used. The default is X'5E86'.
Note:
The definition of transmission protocol is contained in Transport type (TRPTYPE).
Convert message (CONVERT)
Application message data is usually converted by the receiving application. However, if the remote queue manager is on a platform that does not support data conversion, use this channel attribute to specify that the message should be converted into the format required by the receiving system before transmission.
This attribute applies only to sender, cluster-sender, server, and cluster-receiver channels and does not apply to WebSphere MQ for z/OS with CICS.
The possible values are 'yes' and 'no'. If you specify 'yes', the application data in the message is converted before sending if you have specified one of the built-in format names, or a data conversion exit is available for a user-defined format (See the WebSphere MQ Application Programming Guide). If you specify 'no', the application data in the message is not converted before sending.
Description (DESCR)
This contains up to 64 bytes of text that describes the channel definition.
Note:
The maximum number of characters is reduced if the system is using a double byte character set (DBCS).
Use characters from the character set identified by the coded character set identifier (CCSID) for the queue manager to ensure that the text is translated correctly if it is sent to another queue manager.
Disconnect interval (DISCINT)
This is a time-out attribute, specified in seconds, for the server, cluster-sender, sender, and cluster-receiver channels. The interval is measured from the point at which a batch ends, that is when the batch size is reached or when the batch interval expires and the transmission queue becomes empty. If no messages arrive on the transmission queue during the specified time interval, the channel closes down. (The time is approximate.)
The close-down exchange of control data between the two ends of the channel includes an indication of the reason for closing. This ensures that the corresponding end of the channel remains available to start up again.
On all platforms except z/OS with CICS, you can specify any number of seconds from zero through 999 999 where a value of zero means no disconnect; wait indefinitely.
In z/OS using CICS, you can specify any number of seconds from zero through 9999 where a value of zero means disconnect as soon as the transmission queue is empty.
Note:
Performance is affected by the value specified for the disconnect interval.
A very low value (a few seconds) may cause excessive overhead in constantly starting up the channel. A very large value (more than an hour) could mean that system resources are unnecessarily held up. For WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and for WebSphere MQ for z/OS without CICS, you can also specify a heartbeat interval, so that when there are no messages on the transmission queue, the sending MCA will send a heartbeat flow to the receiving MCA, thus giving the receiving MCA an opportunity to quiesce the channel without waiting for the disconnect interval to expire. For these two values to work together effectively, the heartbeat interval value must be significantly lower than the disconnect interval value.
A value for the disconnect interval of a few minutes is a reasonable value to use. Change this value only if you understand the implications for performance, and you need a different value for the requirements of the traffic flowing down your channels.
For more information, see Stopping and quiescing channels.
Heartbeat interval (HBINT)
This attribute applies to WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and for WebSphere MQ for z/OS without CICS. You can specify 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 999 999. A value of zero means that no heartbeat flows are to be sent. The default value is 300. To be most useful, the value should be significantly less than the disconnect interval value.
This attribute is valid for sender, cluster-sender, server, receiver, cluster-receiver, and requester channels. Other than on z/OS and iSeries, it also applies to server-connection and client-connection channels. On these channels, heartbeats flow when a server MCA has issued an MQGET command with the WAIT option on behalf of a client application.
KeepAlive Interval (KAINT)
The KeepAlive Interval parameter is used to specify a time-out value for a channel.
The KeepAlive Interval parameter is a value passed to the communications stack specifying the KeepAlive timing for the channel. It allows you to specify a different keepalive value for each channel.
The value indicates a time, in seconds, and must be in the range 0 to 99999. A KeepAlive value of 0 indicates that channel KeepAlive is not enabled for the channel. When the KeepAlive Interval is set to 0, keepalive still occurs if a value has been specified for TCP/IP keepalive. On z/OS, this occurs when the TCPKEEP=YES parameter is specified in CSQ6CHIP. On other platforms, it occurs when the KEEPALIVE=YES parameter is specified in the TCP stanza in the distributed queuing configuration file.
This parameter is valid for all channel types. The value is ignored for all channels that have a TransportType (TRPTYPE) other than TCP or SPX
KAINT is only available on WebSphere MQ for z/OS.
Local Address (LOCLADDR)
This parameter specifies the local communications address for the channel. When a LOCLADDR value is specified, a channel that is stopped and then restarted continues to use the TCP/IP address specified in LOCLADDR. In recovery scenarios, this could be useful when the channel is communicating through a firewall, because it removes problems caused by the channel restarting with a different IP address, specified by the TCP/IP stack to which it is connected.
This parameter is valid for the following channel types:
* Sender
* Server
* Requester
* Client-connection
* Cluster-receiver
* Cluster-sender
The value used is the optional IP address and optional port or port range to be used for outbound TCP/IP communications. The format is as follows:
LOCLADDR([ip-addr][(low-port[,high-port])])
where "ip-addr" is specified in dotted alphanumeric or decimal form, for example, (MACH1.ABC.COM) or (19.22.11.162), and "low-port" and "high-port" are port numbers enclosed in parentheses. When two port values are specified, the channel binds to the address specified, using an available port within the range covered by the two port values. All values are optional.
The maximum length of the string is MQ_LOCAL_ADDRESS_LENGTH.
Note:
If the LOCLADDR port is in use, TCP/IP requires a time period to release the previously used port. If enough time is not left, and if only 1 LOCLADDR port is specified, the previously used port will not be available and so a random port will be chosen rather than the LOCLADDR port.
Long retry count (LONGRTY)
Specify the maximum number of times that the channel is to try allocating a session to its partner. If the initial allocation attempt fails, the short retry count number is decremented and the channel retries the remaining number of times. If it still fails, it retries a long retry count number of times with an interval of long retry interval between each try. If it is still unsuccessful, the channel closes down. The channel must subsequently be restarted with a command (it is not started automatically by the channel initiator).
(Retry is not attempted if the cause of failure is such that a retry is not likely to be successful.)
If the channel initiator or queue manager stops while the channel is retrying, the short retry count and long retry count are reset when the channel initiator or queue manager is restarted.
The long retry count attribute is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999 999. On z/OS using CICS, it may be set from zero through 999, and the long and short retries have the same count.
Note:
For OS/2, iSeries, UNIX systems, and Windows systems, in order for retry to be attempted a channel initiator must be running. The channel initiator must be monitoring the initiation queue specified in the transmission queue that the channel is using.
Long retry interval (LONGTMR)
The approximate interval in seconds that the channel is to wait before retrying to establish connection, during the long retry mode.
The interval between retries may be extended if the channel has to wait to become active.
The channel tries to connect long retry count number of times at this long interval, after trying the short retry count number of times at the short retry interval.
This is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999. On z/OS using CICS, it may be set from zero through 999.
LU 6.2 mode name (MODENAME)
This is for use with LU 6.2 connections. It gives extra definition for the session characteristics of the connection when a communication session allocation is performed.
When using side information for SNA communications, the mode name is defined in the CPI-C Communications Side Object or APPC side information and this attribute should be left blank; otherwise, it should be set to the SNA mode name.
The name must be one to eight alphanumeric characters long.
It is not valid for receiver or server-connection channels.
LU 6.2 transaction program name (TPNAME)
This is for use with LU 6.2 connections. It is the name, or generic name, of the transaction program (MCA) to be run at the far end of the link.
When using side information for SNA communications, the transaction program name is defined in the CPI-C Communications Side Object or APPC side information and this attribute should be left blank. Otherwise, this name is required by sender channels and requester channels except on z/OS using CICS where it is required in the channel definition but is ignored unless the server is initiating the conversation.
On platforms other than Compaq NonStop Kernel, the name can be up to 64 characters long. See Chapter 20, Setting up communication in Compaq NonStop Kernel for more information about that platform.
If the remote system is WebSphere MQ for z/OS using CICS, the transaction is:
* CKRC when you are defining a sender channel, or a server channel that acts as a sender
* CKSV when you are defining a requester channel of a requester-server pair
* CKRC when you are defining a requester channel of a requester-sender pair
On other platforms, this should be set to the SNA transaction program name, unless the CONNAME contains a side-object name in which case it should be set to blanks. The actual name is taken instead from the CPI-C Communications Side Object, or the APPC side information data set.
This information is set in a different way on other platforms; see the section in this book about setting up communication for your platform.
Maximum message length (MAXMSGL)
Specifies the maximum length of a message that can be transmitted on the channel.
On WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for OS/2 Warp, and VSE/ESA, specify a value greater than or equal to zero, and less than or equal to the maximum message length for the queue manager. See the MAXMSGL parameter of the ALTER QMGR command in the WebSphere MQ Script (MQSC) Command Reference book for more information. On other platforms, specify a value greater than or equal to zero, and less than or equal to 4 194 304 bytes. On WebSphere MQ for z/OS, specify a value greater than or equal to zero, and less than or equal to 104 857 600 bytes.
Because various implementations of WebSphere MQ systems exist on different platforms, the size available for message processing may be limited in some applications. This number must reflect a size that your system can handle without stress. When a channel starts up, the lower of the two numbers at each end of the channel is taken.
Notes:
1. If splitting of messages is not supported at either end of a channel, the maximum message size cannot be greater than the negotiated maximum transmission size.
2. The IBM WebSphere MQ products that this edition of the book applies to all support message splitting. Other WebSphere MQ products do not support message splitting.
3. For a comparison of the functions available, including the different maximum message lengths available see the WebSphere MQ Application Programming Guide.
4. You may use a maximum message size of 0 which will be taken to mean that the size is to be set to the local queue manager maximum value.
Maximum transmission size
If you are using CICS for distributed queuing on z/OS, you can specify the maximum transmission size, in bytes, that your channel is allowed to use when transmitting a message, or part of a message. When a channel starts up, this value is negotiated between the sending and receiving channels and the lower of the two values is agreed. The maximum size is 32 000 bytes on TCP/IP, but the maximum usable size is 32 000 bytes less the message descriptor. On VSE/ESA, the maximum size is 64 000 bytes on SNA.
Use this facility to ensure that system resources are not exceeded by your channels. Set this value in conjunction with the maximum message size, remembering to allow for message descriptors. An error situation may be created if the message size is allowed to exceed the transmission size, and message splitting is not supported.
Notes:
1. If channel startup negotiation results in a size less than the minimum required for the local channel program, no messages can be transferred.
Message channel agent name (MCANAME)
This attribute is reserved and should not be used.
Message channel agent type (MCATYPE)
For WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for OS/2 Warp, this attribute may be specified as a 'process' or a 'thread'. This parameter is valid for channel types of sender, cluster-sender (on WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp), server, requester, or cluster-receiver. On WebSphere MQ for z/OS, it is supported only for channels with a channel type of cluster-receiver. The MCA type is used when the channel is started locally to determine how the channel is run.
Advantages of running as a process include:
* Isolation for each channel providing greater integrity
* Job authority specific for each channel
* Control over job scheduling
Advantages of threads include:
* Much reduced use of storage
* Easier configuration by typing on the command line
* Faster execution - it is quicker to start a thread than to instruct the operating system to start a process
For channel types of sender, server, and requester, the default is 'process'. For channel types of cluster-sender and cluster-receiver, the default is 'thread'. These defaults can change during your installation.
If you specify 'process' on the channel definition, a RUNMQCHL process is started. If you specify 'thread', the MCA runs on a thread of the RUNMQCHI process. On the machine that receives the inbound allocates, the MCA runs as a thread or process depending on whether you use inetd or RUNMQLSR.
Message channel agent user identifier (MCAUSER)
This is not valid for z/OS using CICS; it is not valid for channels of client-connection type.
This attribute is the user identifier (a string) to be used by the MCA for authorization to access WebSphere MQ resources, including (if PUT authority is DEF) authorization to put the message to the destination queue for receiver or requester channels.
On WebSphere MQ for Windows, the user identifier may be domain-qualified by using the format, user@domain, where the domain must be either the Windows systems domain of the local system or a trusted domain.
If this attribute is blank, the MCA uses its default user identifier.
Message exit name (MSGEXIT)
Specifies the name of the user exit program to be run by the channel message exit. On AIX, Compaq Tru64 UNIX, HP-UX, iSeries, Linux, OS/2 Warp, Solaris, Windows systems, and z/OS this can be a list of names of programs that are to be run in succession. Leave blank, if no channel message exit is in effect.
The format and maximum length of this attribute depend on the platform, as for Receive exit name (RCVEXIT).
The message exit is not supported on client-connection or server-connection channels.
Message exit user data (MSGDATA)
Specifies user data that is passed to the channel message exits.
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, Windows systems, and z/OS, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, you can run a sequence of message exits. The limitations on the user data length and an example of how to specify MSGDATA for more than one exit are as shown for RCVDATA. See Receive exit user data (RCVDATA).
On other platforms the maximum length of the string is 32 characters.
Message-retry exit name (MREXIT)
Specifies the name of the user exit program to be run by the message-retry user exit. Leave blank if no message-retry exit program is in effect.
The format and maximum length of the name depend on the platform, as for Receive exit name (RCVEXIT).
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Message-retry exit user data (MRDATA)
This is passed to the channel message-retry exit when it is called.
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Message retry count (MRRTY)
This is the number of times the channel will retry before it decides it cannot deliver the message.
This attribute 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 for the exit's use, but the number of retries performed (if any) is controlled by the exit, and not by this attribute.
The value must be in the range 0 to 999 999 999. A value of zero means that no retries will be performed.
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Message retry interval (MRTMR)
This is the minimum interval of time that must pass before the channel can retry the MQPUT operation. This time interval is in milliseconds.
This attribute 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 for the exit's use, but the retry interval is controlled by the exit, and not by this attribute.
The value must be in the range 0 to 999 999 999. A value of zero means that the retry will be performed as soon as possible (provided that the value of MRRTY is greater than zero).
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Network-connection priority (NETPRTY)
The priority for the network connection. Distributed queuing will choose the path with the highest priority if there are multiple paths available. The value must be in the range 0 through 9; 0 is the lowest priority.
This parameter is valid only for cluster-receiver channels.
This parameter is valid only on AIX, HP-UX, Linux, OS/2 Warp, z/OS without CICS, iSeries, Solaris, and Windows systems.
Nonpersistent message speed (NPMSPEED)
For WebSphere MQ for AIX, HP-UX, iSeries, Solaris and Windows systems, WebSphere MQ for z/OS without CICS, and MQSeries V5.1 for Compaq Tru64 UNIX and OS/2 Warp, you can specify the speed at which nonpersistent messages are to be sent. You can specify either 'normal' or 'fast'. The default is 'fast', which means that nonpersistent messages on a channel are not transferred within transactions. The advantage of this is that nonpersistent messages become available for retrieval far more quickly. The disadvantage is that because they are not part of a transaction, messages may be lost if there is a transmission failure or if the channel stops when the messages are in transit. See Fast, nonpersistent messages.
This attribute is valid for sender, cluster-sender, server, receiver, cluster-receiver, and requester channels.
Password (PASSWORD)
You can specify a password of maximum length 12 characters, although only the first 10 characters are used.
The password may be used by the MCA when attempting to initiate a secure LU 6.2 session with a remote MCA. It is valid for channel types of sender, server, requester, or client-connection.
This does not apply to WebSphere MQ for z/OS except for client-connection channels.
PUT authority (PUTAUT)
Use this attribute to choose the type of security processing to be carried out by the MCA when executing:
* An MQPUT command to the destination queue (for message channels) , or
* An MQI call (for MQI channels).
You can choose one of the following:
Process security, also called default authority (DEF)
The default user ID is used.
On platforms, with Process security, you choose to have the queue security based on the user ID that the process is running under. The user ID is that of the process, or user, running the MCA at the receiving end of the message channel.
The queues are opened with this user ID and the open option MQOO_SET_ALL_CONTEXT.
Context security (CTX)
The alternate user ID is used from the context information associated with the message.
The UserIdentifier in the message descriptor is moved into the AlternateUserId field in the object descriptor. The queue is opened with the open options MQOO_SET_ALL_CONTEXT and MQOO_ALTERNATE_USER_AUTHORITY.
Only Message Channel Agent security (ONLYMCA)
The default user ID is used.
On platforms, with ONLYMCA security, you choose to have the queue security based on the user ID that the process is running under. The user ID is that of the process, or user, running the MCA at the receiving end of the message channel.
The queues are opened with this user ID and the open option MQOO_SET_ALL_CONTEXT.
Alternate Message Channel Agent security (ALTMCA)
This is the same as for ONLYMCA security but allows you to use context.
This parameter is only valid for receiver, requester, cluster-receiver, and server-connection channels. Context security and alternate message channel agent security values are not supported on server-connection channels.
Further details about:
* Context fields and open options can be found in the WebSphere MQ Application Programming Guide.
* Security can be found in the WebSphere MQ System Administration Guide for WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, or in the MQSeries System Administration book for your platform.
Note:
On WebSphere MQ for z/OS it is possible for two userids to be checked. Specific details of userids used by the channel initiator on z/OS can be found in the WebSphere MQ for z/OS System Setup Guide .
.
Queue manager name (QMNAME)
This applies to a channel of client-connection type only. It is the name of the queue manager or queue manager group to which a WebSphere MQ client application can request connection.
Receive exit name (RCVEXIT)
Specifies the name of the user exit program to be run by the channel receive user exit. In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, Windows systems, and z/OS, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp this can be a list of names of programs that are to be run in succession. Leave blank, if no channel receive user exit is in effect.
The format and maximum length of this attribute depend on the platform:
* On z/OS it is a load module name, maximum length 8 characters, except for client-connection channels where the maximum length is 128 characters.
* On iSeries it is of the form:
libname/progname
when specified in CL commands.
When specified in WebSphere MQ Commands (MQSC) it has the form:
progname libname
where progname 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 OS/2 and Windows it is of the form:
dllname(functionname)
where dllname is specified without the suffix ".DLL". The maximum length of the string is 40 characters.
* On UNIX systems, Compaq OpenVMS Alpha, and Compaq NonStop Kernel it is of the form:
libraryname(functionname)
The maximum length of the string is 40 characters.
On AIX, Compaq Tru64 UNIX, HP-UX, Linux, iSeries, OS/2 Warp, Solaris, Windows systems, and z/OS, you can specify a list of receive, send, or message exit program names. The names should be separated by a comma, a space, or both. For example:
RCVEXIT(exit1 exit2)
MSGEXIT(exit1,exit2)
SENDEXIT(exit1, exit2)
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, Windows systems, and z/OS, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, the total length of the string of exit names and strings of user data for a particular type of exit is limited to 500 characters. In WebSphere MQ for iSeries you can list up to 10 exit names. In WebSphere MQ for z/OS you can list up to eight exit names.
Receive exit user data (RCVDATA)
Specifies user data that is passed to the receive exit.
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp you can run a sequence of receive exits. The string of user data for a series of exits should be separated by a comma, spaces, or both. For example:
RCVDATA(exit1_data exit2_data)
MSGDATA(exit1_data,exit2_data)
SENDDATA(exit1_data, exit2_data)
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, the length of the string of exit names and strings of user data is limited to 500 characters. In WebSphere MQ for iSeries you can specify up to 10 exit names and the length of user data for each is limited to 32 characters. In WebSphere MQ for z/OS you can specify up to eight strings of user data each of length 32 characters.
On other platforms the maximum length of the string is 32 characters.
Security exit name (SCYEXIT)
Specifies the name of the exit program to be run by the channel security exit. Leave blank if no channel security exit is in effect.
The format and maximum length of the name depend on the platform, as for Receive exit name (RCVEXIT).
Security exit user data (SCYDATA)
Specifies user data that is passed to the security exit. The maximum length is 32 characters.
Send exit name (SENDEXIT)
Specifies the name of the exit program to be run by the channel send exit. In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, this can be a list of names of programs that are to be run in sequence. Leave blank if no channel send exit is in effect.
The format and maximum length of this attribute depend on the platform, as for Receive exit name (RCVEXIT).
Send exit user data (SENDDATA)
Specifies user data that is passed to the send exit.
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, you can run a sequence of send exits. The limitations on the user data length and an example of how to specify SENDDATA for more than one exit, are as shown for RCVDATA. See Receive exit user data (RCVDATA).
On other platforms the maximum length of the string is 32 characters.
Sequence number wrap (SEQWRAP)
This is the highest number the message sequence number reaches before it restarts at 1. In z/OS using CICS, this number is of interest only when sequential delivery of messages is selected. It is not valid for channel types of client-connection or server-connection.
The value of the number should be high enough to avoid a number being reissued while it is still being used by an earlier message. The two ends of a channel must have the same sequence number wrap value when a channel starts up; otherwise, an error occurs.
The value may be set from 100 through 999 999 999 (1 through 9 999 999 for z/OS using CICS).
Sequential delivery
This applies only to z/OS using CICS. Set this to 'YES' when using sequential numbering of messages. If one side of the channel requests this facility, it must be accepted by the other side.
There could be a performance penalty associated with the use of this option.
For other platforms, the MCA always uses message sequence numbering.
Short retry count (SHORTRTY)
Specify the maximum number of times that the channel is to try allocating a session to its partner. If the initial allocation attempt fails, the short retry count is decremented and the channel retries the remaining number of times with an interval, defined in the short retry interval attribute, between each attempt. If it still fails, it retries long retry count number of times with an interval of long retry interval between each attempt. If it is still unsuccessful, the channel terminates.
(Retry is not attempted if the cause of failure is such that a retry is not likely to be successful.)
If the channel initiator or queue manager stops while the channel is retrying, the short retry count and long retry count are reset when the channel initiator or queue manager is restarted.
The short retry count attribute is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999 999 (1 through 999 for z/OS using CICS, and the long and short retries have the same count).
Note:
On OS/2 Warp, iSeries, UNIX systems, and Windows systems, in order for retry to be attempted a channel initiator must be running. The channel initiator must be monitoring the initiation queue specified in the transmission queue that the channel in using.
Short retry interval (SHORTTMR)
Specify the approximate interval in seconds that the channel is to wait before retrying to establish connection, during the short retry mode.
The interval between retries may be extended if the channel has to wait to become active.
This attribute is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999. (0 through 999 for z/OS using CICS).
SSL Cipher Specification (SSLCIPH)
SSLCIPH defines a single CipherSpec for an SSL connection. Both ends of a WebSphere MQ SSL channel definition must include the parameter and the SSLCIPH values must specify the same CipherSpec on both ends of the channel. The value is a string with a maximum length of 32 characters.
SSLCIPH is valid for all channel types. It is supported on AIX, HP-UX, Linux, iSeries, Solaris, Windows, and z/OS. It is valid only for channels with a transport type (TRPTYPE) of TCP. If the TRPTYPE is not TCP, the data is ignored and no error message is issued.
SSLCIPH is an optional parameter.
For more information on SSLCIPH, see WebSphere MQ Script (MQSC) Command Reference and WebSphere MQ Security.
SSL Client Authentication (SSLCAUTH)
SSLCAUTH is used to define whether the channel needs to receive and authenticate an SSL certificate from an SSL client.
This parameter is valid on all channel types that can ever receive a channel initiation flow, except for sender channels. It is valid for receiver, server-connection, cluster-receiver, server, and requester channels.
The value of SSLCAUTH can be set to OPTIONAL or REQUIRED. The default value is REQUIRED. If SSLCAUTH is set to OPTIONAL, and the peer SSL client sends a certificate, the certificate is processed as normal.
You can specify a value for SSLCAUTH on a non-SSL channel definition, one on which SSLCIPH is missing or blank. You can use this to temporarily disable SSL for debugging without first having to clear and then reinput the SSL parameters.
This parameter is valid on AIX, HP-UX, Linux, iSeries, Solaris, Windows, and z/OS
SSLCAUTH is an optional parameter.
For more information on SSLCAUTH, see WebSphere MQ Script (MQSC) Command Reference and WebSphere MQ Security.
SSL Peer (SSLPEER)
The SSLPEER parameter is used to check the Distinguished Name (DN) of the certificate from the peer queue manager or client at the other end of a WebSphere MQ channel. If the DN received from the peer does not match the SSLPEER value, the channel does not start.
SSLPEER is an optional parameter. If a value is not specified, the peer DN is not checked when the channel is started.
This parameter is valid for all channel types.
This parameter is supported only on AIX, HP-UX, Linux, OS/2 Warp, iSeries, Solaris, Windows, and z/OS.
On z/OS the maximum length of the parameter is 256 bytes. On all other platforms it is 1024 bytes.
On z/OS the parameter values used are not checked. If you input incorrect values, the channel fails at startup, and error messages are written to the error log at both ends of the channel. A Channel SSL Error event is also generated at both ends of the channel. On platforms that support SSLPEER, other than z/OS, the validity of the string is checked when it is first input.
You can specify a value for SSLPEER on a non-SSL channel definition, one on which SSLCIPH is missing or blank. You can use this to temporarily disable SSL for debugging without having to clear and later reinput the SSL parameters.
For more information on using SSLPEER, see WebSphere MQ Script (MQSC) Command Reference and WebSphere MQ Security.
Target system identifier
This is for z/OS using CICS only. It identifies the particular CICS system where the sending or requesting channel transaction is to run.
The default is blank, which means the CICS system where you are logged on. The name may be one through four alphanumeric characters.
Transaction identifier
This only applies to z/OS using CICS.
The name of the local CICS transaction that you want to start. If you do not specify a value, the name of the supplied transaction for the channel type is used.
Transmission queue name (XMITQ)
The name of the transmission queue from which messages are retrieved. This is required for channels of type sender or server, it is not valid for other channel types.
Provide the name of the transmission queue to be associated with this sender or server channel, that corresponds to the queue manager at the far side of the channel. The transmission queue may be given the same name as the queue manager at the remote end.
Transport type (TRPTYPE)
This does not apply to z/OS using CICS.
WebSphere MQ for some platforms may not implement all the attributes shown in the list. Exceptions and platform differences are mentioned in the individual attribute descriptions, where relevant.
The keyword that you can specify in MQSC is shown in brackets for each attribute. (Attributes that apply only to WebSphere MQ for z/OS with CICS do not have MQSC keywords.)
The attributes are arranged in alphabetical order, as follows:
* Auto start (AUTOSTART)
* Alter date (ALTDATE)
* Alter time (ALTTIME)
* Batch Heartbeat Interval (BATCHHB)
* Batch interval (BATCHINT)
* Batch size (BATCHSZ)
* Channel name (CHANNEL)
* Channel type (CHLTYPE)
* CICS profile name
* Cluster (CLUSTER)
* Cluster namelist (CLUSNL)
* Connection name (CONNAME)
* Convert message (CONVERT)
* Description (DESCR)
* Disconnect interval (DISCINT)
* Heartbeat interval (HBINT)
* Local Address (LOCLADDR)
* Long retry count (LONGRTY)
* Long retry interval (LONGTMR)
* LU 6.2 mode name (MODENAME)
* LU 6.2 transaction program name (TPNAME)
* Maximum message length (MAXMSGL)
* Maximum transmission size
* Message channel agent name (MCANAME)
* Message channel agent type (MCATYPE)
* Message channel agent user identifier (MCAUSER)
* Message exit name (MSGEXIT)
* Message exit user data (MSGDATA)
* Message-retry exit name (MREXIT)
* Message-retry exit user data (MRDATA)
* Message retry count (MRRTY)
* Message retry interval (MRTMR)
* Nonpersistent message speed (NPMSPEED)
* Password (PASSWORD)
* PUT authority (PUTAUT)
* Queue manager name (QMNAME)
* Receive exit name (RCVEXIT)
* Receive exit user data (RCVDATA)
* Security exit name (SCYEXIT)
* Security exit user data (SCYDATA)
* Send exit name (SENDEXIT)
* Send exit user data (SENDDATA)
* Sequence number wrap (SEQWRAP)
* Sequential delivery
* Short retry count (SHORTRTY)
* Short retry interval (SHORTTMR)
* SSL Cipher Specification (SSLCIPH)
* SSL Client Authentication (SSLCAUTH)
* SSL Peer (SSLPEER)
* Target system identifier
* Transmission queue name (XMITQ)
* Transport type (TRPTYPE)
* User ID (USERID)
Alter date (ALTDATE)
This is the date on which the definition was last altered, in the form yyyy-mm-dd.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS, iSeries, Solaris, and Windows systems only.
Alter time (ALTTIME)
This is the time at which the definition was last altered, in the form hh:mm:ss.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS, iSeries, Solaris, and Windows systems only.
Auto start (AUTOSTART)
In MQSeries for Compaq NonStop Kernel there is no SNA listener process. Each channel initiated from a remote system must have its own, unique TP name on which it can listen. Such channels must be defined to MQSC with the attribute AUTOSTART(ENABLED) to ensure that there is an LU 6.2 responder process listening on this TP name whenever the queue manager is started.
SNA channels defined AUTOSTART(DISABLED) do not listen for incoming SNA requests. LU 6.2 responder processes are not started for such channels.
Batch Heartbeat Interval (BATCHHB)
The batch heartbeat interval allows 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, otherwise a 'heartbeat' is sent to the receiving channel to check.
The value must be in the range zero through 999 999. A value of zero indicates that batch heartbeating is not used.
This parameter is valid for the following channel types:
* Sender
* Server
* Cluster sender
* Cluster receiver
Batch interval (BATCHINT)
WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for OS/2 Warp, and WebSphere MQ for z/OS without CICS, you can specify a period of time, in milliseconds, during which the channel will keep a batch open even if there are no messages on the transmission queue. You can specify any number of milliseconds, from zero through 999 999 999. The default value is zero.
If you do not specify a batch interval, the batch closes when the number of messages specified in BATCHSZ has been sent or when the transmission queue becomes empty. On lightly loaded channels, where the transmission queue frequently becomes empty the effective batch size may be much smaller than BATCHSZ.
You can use the BATCHINT attribute to make your channels more efficient by reducing the number of short batches. Be aware, however, that you may slow down the response time, because batches will last longer and messages will remain uncommitted for longer.
If you specify a BATCHINT, batches close only when one of the following conditions is met:
* The number of messages specified in BATCHSZ have been sent.
* There are no more messages on the transmission queue and a time interval of BATCHINT has elapsed while waiting for messages (since the first message of the batch was retrieved).
Note:
BATCHINT specifies the total amount of time that is spent waiting for messages. It does not include the time spent retrieving messages that are already available on the transmission queue, or the time spent transferring messages.
This attribute applies only to sender, cluster-sender, server, and cluster-receiver channels.
Batch size (BATCHSZ)
The batch size is the maximum number of messages to be sent before a syncpoint is taken. The batch size does not affect the way the channel transfers messages; messages are always transferred individually, but are committed or backed out as a batch.
To improve performance, you can set a batch size to define the maximum number of messages to be transferred between two syncpoints. The batch size to be used is negotiated when a channel starts up, and the lower of the two channel definitions is taken. On some implementations, the batch size is calculated from the lowest of the two channel definitions and the two queue manager MAXUMSGS values. The actual size of a batch can be less than this; for example, a batch completes when there are no messages left on the transmission queue or the batch interval expires.
A large value for the batch size increases throughput, but recovery times are increased because there are more messages to back out and re-send. The default BATCHSZ is 50, and you are advised to try that value first. You might choose a lower value for BATCHSZ if your communications are unreliable, making the need to recover more likely.
Syncpoint procedure needs a unique logical unit of work identifier to be exchanged across the link every time a syncpoint is taken, to coordinate batch commit procedures.
If the synchronized batch commit procedure is interrupted, an in-doubt situation may arise. In-doubt situations are resolved automatically when a message channel starts up. If this resolution is not successful, manual intervention may be necessary, making use of the RESOLVE command.
Some considerations when choosing the number for batch size:
* If the number is too large, the amount of queue space taken up on both ends of the link becomes excessive. Messages take up queue space when they are not committed, and cannot be removed from queues until they are committed.
* If there is likely to be a steady flow of messages, you can improve the performance of a channel by increasing the batch size. However, this has the negative effect of increasing restart times, and very large batches may also affect performance.
* If message flow characteristics indicate that messages arrive intermittently, a batch size of 1 with a relatively large disconnect time interval may provide a better performance.
* The number may be in the range 1 through 9999. However, for data integrity reasons, channels connecting to any of the current platforms, as described in this book, should specify a batch size greater than 1. (A value of 1 is for use with Version 1 products, apart from MQSeries for MVS/ESA.)
For z/OS using CICS it must also be at least 3 less than the value set by the ALTER QMGR MAXUMSGS command.
* Even though nonpersistent messages on a fast channel do not wait for a syncpoint, they do contribute to the batch-size count.
Channel name (CHANNEL)
Specifies the name of the channel definition. The name can contain up to 20 characters, although as both ends of a message channel must have the same name, and other implementations may have restrictions on the size, the actual number of characters may have to be smaller.
Where possible, channel names should be unique to one channel between any two queue managers in a network of interconnected queue managers.
The name must contain characters from the following list:
Alphabetic (A-Z, a-z; note that uppercase and lowercase are significant)
Numerics (0-9)
Period (.)
Forward slash (/)
Underscore (_)
Percentage sign (%)
Notes:
1. Embedded blanks are not allowed, and leading blanks are ignored.
2. On systems using EBCDIC Katakana, you cannot use lowercase characters.
Channel type (CHLTYPE)
Specifies the type of the channel being defined. The possible channel types are:
Message channel types:
* Sender
* Server (not MQSeries for VSE/ESA)
* Cluster-sender (WebSphere MQ for z/OS without CICS, WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp only)
* Receiver
* Requester (not MQSeries for VSE/ESA)
* Cluster-receiver (WebSphere MQ for z/OS without CICS, WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, only)
MQI channel types:
* Client-connection (MQSeries for OS/2 Warp, VSE/ESA, DOS, Windows 3.1, Windows 95, and Windows 98 only, and WebSphere MQ for Windows systems, and UNIX systems only)
Note:
Client-connection channels can also be defined on z/OS for use on other platforms.
* Server-connection (not WebSphere MQ for z/OS using CICS)
The two ends of a channel must have the same name and have compatible types:
* Sender with receiver
* Requester with server
* Requester with sender (for Call_back)
* Server with receiver (server is used as a sender)
* Client-connection with server-connection
* Cluster-sender with cluster-receiver
CICS profile name
This is for z/OS using CICS only, to give extra definition for the session characteristics of the connection when CICS performs a communication session allocation, for example to select a particular COS.
The name must be known to CICS and be one to eight alphanumeric characters long.
Cluster (CLUSTER)
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 cluster-sender and cluster-receiver channels. Up to one of the resultant values of CLUSTER or CLUSNL can be nonblank. If one of the values is nonblank, the other must be blank.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS without CICS, iSeries, Solaris, and Windows systems only.
Cluster namelist (CLUSNL)
The name of the namelist that specifies a list of clusters to which the channel belongs.
This parameter is valid only for cluster-sender and cluster-receiver channels. Up to one of the resultant values of CLUSTER or CLUSNL can be nonblank. If one of the values is nonblank, the other must be blank.
This parameter is supported on AIX, HP-UX, Linux, OS/2 Warp, z/OS without CICS, iSeries, Solaris, and Windows systems only.
Connection name (CONNAME)
This is the communications connection identifier. It specifies the particular communications link to be used by this channel.
This attribute is required for sender channels, cluster-sender channels, cluster-receiver channels, requester channels, and client-connection channels. It does not apply to receiver or server-connection channel types.
It is optional for server channels, except on z/OS using CICS where it is required in the channel definition, but is ignored unless the server is initiating the conversation.
For z/OS using CICS this attribute names the CICS communication connection identifier for the session to be used for this channel. The name is one to four alphanumeric characters long.
Otherwise, the name is up to 48 characters for z/OS, 264 characters for other platforms, and:
If the transport type is TCP
This is either the hostname or the network address of the remote machine (or the local machine for cluster-receiver channels). For example, (MACH1.ABC.COM) or (19.22.11.162). It may include the port number, for example (MACHINE(123)). It can include the IP_name of a z/OS dynamic DNS group or a network dispatcher input port.
If the transport type is UDP
For WebSphere MQ for AIX only, UDP is an alternative to TCP. As with TCP/IP, it is either the hostname or the network address of the remote machine.
If the transport type is LU 6.2
For MQSeries for OS/2, and WebSphere MQ for iSeries, Windows systems, and UNIX systems, give the fully-qualified name of the partner LU if the TPNAME and MODENAME are specified. For other versions or if the TPNAME and MODENAME are blank, give the CPI-C side information object name as described in the section in this book about setting up communication for your platform.
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. This can be specified in one of 3 forms:
luname, for example IGY12355
luname/TPname, for example IGY12345/APING
luname/TPname/modename, for example IGY12345/APINGD/#INTER
For the first form, the TP name and mode name must be specified for the TPNAME and MODENAME attributes ; otherwise these attributes 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 attributes 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(R) generic resources group.
For Compaq OpenVMS Alpha, specify the Gateway Node name, the Access Name to the channel program, and the TPNAME used to invoke the remote program. For example: CONNAME('SNAGWY.VMSREQUESTER(HOSTVR)').
For Compaq NonStop Kernel, the value depends on whether SNAX or ICE is used; see Chapter 20, Setting up communication in Compaq NonStop Kernel.
If the transmission protocol is NetBIOS
This is the NetBIOS name defined on the remote machine.
If the transmission protocol is SPX
This is an SPX-style address consisting of a 4-byte network address, a 6-byte node address and a 2-byte socket number. Enter these in hexadecimal, with the network and node addresses separated by a fullstop and the socket number in brackets. For example:
CONNAME('0a0b0c0d.804abcde23a1(5e86)')
If the socket number is omitted, the default WebSphere MQ SPX socket number is used. The default is X'5E86'.
Note:
The definition of transmission protocol is contained in Transport type (TRPTYPE).
Convert message (CONVERT)
Application message data is usually converted by the receiving application. However, if the remote queue manager is on a platform that does not support data conversion, use this channel attribute to specify that the message should be converted into the format required by the receiving system before transmission.
This attribute applies only to sender, cluster-sender, server, and cluster-receiver channels and does not apply to WebSphere MQ for z/OS with CICS.
The possible values are 'yes' and 'no'. If you specify 'yes', the application data in the message is converted before sending if you have specified one of the built-in format names, or a data conversion exit is available for a user-defined format (See the WebSphere MQ Application Programming Guide). If you specify 'no', the application data in the message is not converted before sending.
Description (DESCR)
This contains up to 64 bytes of text that describes the channel definition.
Note:
The maximum number of characters is reduced if the system is using a double byte character set (DBCS).
Use characters from the character set identified by the coded character set identifier (CCSID) for the queue manager to ensure that the text is translated correctly if it is sent to another queue manager.
Disconnect interval (DISCINT)
This is a time-out attribute, specified in seconds, for the server, cluster-sender, sender, and cluster-receiver channels. The interval is measured from the point at which a batch ends, that is when the batch size is reached or when the batch interval expires and the transmission queue becomes empty. If no messages arrive on the transmission queue during the specified time interval, the channel closes down. (The time is approximate.)
The close-down exchange of control data between the two ends of the channel includes an indication of the reason for closing. This ensures that the corresponding end of the channel remains available to start up again.
On all platforms except z/OS with CICS, you can specify any number of seconds from zero through 999 999 where a value of zero means no disconnect; wait indefinitely.
In z/OS using CICS, you can specify any number of seconds from zero through 9999 where a value of zero means disconnect as soon as the transmission queue is empty.
Note:
Performance is affected by the value specified for the disconnect interval.
A very low value (a few seconds) may cause excessive overhead in constantly starting up the channel. A very large value (more than an hour) could mean that system resources are unnecessarily held up. For WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and for WebSphere MQ for z/OS without CICS, you can also specify a heartbeat interval, so that when there are no messages on the transmission queue, the sending MCA will send a heartbeat flow to the receiving MCA, thus giving the receiving MCA an opportunity to quiesce the channel without waiting for the disconnect interval to expire. For these two values to work together effectively, the heartbeat interval value must be significantly lower than the disconnect interval value.
A value for the disconnect interval of a few minutes is a reasonable value to use. Change this value only if you understand the implications for performance, and you need a different value for the requirements of the traffic flowing down your channels.
For more information, see Stopping and quiescing channels.
Heartbeat interval (HBINT)
This attribute applies to WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, and for WebSphere MQ for z/OS without CICS. You can specify 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 999 999. A value of zero means that no heartbeat flows are to be sent. The default value is 300. To be most useful, the value should be significantly less than the disconnect interval value.
This attribute is valid for sender, cluster-sender, server, receiver, cluster-receiver, and requester channels. Other than on z/OS and iSeries, it also applies to server-connection and client-connection channels. On these channels, heartbeats flow when a server MCA has issued an MQGET command with the WAIT option on behalf of a client application.
KeepAlive Interval (KAINT)
The KeepAlive Interval parameter is used to specify a time-out value for a channel.
The KeepAlive Interval parameter is a value passed to the communications stack specifying the KeepAlive timing for the channel. It allows you to specify a different keepalive value for each channel.
The value indicates a time, in seconds, and must be in the range 0 to 99999. A KeepAlive value of 0 indicates that channel KeepAlive is not enabled for the channel. When the KeepAlive Interval is set to 0, keepalive still occurs if a value has been specified for TCP/IP keepalive. On z/OS, this occurs when the TCPKEEP=YES parameter is specified in CSQ6CHIP. On other platforms, it occurs when the KEEPALIVE=YES parameter is specified in the TCP stanza in the distributed queuing configuration file.
This parameter is valid for all channel types. The value is ignored for all channels that have a TransportType (TRPTYPE) other than TCP or SPX
KAINT is only available on WebSphere MQ for z/OS.
Local Address (LOCLADDR)
This parameter specifies the local communications address for the channel. When a LOCLADDR value is specified, a channel that is stopped and then restarted continues to use the TCP/IP address specified in LOCLADDR. In recovery scenarios, this could be useful when the channel is communicating through a firewall, because it removes problems caused by the channel restarting with a different IP address, specified by the TCP/IP stack to which it is connected.
This parameter is valid for the following channel types:
* Sender
* Server
* Requester
* Client-connection
* Cluster-receiver
* Cluster-sender
The value used is the optional IP address and optional port or port range to be used for outbound TCP/IP communications. The format is as follows:
LOCLADDR([ip-addr][(low-port[,high-port])])
where "ip-addr" is specified in dotted alphanumeric or decimal form, for example, (MACH1.ABC.COM) or (19.22.11.162), and "low-port" and "high-port" are port numbers enclosed in parentheses. When two port values are specified, the channel binds to the address specified, using an available port within the range covered by the two port values. All values are optional.
The maximum length of the string is MQ_LOCAL_ADDRESS_LENGTH.
Note:
If the LOCLADDR port is in use, TCP/IP requires a time period to release the previously used port. If enough time is not left, and if only 1 LOCLADDR port is specified, the previously used port will not be available and so a random port will be chosen rather than the LOCLADDR port.
Long retry count (LONGRTY)
Specify the maximum number of times that the channel is to try allocating a session to its partner. If the initial allocation attempt fails, the short retry count number is decremented and the channel retries the remaining number of times. If it still fails, it retries a long retry count number of times with an interval of long retry interval between each try. If it is still unsuccessful, the channel closes down. The channel must subsequently be restarted with a command (it is not started automatically by the channel initiator).
(Retry is not attempted if the cause of failure is such that a retry is not likely to be successful.)
If the channel initiator or queue manager stops while the channel is retrying, the short retry count and long retry count are reset when the channel initiator or queue manager is restarted.
The long retry count attribute is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999 999. On z/OS using CICS, it may be set from zero through 999, and the long and short retries have the same count.
Note:
For OS/2, iSeries, UNIX systems, and Windows systems, in order for retry to be attempted a channel initiator must be running. The channel initiator must be monitoring the initiation queue specified in the transmission queue that the channel is using.
Long retry interval (LONGTMR)
The approximate interval in seconds that the channel is to wait before retrying to establish connection, during the long retry mode.
The interval between retries may be extended if the channel has to wait to become active.
The channel tries to connect long retry count number of times at this long interval, after trying the short retry count number of times at the short retry interval.
This is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999. On z/OS using CICS, it may be set from zero through 999.
LU 6.2 mode name (MODENAME)
This is for use with LU 6.2 connections. It gives extra definition for the session characteristics of the connection when a communication session allocation is performed.
When using side information for SNA communications, the mode name is defined in the CPI-C Communications Side Object or APPC side information and this attribute should be left blank; otherwise, it should be set to the SNA mode name.
The name must be one to eight alphanumeric characters long.
It is not valid for receiver or server-connection channels.
LU 6.2 transaction program name (TPNAME)
This is for use with LU 6.2 connections. It is the name, or generic name, of the transaction program (MCA) to be run at the far end of the link.
When using side information for SNA communications, the transaction program name is defined in the CPI-C Communications Side Object or APPC side information and this attribute should be left blank. Otherwise, this name is required by sender channels and requester channels except on z/OS using CICS where it is required in the channel definition but is ignored unless the server is initiating the conversation.
On platforms other than Compaq NonStop Kernel, the name can be up to 64 characters long. See Chapter 20, Setting up communication in Compaq NonStop Kernel for more information about that platform.
If the remote system is WebSphere MQ for z/OS using CICS, the transaction is:
* CKRC when you are defining a sender channel, or a server channel that acts as a sender
* CKSV when you are defining a requester channel of a requester-server pair
* CKRC when you are defining a requester channel of a requester-sender pair
On other platforms, this should be set to the SNA transaction program name, unless the CONNAME contains a side-object name in which case it should be set to blanks. The actual name is taken instead from the CPI-C Communications Side Object, or the APPC side information data set.
This information is set in a different way on other platforms; see the section in this book about setting up communication for your platform.
Maximum message length (MAXMSGL)
Specifies the maximum length of a message that can be transmitted on the channel.
On WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for OS/2 Warp, and VSE/ESA, specify a value greater than or equal to zero, and less than or equal to the maximum message length for the queue manager. See the MAXMSGL parameter of the ALTER QMGR command in the WebSphere MQ Script (MQSC) Command Reference book for more information. On other platforms, specify a value greater than or equal to zero, and less than or equal to 4 194 304 bytes. On WebSphere MQ for z/OS, specify a value greater than or equal to zero, and less than or equal to 104 857 600 bytes.
Because various implementations of WebSphere MQ systems exist on different platforms, the size available for message processing may be limited in some applications. This number must reflect a size that your system can handle without stress. When a channel starts up, the lower of the two numbers at each end of the channel is taken.
Notes:
1. If splitting of messages is not supported at either end of a channel, the maximum message size cannot be greater than the negotiated maximum transmission size.
2. The IBM WebSphere MQ products that this edition of the book applies to all support message splitting. Other WebSphere MQ products do not support message splitting.
3. For a comparison of the functions available, including the different maximum message lengths available see the WebSphere MQ Application Programming Guide.
4. You may use a maximum message size of 0 which will be taken to mean that the size is to be set to the local queue manager maximum value.
Maximum transmission size
If you are using CICS for distributed queuing on z/OS, you can specify the maximum transmission size, in bytes, that your channel is allowed to use when transmitting a message, or part of a message. When a channel starts up, this value is negotiated between the sending and receiving channels and the lower of the two values is agreed. The maximum size is 32 000 bytes on TCP/IP, but the maximum usable size is 32 000 bytes less the message descriptor. On VSE/ESA, the maximum size is 64 000 bytes on SNA.
Use this facility to ensure that system resources are not exceeded by your channels. Set this value in conjunction with the maximum message size, remembering to allow for message descriptors. An error situation may be created if the message size is allowed to exceed the transmission size, and message splitting is not supported.
Notes:
1. If channel startup negotiation results in a size less than the minimum required for the local channel program, no messages can be transferred.
Message channel agent name (MCANAME)
This attribute is reserved and should not be used.
Message channel agent type (MCATYPE)
For WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for OS/2 Warp, this attribute may be specified as a 'process' or a 'thread'. This parameter is valid for channel types of sender, cluster-sender (on WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp), server, requester, or cluster-receiver. On WebSphere MQ for z/OS, it is supported only for channels with a channel type of cluster-receiver. The MCA type is used when the channel is started locally to determine how the channel is run.
Advantages of running as a process include:
* Isolation for each channel providing greater integrity
* Job authority specific for each channel
* Control over job scheduling
Advantages of threads include:
* Much reduced use of storage
* Easier configuration by typing on the command line
* Faster execution - it is quicker to start a thread than to instruct the operating system to start a process
For channel types of sender, server, and requester, the default is 'process'. For channel types of cluster-sender and cluster-receiver, the default is 'thread'. These defaults can change during your installation.
If you specify 'process' on the channel definition, a RUNMQCHL process is started. If you specify 'thread', the MCA runs on a thread of the RUNMQCHI process. On the machine that receives the inbound allocates, the MCA runs as a thread or process depending on whether you use inetd or RUNMQLSR.
Message channel agent user identifier (MCAUSER)
This is not valid for z/OS using CICS; it is not valid for channels of client-connection type.
This attribute is the user identifier (a string) to be used by the MCA for authorization to access WebSphere MQ resources, including (if PUT authority is DEF) authorization to put the message to the destination queue for receiver or requester channels.
On WebSphere MQ for Windows, the user identifier may be domain-qualified by using the format, user@domain, where the domain must be either the Windows systems domain of the local system or a trusted domain.
If this attribute is blank, the MCA uses its default user identifier.
Message exit name (MSGEXIT)
Specifies the name of the user exit program to be run by the channel message exit. On AIX, Compaq Tru64 UNIX, HP-UX, iSeries, Linux, OS/2 Warp, Solaris, Windows systems, and z/OS this can be a list of names of programs that are to be run in succession. Leave blank, if no channel message exit is in effect.
The format and maximum length of this attribute depend on the platform, as for Receive exit name (RCVEXIT).
The message exit is not supported on client-connection or server-connection channels.
Message exit user data (MSGDATA)
Specifies user data that is passed to the channel message exits.
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, Windows systems, and z/OS, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, you can run a sequence of message exits. The limitations on the user data length and an example of how to specify MSGDATA for more than one exit are as shown for RCVDATA. See Receive exit user data (RCVDATA).
On other platforms the maximum length of the string is 32 characters.
Message-retry exit name (MREXIT)
Specifies the name of the user exit program to be run by the message-retry user exit. Leave blank if no message-retry exit program is in effect.
The format and maximum length of the name depend on the platform, as for Receive exit name (RCVEXIT).
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Message-retry exit user data (MRDATA)
This is passed to the channel message-retry exit when it is called.
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Message retry count (MRRTY)
This is the number of times the channel will retry before it decides it cannot deliver the message.
This attribute 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 for the exit's use, but the number of retries performed (if any) is controlled by the exit, and not by this attribute.
The value must be in the range 0 to 999 999 999. A value of zero means that no retries will be performed.
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Message retry interval (MRTMR)
This is the minimum interval of time that must pass before the channel can retry the MQPUT operation. This time interval is in milliseconds.
This attribute 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 for the exit's use, but the retry interval is controlled by the exit, and not by this attribute.
The value must be in the range 0 to 999 999 999. A value of zero means that the retry will be performed as soon as possible (provided that the value of MRRTY is greater than zero).
This parameter is only valid for receiver, cluster-receiver, and requester channels. It is not supported on WebSphere MQ for z/OS.
Network-connection priority (NETPRTY)
The priority for the network connection. Distributed queuing will choose the path with the highest priority if there are multiple paths available. The value must be in the range 0 through 9; 0 is the lowest priority.
This parameter is valid only for cluster-receiver channels.
This parameter is valid only on AIX, HP-UX, Linux, OS/2 Warp, z/OS without CICS, iSeries, Solaris, and Windows systems.
Nonpersistent message speed (NPMSPEED)
For WebSphere MQ for AIX, HP-UX, iSeries, Solaris and Windows systems, WebSphere MQ for z/OS without CICS, and MQSeries V5.1 for Compaq Tru64 UNIX and OS/2 Warp, you can specify the speed at which nonpersistent messages are to be sent. You can specify either 'normal' or 'fast'. The default is 'fast', which means that nonpersistent messages on a channel are not transferred within transactions. The advantage of this is that nonpersistent messages become available for retrieval far more quickly. The disadvantage is that because they are not part of a transaction, messages may be lost if there is a transmission failure or if the channel stops when the messages are in transit. See Fast, nonpersistent messages.
This attribute is valid for sender, cluster-sender, server, receiver, cluster-receiver, and requester channels.
Password (PASSWORD)
You can specify a password of maximum length 12 characters, although only the first 10 characters are used.
The password may be used by the MCA when attempting to initiate a secure LU 6.2 session with a remote MCA. It is valid for channel types of sender, server, requester, or client-connection.
This does not apply to WebSphere MQ for z/OS except for client-connection channels.
PUT authority (PUTAUT)
Use this attribute to choose the type of security processing to be carried out by the MCA when executing:
* An MQPUT command to the destination queue (for message channels) , or
* An MQI call (for MQI channels).
You can choose one of the following:
Process security, also called default authority (DEF)
The default user ID is used.
On platforms, with Process security, you choose to have the queue security based on the user ID that the process is running under. The user ID is that of the process, or user, running the MCA at the receiving end of the message channel.
The queues are opened with this user ID and the open option MQOO_SET_ALL_CONTEXT.
Context security (CTX)
The alternate user ID is used from the context information associated with the message.
The UserIdentifier in the message descriptor is moved into the AlternateUserId field in the object descriptor. The queue is opened with the open options MQOO_SET_ALL_CONTEXT and MQOO_ALTERNATE_USER_AUTHORITY.
Only Message Channel Agent security (ONLYMCA)
The default user ID is used.
On platforms, with ONLYMCA security, you choose to have the queue security based on the user ID that the process is running under. The user ID is that of the process, or user, running the MCA at the receiving end of the message channel.
The queues are opened with this user ID and the open option MQOO_SET_ALL_CONTEXT.
Alternate Message Channel Agent security (ALTMCA)
This is the same as for ONLYMCA security but allows you to use context.
This parameter is only valid for receiver, requester, cluster-receiver, and server-connection channels. Context security and alternate message channel agent security values are not supported on server-connection channels.
Further details about:
* Context fields and open options can be found in the WebSphere MQ Application Programming Guide.
* Security can be found in the WebSphere MQ System Administration Guide for WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, or in the MQSeries System Administration book for your platform.
Note:
On WebSphere MQ for z/OS it is possible for two userids to be checked. Specific details of userids used by the channel initiator on z/OS can be found in the WebSphere MQ for z/OS System Setup Guide .
.
Queue manager name (QMNAME)
This applies to a channel of client-connection type only. It is the name of the queue manager or queue manager group to which a WebSphere MQ client application can request connection.
Receive exit name (RCVEXIT)
Specifies the name of the user exit program to be run by the channel receive user exit. In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, Windows systems, and z/OS, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp this can be a list of names of programs that are to be run in succession. Leave blank, if no channel receive user exit is in effect.
The format and maximum length of this attribute depend on the platform:
* On z/OS it is a load module name, maximum length 8 characters, except for client-connection channels where the maximum length is 128 characters.
* On iSeries it is of the form:
libname/progname
when specified in CL commands.
When specified in WebSphere MQ Commands (MQSC) it has the form:
progname libname
where progname 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 OS/2 and Windows it is of the form:
dllname(functionname)
where dllname is specified without the suffix ".DLL". The maximum length of the string is 40 characters.
* On UNIX systems, Compaq OpenVMS Alpha, and Compaq NonStop Kernel it is of the form:
libraryname(functionname)
The maximum length of the string is 40 characters.
On AIX, Compaq Tru64 UNIX, HP-UX, Linux, iSeries, OS/2 Warp, Solaris, Windows systems, and z/OS, you can specify a list of receive, send, or message exit program names. The names should be separated by a comma, a space, or both. For example:
RCVEXIT(exit1 exit2)
MSGEXIT(exit1,exit2)
SENDEXIT(exit1, exit2)
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, Windows systems, and z/OS, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, the total length of the string of exit names and strings of user data for a particular type of exit is limited to 500 characters. In WebSphere MQ for iSeries you can list up to 10 exit names. In WebSphere MQ for z/OS you can list up to eight exit names.
Receive exit user data (RCVDATA)
Specifies user data that is passed to the receive exit.
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp you can run a sequence of receive exits. The string of user data for a series of exits should be separated by a comma, spaces, or both. For example:
RCVDATA(exit1_data exit2_data)
MSGDATA(exit1_data,exit2_data)
SENDDATA(exit1_data, exit2_data)
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, the length of the string of exit names and strings of user data is limited to 500 characters. In WebSphere MQ for iSeries you can specify up to 10 exit names and the length of user data for each is limited to 32 characters. In WebSphere MQ for z/OS you can specify up to eight strings of user data each of length 32 characters.
On other platforms the maximum length of the string is 32 characters.
Security exit name (SCYEXIT)
Specifies the name of the exit program to be run by the channel security exit. Leave blank if no channel security exit is in effect.
The format and maximum length of the name depend on the platform, as for Receive exit name (RCVEXIT).
Security exit user data (SCYDATA)
Specifies user data that is passed to the security exit. The maximum length is 32 characters.
Send exit name (SENDEXIT)
Specifies the name of the exit program to be run by the channel send exit. In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, this can be a list of names of programs that are to be run in sequence. Leave blank if no channel send exit is in effect.
The format and maximum length of this attribute depend on the platform, as for Receive exit name (RCVEXIT).
Send exit user data (SENDDATA)
Specifies user data that is passed to the send exit.
In WebSphere MQ for AIX, iSeries, HP-UX, Linux, Solaris, z/OS, and Windows systems, and MQSeries V5.1 for Compaq Tru64 UNIX, and OS/2 Warp, you can run a sequence of send exits. The limitations on the user data length and an example of how to specify SENDDATA for more than one exit, are as shown for RCVDATA. See Receive exit user data (RCVDATA).
On other platforms the maximum length of the string is 32 characters.
Sequence number wrap (SEQWRAP)
This is the highest number the message sequence number reaches before it restarts at 1. In z/OS using CICS, this number is of interest only when sequential delivery of messages is selected. It is not valid for channel types of client-connection or server-connection.
The value of the number should be high enough to avoid a number being reissued while it is still being used by an earlier message. The two ends of a channel must have the same sequence number wrap value when a channel starts up; otherwise, an error occurs.
The value may be set from 100 through 999 999 999 (1 through 9 999 999 for z/OS using CICS).
Sequential delivery
This applies only to z/OS using CICS. Set this to 'YES' when using sequential numbering of messages. If one side of the channel requests this facility, it must be accepted by the other side.
There could be a performance penalty associated with the use of this option.
For other platforms, the MCA always uses message sequence numbering.
Short retry count (SHORTRTY)
Specify the maximum number of times that the channel is to try allocating a session to its partner. If the initial allocation attempt fails, the short retry count is decremented and the channel retries the remaining number of times with an interval, defined in the short retry interval attribute, between each attempt. If it still fails, it retries long retry count number of times with an interval of long retry interval between each attempt. If it is still unsuccessful, the channel terminates.
(Retry is not attempted if the cause of failure is such that a retry is not likely to be successful.)
If the channel initiator or queue manager stops while the channel is retrying, the short retry count and long retry count are reset when the channel initiator or queue manager is restarted.
The short retry count attribute is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999 999 (1 through 999 for z/OS using CICS, and the long and short retries have the same count).
Note:
On OS/2 Warp, iSeries, UNIX systems, and Windows systems, in order for retry to be attempted a channel initiator must be running. The channel initiator must be monitoring the initiation queue specified in the transmission queue that the channel in using.
Short retry interval (SHORTTMR)
Specify the approximate interval in seconds that the channel is to wait before retrying to establish connection, during the short retry mode.
The interval between retries may be extended if the channel has to wait to become active.
This attribute is valid only for channel types of sender, cluster-sender, server, and cluster-receiver. It is also valid for requester channels on z/OS if you are using CICS. It may be set from zero through 999 999. (0 through 999 for z/OS using CICS).
SSL Cipher Specification (SSLCIPH)
SSLCIPH defines a single CipherSpec for an SSL connection. Both ends of a WebSphere MQ SSL channel definition must include the parameter and the SSLCIPH values must specify the same CipherSpec on both ends of the channel. The value is a string with a maximum length of 32 characters.
SSLCIPH is valid for all channel types. It is supported on AIX, HP-UX, Linux, iSeries, Solaris, Windows, and z/OS. It is valid only for channels with a transport type (TRPTYPE) of TCP. If the TRPTYPE is not TCP, the data is ignored and no error message is issued.
SSLCIPH is an optional parameter.
For more information on SSLCIPH, see WebSphere MQ Script (MQSC) Command Reference and WebSphere MQ Security.
SSL Client Authentication (SSLCAUTH)
SSLCAUTH is used to define whether the channel needs to receive and authenticate an SSL certificate from an SSL client.
This parameter is valid on all channel types that can ever receive a channel initiation flow, except for sender channels. It is valid for receiver, server-connection, cluster-receiver, server, and requester channels.
The value of SSLCAUTH can be set to OPTIONAL or REQUIRED. The default value is REQUIRED. If SSLCAUTH is set to OPTIONAL, and the peer SSL client sends a certificate, the certificate is processed as normal.
You can specify a value for SSLCAUTH on a non-SSL channel definition, one on which SSLCIPH is missing or blank. You can use this to temporarily disable SSL for debugging without first having to clear and then reinput the SSL parameters.
This parameter is valid on AIX, HP-UX, Linux, iSeries, Solaris, Windows, and z/OS
SSLCAUTH is an optional parameter.
For more information on SSLCAUTH, see WebSphere MQ Script (MQSC) Command Reference and WebSphere MQ Security.
SSL Peer (SSLPEER)
The SSLPEER parameter is used to check the Distinguished Name (DN) of the certificate from the peer queue manager or client at the other end of a WebSphere MQ channel. If the DN received from the peer does not match the SSLPEER value, the channel does not start.
SSLPEER is an optional parameter. If a value is not specified, the peer DN is not checked when the channel is started.
This parameter is valid for all channel types.
This parameter is supported only on AIX, HP-UX, Linux, OS/2 Warp, iSeries, Solaris, Windows, and z/OS.
On z/OS the maximum length of the parameter is 256 bytes. On all other platforms it is 1024 bytes.
On z/OS the parameter values used are not checked. If you input incorrect values, the channel fails at startup, and error messages are written to the error log at both ends of the channel. A Channel SSL Error event is also generated at both ends of the channel. On platforms that support SSLPEER, other than z/OS, the validity of the string is checked when it is first input.
You can specify a value for SSLPEER on a non-SSL channel definition, one on which SSLCIPH is missing or blank. You can use this to temporarily disable SSL for debugging without having to clear and later reinput the SSL parameters.
For more information on using SSLPEER, see WebSphere MQ Script (MQSC) Command Reference and WebSphere MQ Security.
Target system identifier
This is for z/OS using CICS only. It identifies the particular CICS system where the sending or requesting channel transaction is to run.
The default is blank, which means the CICS system where you are logged on. The name may be one through four alphanumeric characters.
Transaction identifier
This only applies to z/OS using CICS.
The name of the local CICS transaction that you want to start. If you do not specify a value, the name of the supplied transaction for the channel type is used.
Transmission queue name (XMITQ)
The name of the transmission queue from which messages are retrieved. This is required for channels of type sender or server, it is not valid for other channel types.
Provide the name of the transmission queue to be associated with this sender or server channel, that corresponds to the queue manager at the far side of the channel. The transmission queue may be given the same name as the queue manager at the remote end.
Transport type (TRPTYPE)
This does not apply to z/OS using CICS.
Comments
Post a Comment