Options (MQLONG)
Options that control the action of MQCONNX.
Accounting options
AccountingConnOverride
queue manager attribute is set to MQMON_ENABLED: - MQCNO_ACCOUNTING_MQI_ENABLED
- When monitoring data collection is switched off in the queue manager
definition by setting the
MQIAccounting
attribute to MQMON_OFF, setting this flag enables MQI accounting data collection. - MQCNO_ACCOUNTING_MQI_DISABLED
- When monitoring data collection is switched off in the queue manager
definition by setting the
MQIAccounting
attribute to MQMON_OFF, setting this flag stops MQI accounting data collection. - MQCNO_ACCOUNTING_Q_ENABLED
- When queue-accounting data collection is switched off in the queue
manager definition by setting the
MQIAccounting
attribute to MQMON_OFF, setting this flag enables accounting data collection for those queues that specify a queue manager in theMQIAccounting
field of their queue definition. - MQCNO_ACCOUNTING_Q_DISABLED
- When queue-accounting data collection is switched off in the queue
manager definition by setting the
MQIAccounting
attribute to MQMON_OFF, setting this flag switches off accounting data collection for those queues that specify a queue manager in theMQIAccounting
field of their queue definition.If none of these flags are defined, the accounting for the connection is as defined in the Queue Manager attributes.
Binding options
The following options control the type of WebSphere® MQ binding to use. Specify only one of these options:
- MQCNO_STANDARD_BINDING
- The application and the local queue manager agent (the component
that manages queuing operations) run in separate units of execution
(typically, in separate processes). This arrangement maintains the
integrity of the queue manager; that is, it protects the queue manager
from errant programs.
If the queue manager supports multiple binding types, and you set MQCNO_STANDARD_BINDING, the queue manager uses the
DefaultBindType
attribute in theConnection
stanza in the qm.ini file (or the equivalent Windows registry entry) to select the actual type of binding. If this stanza is not defined, or the value cannot be used or is not appropriate for the application, the queue manager selects an appropriate binding type. The queue manager sets the actual binding type used in the connect options.Use MQCNO_STANDARD_BINDING in situations where the application might not have been fully tested, or might be unreliable or untrustworthy. MQCNO_STANDARD_BINDING is the default.
This option is supported in all environments.
If you are linking to the mqm library, then a standard server connection using the default bind type is attempted first. If the underlying server library failed to load, a client connection is attempted instead.- If the MQ_CONNECT_TYPE environment variable is specified, one
of the following options can be supplied to change the behaviour of
MQCONN or MQCONNX if MQCNO_STANDARD_BINDING is specified. (The exception
to this is if MQCNO_FASTPATH_BINDING is specified with MQ_CONNECT_TYPE
set to LOCAL or STANDARD to allow
fastpath connections to be downgraded by the administrator without
a related change to the application:
Value Meaning CLIENT A client connection only is attempted. FASTPATH This value was supported in previous releases, but is now ignored if specified. LOCAL A server connection only is attempted. Fastpath connections are downgraded to a standard server connection. STANDARD Supported for compatibility with previous releases. This value is now treated as LOCAL. - If the MQ_CONNECT_TYPE environment variable is not set when MQCONNX is called, a standard server connection using the default bind type is attempted. If the server library fails to load, a client connection is attempted.
- If the MQ_CONNECT_TYPE environment variable is specified, one
of the following options can be supplied to change the behaviour of
MQCONN or MQCONNX if MQCNO_STANDARD_BINDING is specified. (The exception
to this is if MQCNO_FASTPATH_BINDING is specified with MQ_CONNECT_TYPE
set to LOCAL or STANDARD to allow
fastpath connections to be downgraded by the administrator without
a related change to the application:
- MQCNO_FASTPATH_BINDING
- The application and the local queue manager agent are part of
the same unit of execution. This is in contrast to the typical method
of binding, where the application and the local queue manager agent
run in separate units of execution.
MQCNO_FASTPATH_BINDING is ignored if the queue manager does not support this type of binding; processing continues as though the option had not been specified.
MQCNO_FASTPATH_BINDING can be of advantage in situations where multiple processes consume more resources than the overall resource used by the application. An application that uses the fastpath binding is known as a trusted application.
Consider the following important points when deciding whether to use the fastpath binding:- Using the MQCNO_FASTPATH_BINDING option does not prevent an application altering or corrupting messages and other data areas belonging to the queue manager. Use this option only in situations where you have fully evaluated these issues.
- The application must not use asynchronous signals or timer interrupts
(such as
sigkill
) with MQCNO_FASTPATH_BINDING. There are also restrictions on the use of shared memory segments. - The application must use the MQDISC call to disconnect from the queue manager.
- The application must finish before you end the queue manager with
the
endmqm
command. - On IBM® i, the job must run
under a user profile that belongs to the
QMQMADM
group. Also, the program must not stop abnormally, otherwise unpredictable results can occur. - On UNIX systems, the
mqm
user identifier must be the effective user identifier, and themqm
group identifier must be the effective group identifier. To make the application run in this way, configure the program so that it is owned by themqm
user identifier andmqm
group identifier, and then set thesetuid
andsetgid
permission bits on the program.The WebSphere MQ Object Authority Manager (OAM) still uses the real user ID for authority checking.
- On Windows, the program
must be a member of the
mqm
group. Fastpath binding is not supported for 64 bit applications.
The MQCNO_FASTPATH_BINDING option is supported in the following environments: AIX®, HP-UX, IBM i, Solaris, Linux®, and Windows. On z/OS®, the option is accepted but ignored.
For more information about the implications of using trusted applications, see Restrictions for trusted applications .
- MQCNO_SHARED_BINDING
-
With MQCNO_SHARED_BINDING, the application and the local-queue-manager agent share some resources. MQCNO_SHARED_BINDING is ignored if the queue manager does not support this type of binding. Processing continues as though the option had not been specified.
- MQCNO_ISOLATED_BINDING
In this case, the application process and the local queue manager agent are isolated from each other in that they do not share resources. MQCNO_ISOLATED_BINDING is ignored if the queue manager does not support this type of binding. Processing continues as though the option had not been specified.
- MQCNO_CLIENT_BINDING
- Specify this option to make the application attempt a client connection only. This option has the following limitations:
- MQCNO_CLIENT_BINDING is rejected on z/OS with MQRC_OPTIONS_ERROR.
- MQCNO_CLIENT_BINDING is rejected with MQRC_OPTIONS_ERROR if it is specified with any MQCNO binding option other than MQCNO_STANDARD_BINDING.
- MQCNO_CLIENT_BINDING is not available for Java or .NET as they have their own mechanisms for choosing the bind type.
- If the MQ_CONNECT_TYPE environment variable is not set when MQCONNX is called, a standard server connection using the default bind type is attempted. If the server library fails to load, a client connection is attempted.
- MQCNO_LOCAL_BINDING
- Specify this option to make the application attempt a server connection. If either MQCNO_FASTPATH_BINDING, MQCNO_ISOLATED_BINDING, or MQCNO_SHARED_BINDING is also specified, then the connection is of that type instead, and is documented in this section. Otherwise a standard server connection is attempted using the default bind type. MQCNO_LOCAL_BINDING has the following limitations:
- MQCNO_LOCAL_BINDING is ignored on z/OS.
- MQCNO_LOCAL_BINDING is rejected with MQRC_OPTIONS_ERROR if it is specified with any MQCNO reconnect option other than MQCNO_RECONNECT_AS_DEF.
- MQCNO_LOCAL_BINDING is not available for Java or .NET as they have their own mechanisms for choosing the bind type.
- If the MQ_CONNECT_TYPE environment variable is not set when MQCONNX is called, a standard server connection using the default bind type is attempted. If the server library fails to load, a client connection is attempted.
On AIX, HP-UX, Solaris, Linux, and
Windows, you can use the environment variable
MQ_CONNECT_TYPE
with the bind type specified by the
Options
field, to control the
type of binding used. If you specify this environment variable, it
must have the value FASTPATH
or STANDARD
; if it has a different value, it is ignored. The value of the environment
variable is case sensitive; see MQCONNX environment variable
for more information.
Options
field interact
as follows: - If you omit the environment variable, or give it a value that
is not supported, use of the fastpath binding is determined solely
by the
Options
field. - If you give the environment variable a supported value, the fastpath
binding is used only if both the environment variable and
Options
field specify the fastpath binding.
Connection-tag options
ConnTag
. You can specify
only one of these options: - MQCNO_SERIALIZE_CONN_TAG_Q_MGR
This option requests exclusive use of the connection tag within the local queue manager. If the connection tag is already in use in the local queue manager, the MQCONNX call fails with reason code MQRC_CONN_TAG_IN_USE. The outcome of the call is not affected by using the connection tag elsewhere in the queue-sharing group to which the local queue manager belongs.
- MQCNO_SERIALIZE_CONN_TAG_QSG
-
This option requests exclusive use of the connection tag within the queue-sharing group to which the local queue manager belongs. If the connection tag is already in use in the queue-sharing group, the MQCONNX call fails with reason code MQRC_CONN_TAG_IN_USE.
- MQCNO_RESTRICT_CONN_TAG_Q_MGR
- This option requests shared use of the connection tag within the local queue manager. If the connection tag is already in use in the local queue manager, the MQCONNX call can succeed if the requesting application is running in the same processing scope as the existing user of the tag. If this condition is not satisfied, the MQCONNX call fails with reason code MQRC_CONN_TAG_IN_USE. The outcome of the call is not affected by use of the connection tag elsewhere in the queue-sharing group to which the local queue manager belongs.
- Applications must run within the same MVS™ address space to share the connection tag. If the application using the connection tag is a client application, MQCNO_RESTRICT_CONN_TAG_Q_MGR is not allowed.
- MQCNO_RESTRICT_CONN_TAG_QSG
-
This option requests shared use of the connection tag within the queue-sharing group to which the local queue manager belongs. If the connection tag is already in use in the queue-sharing group, the MQCONNX call can succeed provided the requesting application is running in the same processing scope and is connected to the same queue manager, as the existing user of the tag.
If these conditions are not satisfied, the MQCONNX call fails with reason code MQRC_CONN_TAG_IN_USE.
- Applications must run within the same MVS address space to share the connection tag. If the application using the connection tag is a client application, MQCNO_RESTRICT_CONN_TAG_QSG is not allowed.
If none of these options are specified,
ConnTag
is not used. These options
are not valid if Version
is less than MQCNO_VERSION_3.
Handle-sharing options
- MQCNO_HANDLE_SHARE_NONE
This option indicates that connection and object handles can be used only by the thread that caused the handle to be allocated (that is, the thread that issued the MQCONN, MQCONNX , or MQOPEN call). The handles cannot be used by other threads belonging to the same process.
- MQCNO_HANDLE_SHARE_BLOCK
This option indicates that connection and object handles allocated by one thread of a process can be used by other threads belonging to the same process. However, only one thread at a time can use any particular handle; that is, only serial use of a handle is permitted. If a thread tries to use a handle that is already in use by another thread, the call blocks (waits) until the handle becomes available.
- MQCNO_HANDLE_SHARE_NO_BLOCK
This is the same as MQCNO_HANDLE_SHARE_BLOCK, except that if the handle is in use by another thread, the call completes immediately with MQCC_FAILED and MQRC_CALL_IN_PROGRESS instead of blocking until the handle becomes available.
- Each MQCONN or MQCONNX call that specifies MQCNO_HANDLE_SHARE_NONE returns a new nonshared handle on the first call, and the same non-shared handle on the second and later calls (assuming no intervening MQDISC call). The reason code is MQRC_ALREADY_CONNECTED for the second and later calls.
- Each MQCONNX call that specifies MQCNO_HANDLE_SHARE_BLOCK or MQCNO_HANDLE_SHARE_NO_BLOCK returns a new shared handle on each call.
Object handles inherit the same sharing properties as the connection handle specified on the MQOPEN call that created the object handle. Also, units of work inherit the same sharing properties as the connection handle used to start the unit of work; if the unit of work is started in one thread using a shared handle, the unit of work can be updated in another thread using the same handle.
- In the Microsoft Transaction Server (MTS) environment, the default is the same as MQCNO_HANDLE_SHARE_BLOCK.
- In other environments, the default is the same as MQCNO_HANDLE_SHARE_NONE.
Reconnection options
- MQCNO_RECONNECT_AS_DEF
The reconnection option is resolved to its default value. If no default is set, the value of this option resolves to DISABLED . The value of the option is passed to the server, and can be queried by PCF and MQSC.
- MQCNO_RECONNECT
The application can be reconnected to any queue manager consistent with the value of the
QmgrName
parameter of MQCONNX. Use the MQCNO_RECONNECT option only if there is no affinity between the client application and the queue manager with which it initially established a connection. The value of the option is passed to the server, and can be queried by PCF and MQSC.- MQCNO_RECONNECT_DISABLED
The application cannot be reconnected. The value of the option is not passed to the server.
- MQCNO_RECONNECT_Q_MGR
The application can be reconnected only to the queue manager with which it originally connected. Use this value if a client can be reconnected, but there is an affinity between the client application and the queue manager with which it originally established a connection. Choose this value if you want a client to automatically reconnect to the standby instance of a highly available queue manager. The value of the option is passed to the server, and can be queried by PCF and MQSC.
MQCC_FAILED
and reason code
MQRC_OPTIONS_ERROR
. Automatic client reconnect is not supported
by WebSphere MQ classes
for JavaConversation-sharing options
- MQCNO_NO_CONV_SHARING
This option does not permit conversation sharing.
You might use MQCNO_NO_CONV_SHARING in situations where conversations are heavily loaded and, therefore, where contention is a possibility on the server-connection end of the channel instance on which the sharing conversations exist. MQCNO_NO_CNV_SHARING behaves like sharecnv(1) when connected to a channel that supports conversation sharing, and sharecnv(0) when connected to a channel that does not support conversation sharing.
- MQCNO_ALL_CONVS_SHARE
This option permits conversation sharing; the application does not place any limit on the number of connections on the channel instance. This option is the default value.
If the application indicates that the channel instance can share, but the
SharingConversations
(SHARECNV) definition on the server-connection end of the channel is set to one, no sharing occurs and no warning is given to the application.Similarly, if the application indicates that sharing is permitted but the server-connection
SharingConversations
definition is set to zero, no warning is given, and the application exhibits the same behavior as a client in versions of the product earlier than version 7.0; the application setting relating to sharing conversations is ignored.
MQCNO_NO_CONV_SHARING and MQCNO_ALL_CONVS_SHARE are mutually exclusive. If both options are specified on a particular connection, the connection is rejected with a reason code of MQRC_OPTIONS_ERROR.
Channel definition options
- MQCNO_CD_FOR_OUTPUT_ONLY
This option permits channel definition structure in the MQCNO to be used only to return the channel name used on a successful MQCONNX call.
If a valid channel definition structure is not provided, the call fails with the reason code MQRC_CD_ERROR.
If the application is not running as a client, the option is ignored.
The returned channel name can be used on a subsequent MQCONNX call using the MQCNO_USE_CD_SELECTION option to reconnect using the same channel definition. This can be useful when there are multiple applicable channel definitions in the client channel table.
- MQCNO_USE_CD_SELECTION
This option permits MQCONNX call to connect using the channel name contained in the channel definition structure passed in the MQCNO.
If the MQSERVER environment variable is set, the channel definition defined by it is used. If MQSERVER is not set, the client channel table is used.
If a channel definition with matching channel name and queue manager name is not found, the call fails with reason code MQRC_Q_MGR_NAME_ERROR.
If a valid channel definition structure is not provided, the call fails with the reason code MQRC_CD_ERROR.
If the application is not running as a client, the option is ignored.
Default option
- MQCNO_NONE
No options are specified.
Use MQCNO_NONE to aid program documentation. It is not intended that this option is used with any other MQCNO_* option, but because its value is zero, such use cannot be detected.