Japanese

Practical mastering IBM MQ basics

Connection mode (2) client connection (1)

An application that is executed in a client connection(client mode) is called an MQI client(Execute MQI, which is an API provided by MQ, from a remote(client)). Up until the last time, the explanation focused on bind connections (some mention was made on client connections), but this time the explanation focuses on client connections.

*This series may be revised based on the latest mqpgf/mqpcf. Please always download and use the latest version.


Channel connection between machines where data conversion is not supported

If no code conversion is possible between the MQ client default code page and the queue manager CCSID(CodedCharSetId), the connection will fail with 2539 MQRC_CHANNEL_CONFIG_ERROR. In that case, the solution of matching the queue manager's CCSID to the client's code page was introduced before "Ex. 6.4". Changing the queue manager CCSID affects to MQPUT/MQGET calls in bind mode applications that have MQCCSI_Q_MGR(default) set in the MQMD CodedCharSetId field. When MQCCSI_Q_MGR is specified in bind mode, MQMD.CodedCharSetId of the message to be MQPUT will be set to the modified CCSID of the queue manager. Also, if data conversion is performed at the time of MQGET with MQCCSI_Q_MGR specified in bind mode, it will be performed between the CCSID of the message on the queue and the CCSID modified of the queue manager. If you want to avoid this effect, you can use "default data conversion" using ccsid.tbl (MQ9.0 or later: ccsid_part2.tbl).

*The "default data conversion" function is effective not only for client connection but also for connection between servers.

ccsid.tbl/ccsid_part2.tbl is under "/var/mqm/conv/table/" on Unix operating systems and "C:\ProgramData\IBM\MQ\conv\table\" on Windows. Note that changes to this file will affect all queue managers that use this work directory and running in the installation, as they are not directories under "qmgrs"(per queue manager directory). The following two lines are the default data conversion settings, and first line is for EBCDIC type code(the fifth column is "1"), and the second line is for the ASCII(the fifth column is "2").

#default 0 500 1 1 0
#default 0 850 1 2 0

The default state is commented out with "#" at the beginning, so delete it and enable "default data conversion". The point to note is that even if both data codes in conversion are ASCII character codes, it is necessary to make sure that both lines are not commented out. Otherwise, "default data conversion" will not work. In this case, CCSID = 932(Windows) and CCSID = 819(UNIX English mode) is used as an example. In that case, both are ASCII character codes, but even in that case, be sure to enable the two lines for ECDCIC and ASCII. Then, change CCISD(third column) of the line for ASCII from '950' to '932'. You need to restart the queue manager for changes to this table to take effect.

default 0 500 1 1 0
default 0 932 1 2 0

Get packet traces before and after enabling "default data conversion" and compare how it changed. The view of packet tracing in MQ communication will be explained at another time.


Ex. 7.1 Default data conversion behavior

The following is a part of "Transmission Segment Header(TSH)" part and "Initil Data(ID)" part of "INITIAL_DATA" output from the queue manager side in the negotiation between channels when connecting channels, before enabling "default data conversion". As the CCSID, '819', which is the setting value of the CCSID property of the queue manager, is output to TSH.CCSID. And "0x01, Invalid CCSID" is set to ID.IniErrFlg1. After this, the connection fails and is closed.


Test result 7.1.1

>mqpgfc -qm SampleQM -q SampleQ -x nnn.nnn.nnn.nnn(nnnn) -tr
[2018/08/15 17:15:09.225] MQCONNX start qmgr:SampleQM Options:0x00000000
[2018/08/15 17:15:09.373] MQCONNX stop hcon:-1 qmgr:SampleQM CompCd=02 ReasonCd=2539
MQCONNX fail : SampleQM CompCd=02 ReasonCd=2539
!!! Queue Manager Connect Fail SampleQM !!!

Packet trace excerpt:
WebSphere MQ (INITIAL_DATA)
Transmission Segment Header
StructID..: TSH
MQSegmLen.: 268
Byte order: Big endian (0x01)
SegmType..: INITIAL_DATA (0x01)
Ctl Flag 1: 0x02, Error
Ctl Flag 2: 0x00
LUW Ident.: 0000000000000000
Encoding..: 111-273 (FLT_IEEE_NORMAL/DEC_NORMAL/INT_NORMAL)
CCSID.....: (819)
Reserved..: 0x0000
Initial Data
Structid..: ID
FAP level.: 13
CapFlag1..: 0x25, MQ request, Split messages, Message sequence
ECapFlag1.: 0x00
IniErrFlg1: 0x01, Invalid CCSID

fig 7.1

The following is the same part after enabling "default data conversion". '932' set in ccsid.tbl/ccsid_part2.tbl as CCSID is output to TSH.CCSID. And "0x01, Invalid CCSID" of ID.IniErrFlg1 is not output. After this, the connection is successful and MQ messages are exchanged.


Test result 7.1.2

>mqpgfc -qm SampleQM -q SampleQ -m test -x 16.147.169.198(18551) -tr
[2018/08/15 17:20:05.932] MQCONNX start qmgr:SampleQM Options:0x00000000
[2018/08/15 17:20:06.144] MQCONNX stop hcon:33554438 qmgr:SampleQM CompCd=00 ReasonCd=00
[2018/08/15 17:20:06.145] MQOPEN start hcon:33554438 ObjectName:SampleQ Options:0x00000010
[2018/08/15 17:20:06.214] MQOPEN stop hcon:33554438 ObjectName:SampleQ CompCd=00 ReasonCd=00
[2018/08/15 17:20:06.215] 1: message length: 4 put message: test
[2018/08/15 17:20:06.218] MQPUT start hcon:33554438 Options:0x00000000
[2018/08/15 17:20:06.234] MQPUT stop hcon:33554438 CompCd=00 ReasonCd=00
[2018/08/15 17:20:06.239] MQCLOSE start hcon:33554438 Options:0x00000000
[2018/08/15 17:20:06.251] MQCLOSE stop hcon:33554438 CompCd=00 ReasonCd=00
[2018/08/15 17:20:06.257] MQDISC start hcon:33554438
[2018/08/15 17:20:06.281] MQDISC stop hcon:-1 CompCd=00 ReasonCd=00

Packet trace excerpt:
WebSphere MQ (INITIAL_DATA)
Transmission Segment Header
StructID..: TSH
MQSegmLen.: 268
Byte order: Little endian (0x02)
SegmType..: INITIAL_DATA (0x01)
Ctl Flag 1: 0x02, Error
Ctl Flag 2: 0x00
LUW Ident.: 0000000000000000
Encoding..: 222-546 (FLT_IEEE_REVERSED/DEC_REVERSED/INT_REVERSED)
CCSID.....: (932)
Reserved..: 0x0000
Initial Data
Structid..: ID
FAP level.: 13
CapFlag1..: 0x25, MQ request, Split messages, Message sequence
ECapFlag1.: 0x00
IniErrFlg1: 0x80, Invalid HB interval

fig 7.2

to the top


Other workarounds when data conversion is not supported between client and server

For client connections, if data conversion between client and server is not supported, there is a way to use the MQCCSID environment variable. The default CCSID of the client is the code page of the client machine's locale. You can override this value by setting the CCSID to this environment variable. However, note that this method also sets the MQMD CCSID to the value of this environment variable.


Ex. 7.2 Set the queue manager CCSID to the environment variable MQCCSID on the client side

Test between a client with code page 819 and a 932 queue manager.


Test result 7.2

$ unset MQCCSID
$ mqpgfc -qm SampleQM -q SampleQ -m test
$ MQCONN fail : SampleQM CompCd=02 ReasonCd=2539
!!! Queue Manager Connect Fail SampleQM !!!
/home/okaqm9/work/cprog/mqpgf: mqrc 2539

2539 0x000009eb MQRC_CHANNEL_CONFIG_ERROR
$
$ export MQCCSID=932
$ mqpgfc -qm SampleQM -q SampleQ -m test
[18/08/27 17:52:28.062106] 1: message length: 4 put message: test

$ mqpgfc -qm SampleQM -q SampleQ -br
message number: 1
*StrucId[MD ] Version[2] Report[0] MsgType[8] Expiry[-1] Feedback[0] Encoding[273] CodedCharSetId[932] Format[ ] Priority[0] Persistence[0] MsgId[0x414D512053616D706C65514D202020204B71835B23926C02] CorrelId[0x000000000000000000000000000000000000000000000000] BackoutCount[0] ReplyToQ[ ] ReplyToQMgr[SampleQM ] UserIdentifier[pulsar ] AccountingToken[0x16010515000000F99C8959835A305AE2E39508EC03000000000000000000000B] ApplIdentityData[ ] PutApplType[13] PutApplName[mqpgfc ] PutDate[20180827] PutTime[08522237] ApplOriginData[ ]

GroupId[0x000000000000000000000000000000000000000000000000] MsgSeqNumber[1] Offset[0] MsgFlags[0] OriginalLength[-1]

data length: 4
00000000: 7465 7374 'test '

fig 7.3

to the top

Setting of message channel agent user ID (MCAUSER) and authorization

In Ex. 6.4, the MQ channel user "mqm" is set to the message channel agent user ID(MCAUSER) of the default server connection channel(SYSTEM.DEF.SVRCONN). Since MCAUSER is the user ID that MCA uses to grant access to IBM MQ resources, access to MQ resources is possible with the authority of the 'mqm' user, regardless of the connection by any user. This can be a security issue.


Ex. 7.3 Setting authorization of Client Connection User

First, set MCAUSER of SYSTEM.DEF.SVRCONN back to blank. If you leave the server connection channel MQCAUSER blank, by default the running user of the client application(mqpgfc) is used. When setting blanks for parameters in runmqsc, enclose single-byte spaces with single quotes.

MQSC > alter chl(SYSTEM.DEF.SVRCONN) chltype(svrconn) mcauser(' ')
4 : alter chl(SYSTEM.DEF.SVRCONN) chltype(svrconn) mcauser(' ')
AMQ8016: IBM MQ channel changed.

In this state, set up so that the client connection user can connect to the queue manager normally and can PUT/GET to the queue.
If the user does not exist on the server side, the following error is displayed to the queue manager error log.

/var/mqm/qmgrs/SampleQM/errors/AMQERR01.LOG(Default for Unix OS)
....
AMQ9557: Queue Manager User ID initialization failed for 'pulsar'.

EXPLANATION:
The call to initialize the User ID 'pulsar' failed with CompCode 2 and 2035.
ACTION:
Correct the error and try again.
----- cmqxrsrv.c : 2318 -------------------------------------------------------

$ mqrc 2035

2035 0x000007f3 MQRC_NOT_AUTHORIZED

If the corresponding user does not exist on the server side, create it. For the test, try to set the access rights of the user who does not belong to the mqm group or the Windows Administrators group.
For MQ for HP NonStop, use the altmqusr command to map the MQ principal(pulsar) to the NonStop OS user ID(pulsar.plsgrp) as follows:

$ altmqusr -m SampleQM -p pulsar -u pulsar.plsgrp Username mapping for queue manager 'SampleQM' $ dspmqusr -m SampleQM Username mapping for Queue Manager 'SampleQM' Principal Userid Username Alias GroupName GroupType 0.1 mqm 171.255 MQM.MANAGER n MQM a nobody 0.0 pulsar 101.101 PULSAR.PLSGRP n PLSGRP a

After creating the user, add access to the MQ resource. If the permissions are insufficient, the target object and the missing permissions are displayed in the error log as follows:

....
AMQ8077: Entity 'pulsar' has insufficient authority to access object
'SampleQM'.

EXPLANATION:
The specified entity is not authorized to access the required object. The
following requested permissions are unauthorized: connect
....
AMQ8077: Entity 'pulsar' has insufficient authority to access object
'SampleQ'.

EXPLANATION:
The specified entity is not authorized to access the required object. The
following requested permissions are unauthorized: put
....

Here, we grant "connect" permission to the queue manager and "put" and "get" permissions to the queue(SampleQ). See the product documentation for a list of permissions and details.

$ setmqaut -m SampleQM -t qmgr -p pulsar +connect
The setmqaut command completed successfully.

$ dspmqaut -m SampleQM -t qmgr -p pulsar
Entity pulsar has the following authorizations for object SampleQM:
connect

$ setmqaut -m SampleQM -t queue -n SampleQ -p pulsar +put +get
The setmqaut command completed successfully.

$ dspmqaut -m SampleQM -t queue -n SampleQ -p pulsar
Entity pulsar has the following authorizations for object SampleQ:
get
put

Check if you can connect and PUT/GET normally.


Test result 7.3

$ mqpgfc -qm SampleQM -q SampleQ -m test -x nnn.nnn.nnn.nnn(nnnn)
[2018/08/17 13:30:39.208] 1: message length: 4 put message: test

$ mqpgfc -qm SampleQM -q SampleQ -xnnn.nnn.nnn.nnn(nnnn)
[2018/08/17 13:31:07.036] 1: message length: 4 get message : test

In this example, we gave permissions to "Principal name"(-p), but there is also a way to give permissions to "User group name"(-g). The details of setting up object authority manager (OAM) are not described here, but there is only one caveat. Up to MQ 7.5, access permissions have been set on a group basis (Windows is on a per user basis), but since MQ 8.0, it can also be set on a per user basis. This mode is changed by adding "SecurityPolicy" parameter to "Service:" stanza of qm.ini, setting "user" and restarting the queue manager. Dump and compare the OAM permission settings for the default case and when "SecurityPolicy = user" is set in the "Service:" stanza.
*The result of dspmqaut is output as a standard error, so if you want to save the displayed result to a file, redirect the standard error("2>").


$ dmpmqaut -m SampleQM 2> SampleQM.aut
Confirmation of output contents:

* For default (group):
....
- - - - - - - -
profile: self
object type: qmgr
entity: PLSGRP
entity type: group
authority: connect

- - - - - - - -
....
- - - - - - - -
profile: SampleQ
object type: queue
entity: PLSGRP
entity type: group
authority: get put

- - - - - - - -


* When "SecurityPolicy = user" is set in the "Service:" stanza:
....
- - - - - - - -
profile: self
object type: qmgr
entity: pulsar
entity type: principal
authority: connect

- - - - - - - -
....
- - - - - - - -
profile: SampleQ
object type: queue
entity: pulsar
entity type: principal
authority: get put

- - - - - - - -
....

The first has permissions for the group ("PLSGRP") and the second has permissions only for the user ("pulsar"). Set access permissiions according to the system requirements.

fig 7.4

to the top

Default channel authentication record

Channel authentication records are available from MQ7.1. In Ex. 6.4, the channel authentication record was invalidated and tested. There are many variations in how channel authentication records are set up, but here this section briefly describes the default channel authentication record settings.

If channel authentication record is enabled, the following three default channel authentication records are checked.

$ mqpcf mqsc -qm SampleQM -s "dis chlauth(*) all" 1: AMQ8878: Display channel authentication record details. CHLAUTH(SYSTEM.ADMIN.SVRCONN) TYPE(ADDRESSMAP) DESCR(Default rule to allow MQ Explorer access) CUSTOM( ) ADDRESS(*) USERSRC(CHANNEL) CHCKCLNT(ASQMGR) ALTDATE(2018-06-25) ALTTIME(10.56.47) 2: AMQ8878: Display channel authentication record details. CHLAUTH(SYSTEM.*) TYPE(ADDRESSMAP) DESCR(Default rule to disable all SYSTEM channels) CUSTOM( ) ADDRESS(*) USERSRC(NOACCESS) WARN(NO) ALTDATE(2018-06-25) ALTTIME(10.56.47) 3: AMQ8878: Display channel authentication record details. CHLAUTH(*) TYPE(BLOCKUSER) DESCR(Default rule to disallow privileged users) CUSTOM( ) USERLIST(*MQADMIN) WARN(NO) ALTDATE(2018-06-25) ALTTIME(10.56.47)

*Option descriptions
mqsc: Execute MQSC command
-s : MQSC command string

The first record is for the channel "SYSTEM.ADMIN.SVRCONN"(CHLAUTH (SYSTEM.ADMIN.SVRCONN)). This is usually defined for the connection of MQ Explorer. If you do not specify a channel name in mqpgfc, "SYSTEM.DEF.SVRCONN" is used by default, so this record is not relevant for tests using mqpgfc.
The second record is for all channels beginning with "SYSTEM."(CHLAUTH (SYSTEM.*)). The address to block is all addresses(TYPE(ADDRESSMAP) ADDRESS(*)). A matching connection can not access the queue manager and the channel will stop immediately(USERSRC(NOACCESS)). If mqpgfc fails to connect with reason code 2035 before invalidating the channel authentication record, then this channel authentication record applies.
The third record covers all channels(CHLAUTH(*)). Blocks the users specified in USERLIST(TYPE (BLOCKUSER)). The USERLIST "*MQADMIN" is a special value that blocks the following users:

Windows: mqm group, Administrators group, and SYSTEM user
Unix-like OS: mqm group

This authentication record also applies if mqpgfc was executed as the above administrative user. If this authentication record is applicable, the error log will indicate that the userid was blocked.

....
AMQ9776: Channel was blocked by userid

EXPLANATION:
The inbound channel 'SampleQM.MQICHL' was blocked from address 'nnn.nnn.nnn.nnn'
because the active values of the channel were mapped to a userid which should
be blocked. The active values of the channel were 'MCAUSER(pulsar)
CLNTUSER(pulsar)'.

To connect with the default settings, create a new server connection channel and use a user other than the admin user. When changing the group to which the user(server side) belongs, it is necessary to restart the queue manager or execute "refresh security" in order for the queue manager to recognize the change.

$ mqpcf mqsc -qm SampleQM -s "refresh security"
1: AMQ8560: IBM MQ security cache refreshed.

*Option descriptions
mqsc: Execute MQSC command
-s : MQSC command string


Ex. 7.4 Connect by specifying a channel name

Returns the channel authentication record back to valid.

$ mqpcf mqsc -qm SampleQM -s "alter qmgr chlauth(enabled)>
1: AMQ8005: IBM MQ queue manager changed.

Create a new server connection channel.

$ mqpcf mqsc -qm SampleQM -s "def chl(SampleQM.MQICHL) chltype(svrconn)"
1: AMQ8014: IBM MQ channel created.

Execute mqpgfc specifying the channel name to connect.


Test result 7.4

>mqpgfc -qm SampleQM -q SampleQ -m test -x nnn.nnn.nnn.nnn(nnnn) -ch SampleQM.MQICHL
[2018/08/20 16:03:39.323] 1: message length: 4 put message: test

*Option descriptions
-ch: Connection channel name

fig 7.5

to the top

Default connection authentication

Connection authentication is available from MQ 8.0. In Ex. 6.4, connection authentication was once disabled. This section does not describe the connection authentication feature or the details of how to set the configuration, but briefly describes the default settings for client connection.

Restore the CONNAUTH property set to blank to the default "SYSTEM.DEFAULT.AUTHINFO.IDPWOS". After making changes, refresh the queue manager security information.

$ mqpcf mqsc -qm SampleQM -s "alter qmgr connauth(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)"
1: AMQ8005: IBM MQ queue manager changed.

$ mqpcf mqsc -qm SampleQM -s "refresh security type(connauth)"
1: AMQ8560: IBM MQ security cache refreshed.

$ mqpcf qmgr -qm SampleQM CONNAUTH
1: QMNAME(SampleQM) CONNAUTH(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)

Check the settings of the default "Authentication Information (AUTHINFO) Object" (SYSTEM.DEFAULT.AUTHINFO.IDPWOS).

$ mqpcf mqsc -qm SampleQM -s "dis authinfo(SYSTEM.DEFAULT.AUTHINFO.IDPWOS)" 1: AMQ8566: Display authentication information details. AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS) AUTHTYPE(IDPWOS) ADOPTCTX(NO) DESCR( ) CHCKCLNT(REQDADM) CHCKLOCL(OPTIONAL) FAILDLAY(1) ALTDATE(2018-06-25) ALTTIME(10.56.47)

AUTHTYPE indicates the authentication method of UserId and Password set in the MQCSP structure. The following can be set.

IDPWOS Authenticate user ID and password using the local server OS.
IDPWLDAP Authenticate user ID and password using LDAP server.


CHCKCLNT (Client Connection Check) is used for the client connection check method. The following can be set.

NONE Do not check user ID and password.
OPTIONAL Check only if a user ID and password are provided.
REQUIRED Always check user ID and password when connecting.
REQDADM A privileged user always checks the user ID and password but is otherwise optional (same as OPTIONAL).

That is, if the client connection does not use a privileged user, specifying a user/password will perform a check.


Ex. 7.5 Connect by specifying a user/password in MQCSP.

mqpgf can specify a user and password to set in MQCSP with "-cu" and "-cp" respectively. If you specify these, mqpgf automatically sets the pointer of each string to MQCSP.CSPUserIdPtr and MQCSP.CSPPasswordPtr, and automatically sets the length of each string to MQCSP.CSPUserIdLength and MQCSP.CSPPasswordLength. To execute authentication, it is necessary to specify MQCSP_AUTH_USER_ID_AND_PWD in MQCSP.AuthenticationType. When MQCSP_AUTH_* is specified as an argument, mqpgf sets it to MQCSP.AuthenticationType and automatically sets a pointer to MQCSP in MQCSP.SecurityParmsPtr to refer to MQCSP. Also note that MQCNO_VERSION_5 or higher is required to specify this MQCNO.SecurityParmsPtr. The default for MQCNO is MQCNO_VERSION_1 (*mqpgf(c) automatically uses MQCNO_VERSION_2 when "connection name" is specified with -x). If the version of MQCNO is less than MQCNO_VERSION_5, no authentication takes place.

To organize, in order for the queue manager to authenticate a user/password, the application needs to do at least the following.

  1. 1. Set the user ID string to be authenticated to MQCSP.CSPUserIdPtr.
  2. 2. Set the user password string to be authenticated to MQCSP.CSPPasswordPtr.
  3. 3. Set the length of the user ID string in MQCSP.CSPUserIdLength.
  4. 4. Set the length of the password string in MQCSP.CSPPasswordLength.
  5. 5. Specify MQCSP_AUTH_USER_ID_AND_PWD in MQCSP.AuthenticationType.
  6. 6. Set MQCNO.Version to MQCNO.VERSION or higher.

Test result 7.5

>mqpgfc -qm SampleQM -q SampleQ -m test -x nnn.nnn.nnn.nnn(nnnnn) -ch SampleQM.MQICHL -cu pulsar -cp correctPW MQCSP_AUTH_USER_ID_AND_PWD MQCNO_VERSION_5
[2018/08/23 14:50:46.286] 1: message length: 4 put message: test

>mqpgfc -qm SampleQM -q SampleQ -m test -x nnn.nnn.nnn.nnn(nnnnn) -ch SampleQM.MQICHL -cu pulsar -cp wrongPW MQCSP_AUTH_USER_ID_AND_PWD MQCNO_VERSION_5
MQCONNX fail : SampleQM CompCd=02 ReasonCd=2035
!!! Queue Manager Connect Fail SampleQM !!!

>mqrc 2035

2035 0x000007f3 MQRC_NOT_AUTHORIZED

>mqpgfc -qm SampleQM -q SampleQ -m test -x nnn.nnn.nnn.nnn(nnnnn) -ch SampleQM.MQICHL -cu pulsar -cp wrongPW MQCSP_AUTH_USER_ID_AND_PWD
[2018/08/23 14:51:02.293] 1: message length: 4 put message: test

The last example above specifies the wrong password, but MQCNO_VERSION_5 is not specified, so the default MQCNO_VERSION_2, default when "connection name" is specified with -x, is used. The user and password specified in MQCSP were not authenticated, resulting in a successful PUT.
Please try it in various ways.

fig 7.6

to the top

General method of client connection

Client connections use one of the following methods:

1. Specify channel information in MQCONNX() This is how the MQ client application specifies the definition of the client connection channel at run time. It references the channel definition structure MQCD, which contains the definition of the client connection channel, from the MQCNO structure specified in MQCONNX().
2. Use the MQSERVER environment variable On the machine where the client application is running, set the definition of the client's channel to this environment variable.
3. Refer to CCDT by environment variable This method is used to refer to the channel definition table (CCDT), which is a file with channel definition and authentication information for client connection, using the MQCHLLIB/MQCHLTAB environment variable.
4. Set channel information in mqclient.ini Set information on the client channel equivalent to the MQSERVER environment variable in the CHANNELS stanza of the client configuration file(mqclient.ini).
5. Refer to CCDT by mqclient.ini Set reference information to the CCDT equivalent to the MQCHLLIB/MQCHLTAB environment variable in the CHANNELS stanza of the client configuration file(mqclient.ini).

Two methods have been introduced so far for making client connections. One is to set the MQ_CONNECT_TYPE environment variable to CLIENTin Ex. 6.4. And the other is to specify MQCNO_CLIENT_BINDING as the connection option and try the client connection in Ex. 6.5. They are the supplementary explanations above.
For "4." and "5." that use the client configuration file, set the equivalent of the environment variable values in "2." and "3." to the stanza of mqclient.ini. They are functionally similar to environment variables. If set simultaneously, environment variables take precedence.

The order of priority for each of these being set at the same time is as follows.

  1. 1. "1. Specify channel information in MQCONNX()"
  2. 2. "2. Use the MQSERVER Environment variable"
  3. 3. "4. Set channel information in mqclient.ini (setting equivalent to MQSERVER)"
  4. 4. "3. Refer to CCDT by Environment variable(MQCHLLIB/MQCHLTAB)"
  5. 5. "5. Refer to CCDT in mqclient.ini (setting equivalent to MQCHLLIB/MQCHLTAB)"

As mentioned above, there are many variations in the client connection configuration, so select and use the one that best suits your system.
As a premise, in all of these methods, the server connection channel (CHLTYPE (SVRCONN)) on the server side introduced in Ex. 7.3 has been created with the same name as the channel name specified by the client. And it is necessary that the listener (runmqlsr) that monitors the connecting port introduced in "Create a connection to the opposite side queue manager" is started normally. You don't need to create a new listener if you are using it for the connection between the servers.(Use the same port)

fig 7.7

to the top

Specify channel information in MQCONNX()

You can use this method when you want to connect using the parameters set in the system-specific environment file. The following is the procedure for making a client connection by specifying the channel information in MQCONNX().

  1. 1. Initialize MQCD with MQCD_CLIENT_CONN_DEFAULT
  2. 2. Set required fields of MQCD
  3. 3. Set MQCD reference to MQCNO

After initializing MQCD with MQCD_CLIENT_CONN_DEFAULT, set at least the following fields:

Channel Name(ChannelName): Channel name used for client connection
Connection Name(ConnectionName): ipaddr or hostname(port)
Version(Version): MQCD_VERSION_2 or higher

To make MQCNO refer to MQCD, set MQCD pointer to MQCNO.ClientConnPtr.

to the top

How to set the MQSERVER environment variable

It is the simplest way. It is often used in testing because its priority is high. Set in the following format.

Windows: SET MQSERVER=ChannelName/TransportType/ConnectionName
Unix-like OS: export MQSERVER=ChannelName/TransportType/ConnectionName

The following are setting examples. The format of ConnectionName is "ipaddr or hostname(port)". For Unix/Linux, enclose it in single quotes.

SET MQSERVER=SampleQM.MQICHL/TCP/9.20.4.56(1415) *Windows
export MQSERVER=SampleQM.MQICHL/TCP/'9.20.4.56(1415)' *Unix/Linux

When setting the equivalent definition in mqclient.ini, set in the same format in ServerConnectionParms of the CHANNELS stanza. mqclient.ini is located by default below.

Windows(MQ7.5 or earlier): C:¥Program Files¥IBM¥WebSphere MQ\mqclient.ini
Windows(MQ 8.0 or higher): C:\ProgramData\IBM\MQ\mqclient.ini
Unix-like OS: /var/mqm/mqclient.ini
MQ8 for HP NonStop: $MQINST/mqclient.ini

The following are setting examples. In mqlient.ini, there is no need to enclose ConnectionName in single quotes, as in the case of environment variables, even in Unix/Linux.

CHANNELS:
ServerConnectionParms=SampleQM.MQICHL/TCP/9.20.4.56(1415)

to the top

How to use the client channel definition table

Before MQ 7.5, this client channel definition table(CCDT) had to be created on the server side(queue manager), but as of MQ 8.0, it can be created on the client side. To create on the client side, run runmqsc with only the "-n" option specified on the machine where MQ client is installed. The following is an example of creating a client channel.

$ runmqsc -n
5724-H72 (C) Copyright IBM Corp. 1994, 2014.
Starting local MQSC for 'AMQCLCHL.TAB'.

MQSC > def chl(SampleQM.MQICHL) chltype(clntconn) conname('nnn.nnn.nnn.nnn(nnnn)') QMNAME('SampleQM')
1 : def chl(SampleQM.MQICHL) chltype(clntconn) conname('nnn.nnn.nnn.nnn(nnnn)') QMNAME('SampleQM')
AMQ8014: IBM MQ channel created.
MQSC >

The channel definition table is created by default in the work directory(the same location as the default mqclient.ini above). If MQCHLLIB and MQCHLTAB are set, they are created in the directory indicated by MQCHLLIB with the name specified in MQCHLTAB. If MQCHLLIB and MQCHLTAB are not set when running a MQ client application, the work directory AMQCLCHL.TAB is referenced by default.

To set the equivalent definition in mqclient.ini, set the path of the channel definition table in ChannelDefinitionDirectory of the CHANNELS stanza, and set the file name of the channel definition table in ChannelDefinitionFile.

CHANNELS:
ChannelDefinitionDirectory=/var/clientfiles
ChannelDefinitionFile=PULSAR.TAB

Channel definition tables allow you to create queue manager groups and take advantage of many features that would not otherwise be possible. Next time, I will introduce the specific usage method.

to the top

to the top