Defining a NetBIOS connection

WebSphere MQ uses three types of NetBIOS resource when establishing a NetBIOS connection to another WebSphere MQ product: sessions, commands, and names. Each of these resources has a limit, which is established either by default or by choice during the installation of NetBIOS.

Each running channel, regardless of type, uses one NetBIOS session and one NetBIOS command. The IBM NetBIOS implementation allows multiple processes to use the same local NetBIOS name. Therefore, only one NetBIOS name needs to be available for use by WebSphere MQ. Other vendors' implementations, for example Novell's NetBIOS emulation, require a different local name per process. Verify your requirements from the documentation for the NetBIOS product you are using.

In all cases, ensure that sufficient resources of each type are already available, or increase the maximums specified in the configuration. Any changes to the values will require a system restart.

During system startup, the NetBIOS device driver displays the number of sessions, commands, and names available for use by applications. These resources are available to any NetBIOS-based application that is running on the same system. Therefore, it is possible for other applications to consume these resources before WebSphere MQ needs to acquire them. Your LAN network administrator should be able to clarify this for you.

Defining the WebSphere MQ local NetBIOS name

The local NetBIOS name used by WebSphere MQ channel processes can be specified in three ways. In order of precedence they are:

  1. The value specified in the -l parameter of the RUNMQLSR command, for example: 
          RUNMQLSR -t NETBIOS -l my_station
  2. The MQNAME environment variable whose value is established by the command: 
          SET MQNAME=my_station

    You can set the MQNAME value for each process. Alternatively, you may set it at a system level -- in the CONFIG.SYS file on OS/2 or in the Windows registry.

    If you are using a NetBIOS implementation that requires unique names, you must issue a SET(TM) MQNAME command in each window in which a WebSphere MQ process is started. The MQNAME value is arbitrary but it must be unique for each process.

  3. The NETBIOS stanza in the queue manager configuration file qm.ini or in the Windows registry. For example: 
          NETBIOS:
 
        LocalName=my_station

Notes:

  1. Due to the variations in implementation of the NetBIOS products supported, you are advised to make each NetBIOS name unique in the network. If you do not, unpredictable results may occur. If you have problems establishing a NetBIOS channel and there are error messages in the queue-manager error log showing a NetBIOS return code of X'15', review your use of NetBIOS names.

  2. On Windows you cannot use your machine name as the NetBIOS name because Windows already uses it.

  3. Sender channel initiation requires that a NetBIOS name be specified either via the MQNAME environment variable or the LocalName in the qm.ini file or in the Windows registry.

Establishing the queue manager NetBIOS session, command, and name limits

The queue manager limits for NetBIOS sessions, commands, and names can be specified in two ways. In order of precedence they are:

  1. The values specified in the RUNMQLSR command: 
          -s  Sessions
      -e  Names
      -o  Commands

    If the -m operand is not specified in the command, the values will apply only to the default queue manager.

  2. The NETBIOS stanza in the queue manager configuration file qm.ini or in the Windows registry. For example: 
          NETBIOS:
 
        NumSess=Qmgr_max_sess
        NumCmds=Qmgr_max_cmds
        NumNames=Qmgr_max_names

Establishing the LAN adapter number

For channels to work successfully across NetBIOS, the adapter support at each end must be compatible. WebSphere MQ allows you to control the choice of adapter number (lana) by using the AdapterNum value in the NETBIOS stanza of your qm.ini file or the Windows registry and by specifying the -a parameter on the runmqlsr command.

The default LAN adapter number used by WebSphere MQ for NetBIOS connections is 0. Verify the adapter number being used on your system as follows:

On OS/2 the adapter number used by NetBIOS on your system can be viewed in the PROTOCOL.INI file or the LANTRAN.LOG file found in the \IBMCOM directory.

On Windows, view the information displayed in the NetBIOS Interface pop-up window. This is accessible by selecting the Network option, which is one of many options displayed when opening the Control icon from the Main Window. Windows can assign multiple 'logical' adapter numbers to one physical LAN adapter. The installation default for 'logical' adapter number 0 is NetBIOS running over a TCP network, not a Token-Ring network. This is not necessary for WebSphere MQ. You should select logical adapter number 1, which is native NetBIOS. WebSphere MQ for Windows uses the 'logical' adapter number for communication.

Specify the correct value in the NETBIOS stanza of the queue manager configuration file, qm.ini, or the Windows registry: 

      NETBIOS:
        AdapterNum=n

where n is the correct LAN adapter number for this system.

Initiating the connection

To initiate the connection, follow these steps at the sending end:

  1. Define the NetBIOS station name using the MQNAME or LocalName value as described above.
  2. Verify the LAN adapter number being used on your system and specify the correct file using the AdapterNum as described above.
  3. In the ConnectionName field of the channel definition, specify the NetBIOS name being used by the target listener program. On Windows, NetBIOS channels must be run as threads. Do this by specifying MCATYPE(THREAD) in the channel definition. 
    DEFINE CHANNEL (chname) CHLTYPE(SDR) +
       TRPTYPE(NETBIOS) +
       CONNAME(your_station) +
       XMITQ(xmitq) +
       MCATYPE(THREAD) +
       REPLACE

Target listener

At the receiving end, follow these steps:

  1. Define the NetBIOS station name using the MQNAME or LocalName value as described above.
  2. Verify the LAN adapter number being used on your system and specify the correct file using the AdapterNum as described above.
  3. Define the receiver channel: 
    DEFINE CHANNEL (chname) CHLTYPE(RCVR) +
       TRPTYPE(NETBIOS) +
       REPLACE
  4. Start the WebSphere MQ listener program to establish the station and make it possible to contact it. For example: 
    RUNMQLSR -t NETBIOS -l your_station [-m qmgr]

    This command establishes your_station as a NetBIOS station waiting to be contacted. The NetBIOS station name must be unique throughout your NetBIOS network.

For the best performance, run the WebSphere MQ listener as a trusted application as described in Running channels and listeners as trusted applications. See the WebSphere MQ Application Programming Guide for information about trusted applications.

You can stop all WebSphere MQ listeners running on a queue manager that is inactive, using the command: 

ENDMQLSR [-m QMNAME]

If you do not specify a queue manager name, the default queue manager is assumed.


© IBM Corporation 2002. All Rights Reserved