Options (MQLONG)
Options that control the action of MQCONNX.
Accounting options: The following
options further control the type of accounting if the 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 queue manager in the MQIAccounting 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 queue manager in the MQIAccounting field
of their queue definition.
If none of these flags is defined, the accounting
for the connection is as defined in the Queue Manager attributes.
Binding options: The following options control
the type of 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 (generally,
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 looks for the DefaultBindType attribute
in the Connection stanza in the qm.ini file (or the equivalent Windows(R) 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.
- 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 normal 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 may be of advantage in
situations where the use of multiple processes is a significant performance
overhead compared to 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:
- Use of the MQCNO_FASTPATH_BINDING option compromises
the integrity of the queue manager, because it permits a rogue application
to alter or corrupt messages and other data areas belonging to the queue manager.
Use it 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. Refer to the WebSphere MQ Application Programming Guide for
more information.
- The application must use the MQDISC call to disconnect
from the queue manager.
- The application must finish before ending the queue manager with the endmqm command.
The following points apply to the use of MQCNO_FASTPATH_BINDING
in the environments indicated:
For more information about the implications of using trusted
applications, see the WebSphere MQ Application Programming Guide.
This option is
supported in the following environments: AIX, HP-UX, , i5/OS, Solaris, Linux, Windows.
On z/OS the option is accepted but ignored.
- MQCNO_SHARED_BINDING
- The application and the local queue manager agent (the component that
manages queuing operations) run in separate units of execution (generally,
in separate processes). This arrangement maintains the integrity of the queue
manager, that is, it protects the queue manager from errant programs. However,
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
- The application and the local queue manager agent (the component that
manages queuing operations) run in separate units of execution (generally,
in separate processes). This arrangement maintains the integrity of the queue
manager, that is, it protects the queue manager from errant programs. 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.
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, STANDARD; if it has some other value, it is ignored. The value of the environment
variable is case sensitive.
The environment variable and 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: The following options control
the use of the connection tag ConnTag. You can specify
only one of these options.
- These options are supported only when connecting to a z/OS queue
manager.
- 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 use of 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 provided that
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.
- On z/OS, applications must run within the same MVS(TM) address space
in order 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 that:
- The requesting application is running in the same processing scope as
the existing user of the tag.
- The requesting application 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.
- On z/OS, applications must run within the same MVS address space
in order 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 is specified, ConnTag is not
used. These options are not valid if Version is less than
MQCNO_VERSION_3.
Handle-sharing options: The following options
control the sharing of handles between different threads (units of parallel
processing) within the same process. You can specify only one of these options.
- These options are supported in the following environments: AIX, HP-UX, i5/OS, Solaris, Linux, Windows.
- 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.
A thread can have zero or one nonshared handle:
- Each MQCONN or MQCONNX call
that specifies MQCNO_HANDLE_SHARE_NONE returns a new nonshared handle on the
first call, and the same nonshared 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 shareability as the connection handle specified
on the MQOPEN call that created the object handle. Also,
units of work inherit the same shareability 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.
If you specify no handle-sharing option, the default is determined by the
environment:
- In the Microsoft(R) 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.
Default option: If you require none of the options
described above, you can use the following option:
- MQCNO_NONE
- No options specified.
Use MQCNO_NONE to aid program documentation.
It is not intended that this option be used with any other MQCNO_*
option, but as its value is zero, such use cannot be detected.
This is always an input field. The initial value of this field is MQCNO_NONE.