Options (MQLONG)

Options that control the action of MQCONNX.

Accounting options

MQCNO_ACCOUNTING_MQI_ENABLED

When monitoring data collection is disabled 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 disabled 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 disabled 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 the MQIAccounting field of their queue definition.

MQCNO_ACCOUNTING_Q_DISABLED

When queue-accounting data collection is disabled 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 the MQIAccounting 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 IBM 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 the Connection stanza in the qm.ini file 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 behavior 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_CONNECTI_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_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:

• Use 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 we 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, the mqm user identifier must be the effective user identifier, and the mqm 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 the mqm user identifier and mqm group identifier, and then set the setuid and setgid permission bits on the program.

  The IBM 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 ignored on z/OS.
• 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.

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.

On AIX, HP-UX, Solaris, Linux, and Windows, we 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.

• 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

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.

Use the options MQCNO_RECONNECT, MQCNO_RECONNECT_DISABLED and MQCNO_RECONNECT_Q_MGR only for client connections. If the options are used for a binding connection, MQCONNX fails with completion code MQCC_FAILED and reason code MQRC_OPTIONS_ERROR. Automatic client reconnect is not supported by IBM MQ classes for Java

Conversation-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.