VISTA XWB Broker Troubleshooting

Starting the Broker

On GT.M, to start the broker, you need to create an OS service (Xinetd on Linux) that calls GTMLNX^XWBTCPM.

On Cache, you can start a broker listener using the start-up file ZSTU by calling this: J ZISTCP^XWBTCPM1(<port no>):"<namespace>"

On Cache, you can also fill out the RPC Broker Site Parameters file like this:

Select OPTION NAME: XWB MENU       RPC Broker Management Menu


          RPC Listener Edit
          Start All RPC Broker Listeners
          Stop All RPC Broker Listeners
          Clear XWB Log Files
          Debug Parameter Edit
          View XWB Log

Select RPC Broker Management Menu <TEST ACCOUNT> Option: RPC LISTener Edit

Select RPC BROKER SITE PARAMETERS DOMAIN NAME: ?
    Answer with RPC BROKER SITE PARAMETERS DOMAIN NAME, or STATUS:
   VISTA.PLATINUM    
    
Select RPC BROKER SITE PARAMETERS DOMAIN NAME:    VISTA.PLATINUM 
Select BOX-VOLUME PAIR: ICARUS:icarus// 
  BOX-VOLUME PAIR: ICARUS:icarus// 
  Select PORT: 9000
  Are you adding '9000' as a new PORT (the 1ST for this LISTENER)? No// Y
  (Yes)
    STATUS: STOPPED// 
    TYPE OF LISTENER: ?
     Choose from: 
       0        Original
       1        New Style
    TYPE OF LISTENER: 1  New Style
    CONTROLLED BY LISTENER STARTER: ?
     Choose from: 
       0        NO
       1        YES
    CONTROLLED BY LISTENER STARTER: 1  YES

Then ask Taskman to start this upon Taskman start-up, by creating this entry in file 19.2:

OUTPUT FROM WHAT FILE: OPTION SCHEDULING// 
Select OPTION SCHEDULING NAME:    XWB LISTENER STARTER
ANOTHER ONE: 
STANDARD CAPTIONED OUTPUT? Yes//   (Yes)
Include COMPUTED fields:  (N/Y/R/B): NO//  - No record number (IEN), no Computed
 Fields

NAME: XWB LISTENER STARTER              SPECIAL QUEUEING: STARTUP

When you start taskman from ZSTU using J ^ZTMB:"<namespace>", the broker will be started by taskman.

Troubleshooting

Environment Check and Unit Test

The broker can fail at several points. All of them are covered by an environment check that either Wally or Joel wrote: D CHECK^XWBTCPMT. Here's an example:

GTM>D CHECK^XWBTCPMT

This will check for some of the errors that can prevent the Broker
from getting started.

Debugging is set to Very Verbose
Broker activity timeout is set to 180
Checking can Write to null device
The NULL device is OK.
Checking if new JOB's can start.
New jobs are allowed.
Done with the checks.

From the above, you can glean why a broker might not start or accept connections:

1. The VOLUME multiple in the Kernel System Parameters isn't filled out properly.
2. The VOLUME SET file has the disable flag set to yes.
3. There is more than one NULL device or no NULL device.
4. Your Mumps Implementation license doesn't allow you to start a new job.
5. $$ACTJ^%ZOSV says you ran out of licenses.

In the same routine, there is also a broker tester to test your broker system by connecting to it, only you are doing it directly from Mumps. Here's an example:

GTM>D CALL^XWBTCPMT

Interactive Broker Test
IP ADDRESS: 127.0.0.1
PORT: 9200
Success, response: accept

If this call succeeds (and you need to make sure that this is indeed the right port that hooks up to your VISTA system), then you are now certain that the new style broker works to some extent.

Broker Logging

If you have further issues, the easiest way to troubleshoot them is to turn on broker logging, like this:

GTM>S DUZ=1 D ^XUP

Setting up programmer environment
This is a TEST account.

Terminal Type set to: C-VT220

Select OPTION NAME: XWB MENU       RPC Broker Management Menu


          RPC Listener Edit
          Start All RPC Broker Listeners
          Stop All RPC Broker Listeners
          Clear XWB Log Files
          Debug Parameter Edit
          View XWB Log

Select RPC Broker Management Menu <TEST ACCOUNT> Option: DEBUG Parameter Edit



-------- Setting RPCBroker debug logging  for System: FOIA.PLATINUM  --------
Enable Broker Logging: very Verbose// ?

Enter a code from the list.

     Select one of the following:

          0         No
          1         Yes
          2         Verbose
          3         very Verbose

Enable Broker Logging: very Verbose// 3  very Verbose

After you do that, you need to clear the old logs:

Select RPC Broker Management Menu <TEST ACCOUNT> Option: CLEAR XWB Log Files
Remove all XWB log entries? No// YES
Done

Now, perform the connection, replicate the error that you encounter, and then check-out the broker logs using the option 'View XWB Log'. A good familiarity with the broker TCP protocol will help you understand it; here's an excerpt:

Log from Job 4115 25 Lines
09:43:36 = Log start: Apr 09, 2012@09:43:36
09:43:36 = XWBTCPM
09:43:36 = rd: [XWB]
09:43:36 = MSG format is [XWB] type NEW
09:43:36 = rd: 1030
09:43:36 = rd: 4
09:43:36 = rd: \10
09:43:36 = rd: TCPConnect
09:43:36 = CMD: TCPConnect
09:43:36 = rd: 5
09:43:36 = rd: 0
09:43:36 = rd: 012
09:43:36 = rd: 192.168.0.17
09:43:36 = rd: f
09:43:36 = rd: 0
09:43:36 = rd: 001
09:43:36 = rd: 0
09:43:36 = rd: f
09:43:36 = rd: 0
09:43:36 = rd: 006
09:43:36 = rd: icarus
09:43:36 = rd: f
09:43:36 = rd: \04

Some essential parts to understand: a byte that is x04 (\04) always ends a message. A byte "f" means it's the end of the argument. The item just before the argument is the argument length (006). The client creates this message. Therefore, if this message is not created properly at the client, it won't be read properly by VISTA.

Foreground Debugging of Broker Calls

Last but not least, for desperate debuggers, you can put breakpoints in your current process and run the listener process in the foreground and then connect your client. You will hit the breakpoint:

GTM>D DEBUG^XWBTCPM

Before running this entry point set your debugger to stop at
the place you want to debug. Some spots to use:
'SERV+1^XWBTCPM', 'MAIN+1^XWBTCPM' or 'CAPI+1^XWBPRS.'

or location of your choice.

IP Socket to Listen on: <etc>...