MQCNO (Connect options) on IBM i
The MQCNO structure allows the application to specify options relating to the connection to the local queue manager.
Overview
Purpose: The structure is an input/output parameter on the MQCONNX call.
Version: The current version of MQCNO is CNVER6. Fields that exist only in the more-recent versions of the structure are identified as such in the descriptions that follow.
The COPY file provided contains the most recent version of MQCNO that is supported by the environment, but with the initial value of the CNVER field set to CNVER1. To use fields that are not present in the version-1 structure, the application must set the CNVER field to the version number of the version required.
Character set and encoding: Data in MQCNO must be in the character set given by the CodedCharSetId queue manager attribute and encoding of the local queue manager given by ENNAT.
Fields
The MQCNO structure contains the following fields; the fields are described in alphabetical order:
- CCDTUL (10-digit signed integer)
-
CCDTUL is the length of the string identified by either CCDTUP or CCDTUO which contains a URL that identifies the location of the client connection channel table to use for the connection.
Use CCDTUL only when the application issuing the MQCONNX call is running as an IBM MQ MQI client.
This is a programmatic alternative to setting the MQCHLLIB and MQCHLTAB environment variables.
If the application is not running as an client, CCDTUL is ignored.
This field is ignored if CNVER is less than CNVER6.
- CCDTUO (10-digit signed integer)
-
CCDTUO is the offset in bytes, from the start of the MQCNO structure, to a string which contains a URL that identifies the location of the client connection channel table to use for the connection. The offset can be positive or negative.
Use CCDTUL only when the application issuing the MQCONNX call is running as an IBM MQ MQI client.
Important: We can use only one of CCDTUP and CCDTUO. The call fails with reason code RC2600 if both fields are nonzero.This is a programmatic alternative to setting the MQCHLLIB and MQCHLTAB environment variables.
If the application is not running as an client, CCDTUO is ignored.
This field is ignored if CNVER is less than CNVER6.
- CCDTUP (pointer)
-
CCDTUP is an optional pointer to a string which contains a URL, to identify the location of the client connection channel table to use for the connection..
Use CCDTUP only when the application issuing the MQCONNX call is running as an IBM MQ MQI client.
Important: We can use only one of CCDTUP and CCDTUO. The call fails with reason code RC2600 if both fields are nonzero.This is a programmatic alternative to setting the MQCHLLIB and MQCHLTAB environment variables.
If the application is not running as an client, CCDTUP is ignored.
This field is ignored if CNVER is less than CNVER6.
- CNAN (28-byte character string)
-
The name set by the application to identify the connection to the queue manager. The initial value of the field is null characters.
This field is ignored if CNVER is less than CNVER7.
- CNCCO (10-digit signed integer)
-
This is the offset in bytes of an MQCD channel definition structure from the start of the MQCNO structure.
- CNCCP (pointer)
-
This is a pointer to an MQCD channel definition structure.
- CNCONID (24-byte character string)
-
Unique connection identifier. This field allows the queue manager to reliably identify an application process by assigning it a unique identifier when it first connects to the queue manager.
Applications use the connection identifier for correlation purposes when making PUT and GET calls. All connections are assigned an identifier by the queue manager, no matter how the connection was established.
It is possible to use the connection identifier to force the end of a long running unit of work. To do this, specifying the connection identifier using the PCF command 'Stop Connection', or the MQSC command STOP CONN. For more information about using these commands, see the related links.
The initial value of the field is 24 null bytes.
- CNCT (128-byte bit string)
-
This is a tag that the queue manager associates with the resources that are affected by the application during this connection.
Each application or application instance must use a different value for the tag, so that the queue manager can correctly serialize access to the affected resources. See the descriptions of the CN*CT* options for further details. The tag ceases to be valid when the application terminates, or issues the MQDISC call.
Use the following special value if no tag is required:- CTNONE
- No connection tag specified.
The value is binary zero for the length of the field.
This is an input field. The length of this field is given by LNCTAG. The initial value of this field is CTNONE. This field is ignored if CNVER is less than CNVER3.
Use the field ConnTag when connecting to a z/OS queue manager.
- CNNORES2 (4-byte character string)
-
A reserved field to pad the structure out to a 64-bit boundary. The initial value of the field is binary zero for the length of the field.
This field is ignored if CNVER is less than CNVER7.
- CNOPT (10 digit signed integer)
-
Options that control the action of MQCONNX.
- Binding options
-
The binding options control the type of IBM MQ binding that is used; specify only one of these options:
- CNSBND
- Standard binding.
The standard binding option causes the application and the local queue manager agent to run in separate units of execution, typically in separate processes. The arrangement maintains the integrity of the queue manager; that is, it protects the queue manager from errant programs.
Use CNSBND in situations where the application might not have been fully tested, or might be unreliable or untrustworthy. CNSBND is the default.
CNSBND is defined to aid program documentation. Do not use this option with any other option controlling the type of binding used; but because its value is zero, such use cannot be detected.
This option is supported in all environments.
- CNFBND
- Fast path binding.
The fast path binding option causes the application and the local queue manager agent to be part of the same unit of execution. Fast path is in contrast to the standard binding, where the application and the local queue manager agent run in separate units of execution.
CNFBND is ignored if the queue manager does not support this type of binding; processing continues as though the option had not been specified.
CNFBND 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 fast path binding is known as a trusted application.
Consider the following important points when deciding whether to use the fast path binding:- Use the CNFBND 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 CNFBND. There are also restrictions on the use of shared memory segments.
- The application must not have more than one thread connected to the queue manager at any one time.
- 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 CNFBND in the environments indicated:
- On IBM i, the job must run under user profile QMQM that belongs to the QMQMADM group. Also, the program must not terminate abnormally, otherwise unpredictable results might occur.
For more information about the implications of using trusted applications, see Connect to a queue manager using the MQCONNX call and Restrictions for trusted applications.
- CNSHBD
- Shared Bindings.
The shared bindings option causes the application and the local queue manager agent to run in separate units of execution, typically in separate processes. The arrangement maintains the integrity of the queue manager; that is, it protects the queue manager from errant programs. However some resources are shared between the application and the local queue manager agent. CNSHBD is ignored if the queue manager does not support this type of binding. Processing continues as though the option had not been specified.
- CNIBND
- Isolated Bindings.
The isolated bindings option causes the application and the local queue manager agent to run in separate units of execution, typically in separate processes. The 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. CNIBND is ignored if the queue manager does not support this type of binding. Processing continues as though the option had not been specified.
- Handle-sharing options
-
The following options control the sharing of handles between different threads (units of parallel processing) within the same process. Only one of these options can be specified.
- CNHSN
- No handle sharing between threads.
The no handle sharing between threads 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.
- CNHSB
- Serial handle sharing between threads, with call blocking.
The serial handle sharing between threads, with call blocking, 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.
- CNHSNB
- Serial handle sharing between threads, without call blocking.
The serial handle sharing between threads, without call blocking, option is the same as the " with blocking" option, except that, if the handle is in use by another thread, the call completes immediately with CCFAIL and RC2219 instead of blocking until the handle becomes available.
A thread can have zero or one nonshared handles, plus zero or more shared handles:
- Each MQCONN or MQCONNX call that specifies CNHSN returns a new nonshared handle on the first call, and the same nonshared handle on subsequent calls (assuming no intervening MQDISC call). The reason code is RC2002 for the second and later calls.
- Each MQCONNX call that specifies CNHSB or CNHSNB 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.
If we do not specify a handle-sharing option, the default is determined by the environment:- In the Microsoft Transaction Server (MTS) environment, the default is the same as CNHSB.
- In other environments, the default is the same as CNHSN.
- Reconnection options
-
Reconnection options determine if a connection is reconnectable. Only client connections are reconnectable.
- CNRCDF
- 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.
- CNRC
- The application can be reconnected to any queue manager consistent with the value of the MQCONNX QMNAME parameter. Use the CNRC 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.
- CNRCD
- The application cannot be reconnected. The value of the option is not passed to the server.
- CNRCQM
- The application can only be reconnected 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 we 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 CNRC, CNRCD, and CNRCQM 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. Default option: If none of the options described is required, the following option can be used:
- CNNONE
- No options are specified.
CNNONE is defined to aid program documentation. It is not intended that this option is used with any other CN* option, but because its value is zero, such use cannot be detected.
- CNSCO (10-digit signed integer)
-
This is the offset in bytes of an MQSCO structure from the start of the MQCNO structure.
This field is ignored if CNVER is less than CNVER4.
- CNSCP (pointer)
-
This is the address of an MQSCO structure.
This field is ignored if CNVER is less than CNVER4.
- CNSECPO (10-digit signed integer)
-
Security parameters offset. The offset of the MQCSP structure used for specifying a user ID and password.
The value may be positive or negative. The initial value of this field is 0.
This field is ignored if CNVER is less than CNVER5.
- CNSECPP (pointer)
-
Security parameters pointer. Address of the MQCSP structure used for specifying a user ID and a password.
The initial value of this field is a null pointer or null bytes.
This field is ignored if CNVER is less than CNVER5.
- CNSID (4-byte character string)
-
The structure identifier for the MQCNO structure.
The value must be:- CNSIDV
- Identifier for connect-options structure.
This is always an input field. The initial value of this field is CNSIDV.
- CNVER (10-digit signed integer)
-
The structure version number for the MQCNO structure.
The value must be:- CNVER6
- Version-6 connect-options structure.
This version is supported in all environments.
- CNVER7
- Version-7 connect-options structure.
This version is supported in all environments.
The following constant specifies the version number of the current version:
- CNVERC
- Current version of connect-options structure.
This is always an input field. The initial value of this field is CNVER7.
Initial values
| Field name | Name of constant | Value of constant |
|---|---|---|
| CNSID | CNSIDV | 'CNO¬ |
| CNVER | CNVER5 | 1 |
| CNOPT | CNNONE | 0 |
| CNCCO | None | 0 |
| CNCCP | None | Null pointer or null bytes |
| CNCT | CTNONE | Nulls |
| CNSCP | None | Null pointer or null bytes |
| CNSCO | None | 0 |
| CNCONID | None | Nulls |
| CNSECPO | None | 0 |
| CNSECPP | None | Null pointer or null bytes |
| CCDTUL | None | 0 |
| CCDTUO | None | 0 |
| CCDTUP | None | Null pointer or null bytes |
- The symbol ¬ represents a single blank character.
RPG declaration
D******************************************************************
D** **
D** IBM MQ for IBM i **
D** **
D** FILE NAME: CMQCNOG **
D** **
D** DESCRIPTION: MQCNO Structure -- Connect Options **
D** **
D******************************************************************
D** <N_OCO_COPYRIGHT> **
D** **
D** 5724-H72 **
D** (c) Copyright IBM Corp. 1993, 2020. All Rights Reserved. **
D** **
D** disclosure restricted by GSA ADP Schedule Contract with **
D** IBM Corp. **
D** <NOC_COPYRIGHT> **
D******************************************************************
D** **
D** FUNCTION: This file declares the structure MQCNO, **
D** which is used by the main MQI. **
D** **
D** PROCESSOR: RPG (ILE) **
D** **
D******************************************************************
D*
D*
D******************************************************************
D** <BEGIN_BUILDINFO> **
D** Generated on: 08/02/16 13:50 **
D** Build Level: L000000 **
D** Build Type: Production **
D** Pointer Size: 128 Bit **
D** Source File: **
D** CMQCNOG **
D** <END_BUILDINFO> **
D******************************************************************
D*
D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
D*
D*
D* MQCNO Structure
D*
D* Structure identifier
D CNSID 1 4 INZ('CNO ')
D* Structure version number
D CNVER 5 8I 0 INZ(1)
D* Options that control the action of MQCONNX
D CNOPT 9 12I 0 INZ(0)
D* Ver:1 **
D* Offset of MQCD structure for client connection
D CNCCO 13 16I 0 INZ(0)
D* Address of MQCD structure for client connection
D CNCCP 17 32* INZ(*NULL)
D* Ver:2 **
D* Queue managerconnection tag
D CNCT 33 160 INZ(X'00000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 0000000000000000000000000-
D 00000000000000')
D* Ver:3 **
D* Address of MQSCO structure for client connection
D CNSCP 161 176* INZ(*NULL)
D* Offset of MQSCO structure for client connection
D CNSCO 177 180I 0 INZ(0)
D* Ver:4 **
D* Unique Connection Identifier
D CNCONID 181 204 INZ(X'00000000000000000-
D 0000000000000000000000000-
D 000000')
D* Offset of MQCSP structure
D CNSECPO 205 208I 0 INZ(0)
D* Address of MQCSP structure
D CNSECPP 209 224* INZ(*NULL)
D* Ver:5 **
D* Address of CCDT URL string
D CNCCDTUP 225 240* INZ(*NULL)
D* Offset of CCDT URL string
D CNCCDTUO 241 244I 0 INZ(0)
D* Length of CCDT URL
D CNCCDTUL 245 248I 0 INZ(0)
D* Ver:6 **
D*
D******************************************************************
D** End of CMQCNOG **
D******************************************************************
Parent topic: Data type descriptions on IBM i