ClientConnPtr (MQPTR)
ClientConnPtr is an input field. Its initial value is the null pointer in those programming languages that support pointers, and an all-null byte string otherwise.
Use ClientConnOffset and ClientConnPtr only when the application issuing the MQCONNX call is running as an IBM MQ MQI client. By specifying one or other of these fields, the application can control the definition of the client connection channel by providing an MQCD channel definition structure that contains the values required.
If the application is running as an IBM MQ MQI client, but does not provide an MQCD structure, the MQSERVER environment variable is used to select the channel definition. If MQSERVER is not set, the client channel table is used.
If the application is not running as an IBM MQ MQI client, ClientConnOffset and ClientConnPtr are ignored.
If the application provides an MQCD structure, set the fields listed to the values required; other fields in MQCD are ignored. We can pad character strings with blanks to the length of the field, or terminated them with a null character. See Fields for more information about the fields in the MQCD structure.
| Field in MQCD | Value |
|---|---|
| ChannelName | Channel name. |
| Version | Structure version number. Must not be less than MQCD_VERSION_7. |
| TransportType | Any supported transport type. |
| ModeName | LU 6.2 mode name. |
| TpName | LU 6.2 transaction program name. |
| SecurityExit | Name of channel security exit. |
| SendExit | Name of channel send exit. |
| ReceiveExit | Name of channel receive exit. |
| MaxMsgLength | Maximum length in bytes of messages that can be sent over the client connection channel. |
| SecurityUserData | User data for security exit. |
| SendUserData | User data for send exit. |
| ReceiveUserData | User data for receive exit. |
| UserIdentifier | User identifier to be used to establish an LU 6.2 session. |
| Password | Password to be used to establish an LU 6.2 session. |
| ConnectionName | Connection name. |
| HeartbeatInterval | Time in seconds between heartbeat flows. |
| StrucLength | Length of the MQCD structure. |
| ExitNameLength | Length of exit names addressed by SendExitPtr and ReceiveExitPtr. Must be greater than zero if SendExitPtr or ReceiveExitPtr is set to a value that is not the null pointer. |
| ExitDataLength | Length of exit data addressed by SendUserDataPtr and ReceiveUserDataPtr. Must be greater than zero if SendUserDataPtr or ReceiveUserDataPtr is set to a value that is not the null pointer. |
| SendExitsDefined | Number of send exits addressed by SendExitPtr. If zero, SendExit and SendUserData provide the exit name and data. If greater than zero, SendExitPtr and SendUserDataPtr provide the exit names and data, and SendExit and SendUserData must be blank. |
| ReceiveExitsDefined | Number of receive exits addressed by ReceiveExitPtr. If zero, ReceiveExit and ReceiveUserData provide the exit name and data. If greater than zero, ReceiveExitPtr and ReceiveUserDataPtr provide the exit names and data, and ReceiveExit and ReceiveUserData must be blank. |
| SendExitPtr | Address of name of first send exit. |
| SendUserDataPtr | Address of data for first send exit. |
| ReceiveExitPtr | Address of name of first receive exit. |
| ReceiveUserDataPtr | Address of data for first receive exit. |
| LongRemoteUserIdLength | Length of long remote user identifier. |
| LongRemoteUserIdPtr | Address of long remote user identifier. |
| RemoteSecurityId | Remote security identifier. |
| SSLCipherSpec | TLS CipherSpec. |
| SSLPeerNamePtr | Address of TLS peer name. |
| SSLPeerNameLength | Length of TLS peer name. |
| KeepAliveInterval | Value passed to the communications stack for keepalive timing for the channel |
| LocalAddress | The local communications address, including the IP address of the local network adapter to use, and a range of ports to use for outgoing connections. |
- By using the offset field ClientConnOffset
In this case, the application must declare a compound structure containing an MQCNO followed by the channel definition structure MQCD, and set ClientConnOffset to the offset of the channel definition structure from the start of the MQCNO. Ensure that this offset is correct. ClientConnPtr must be set to the null pointer or null bytes.
Use ClientConnOffset for programming languages that do not support the pointer data type, or that implement the pointer data type in a way that is not portable to different environments (for example, the COBOL programming language).
For the Visual Basic programming language, a compound structure called MQCNOCD is provided in the header file CMQXB.BAS; this structure contains an MQCNO structure followed by an MQCD structure. Initialize MQCNOCD by invoking the MQCNOCD_DEFAULTS subroutine. MQCNOCD is used with the MQCONNXAny variant of the MQCONNX call; see the description of the MQCONNX call for further details.
- By using the pointer field ClientConnPtr
In this case, the application can declare the channel definition structure separately from the MQCNO structure, and set ClientConnPtr to the address of the channel definition structure. Set ClientConnOffset to zero.
Use ClientConnPtr for programming languages that support the pointer data type in a way that is portable to different environments (for example, the C programming language).
In the C programming language, we can use the macro variable MQCD_CLIENT_CONN_DEFAULT to provide initial values for the structure that are more suitable for use on the MQCONNX call than the initial values provided by MQCD_DEFAULT.
Whichever technique you choose, we can use only one of ClientConnOffset and ClientConnPtr ; the call fails with reason code MQRC_CLIENT_CONN_ERROR if both are nonzero.
When the MQCONNX call has completed, the MQCD structure is not referenced again.
This field is ignored if Version is less than MQCNO_VERSION_2.
Note: On platforms where the programming language does not support the pointer data type, this field is declared as a byte string of the appropriate length, with the initial value being the all-null byte string. Parent topic: Fields for MQCNO