Tutorial 04 07 Add Traditional Bridge Host

Tutorial 4: Add Traditional Bridge Host

The traditional Synergy side of your Traditional Bridge environment is almost complete. All that remains is to write the code for the Traditional Bridge host program.

The host program typically performs these steps:

• Opens and configures the terminal channel environment.
• Configures and initializes logging.
• Creates an instance of the master dispatcher class.
• Sends a "READY" message on STDOUT to tell Harmony Core that the host program is running.
• Instructs the master dispatcher class to start listening for and dispatching messages.
• Closes the log file when the master dispatcher exits.
• Gracefully deals with any unexpected exceptions.

Import Namespaces

The code that you will include in the program will manipulate classes from several namespaces, so we'll start by importing those namespaces to make the classes easier to access:

1. Open TraditionalBridgeHost.dbl and add the following code right at the top of the file, before the main compiler directive:

   ;;*****************************************************************************
   ;;
   ;; Title:       TraditionalBridgeHost.dbl
   ;;
   ;; Description: A program to host a Harmony Core Traditional Bridge environment
   ;;              that exposes traditional Synergy business logic to a Harmony
   ;;              Core web service.
   ;;
   ;;*****************************************************************************
   
   import Harmony.TraditionalBridge
   import Json
   import TraditionalBridge
   import TraditionalBridge.Dispatchers
   

Declare variables

The code that you will be adding to the program will use several variables, so let's add them all now:

2. In the data division, add the following record:

   record
       ttChan,         i4                  ;;Terminal channel number
       length,         int                 ;;Length of a string
       tmpa,           a10                 ;;Temporary alpha variable
       logLevel,       int                 ;;Logging level.
       logFileName,    string              ;;Log file name
       dispatcher,     @MethodDispatcher   ;;Message dispatcher instance
   endrecord
   

Establish Exception Handling

If any code in this environment fails, we want to trap and log the exception, and exit gracefully. So we'll wrap everything in one big TRY/CATCH statement:

3. Add the following code to the procedure division:

   try
   begin
   
   end
   catch(ex, @Exception)
   begin
   
   end
   endtry
   

Open and Configure the Terminal Channel

Harmony Core will send us JSON-RPC request messages on STDIN, and expects us to respond by sending JSON-RPC response messages on STDOUT. In traditional Synergy, these are both represented by a terminal channel. We need to open the terminal, and configure the environment:

4. Add the following code in the TRY block of the TRY/CATCH statement:

   ;;Configure the environment and open the terminal chanel.
   ;; - STDIN  is the mechanism by which Harmony Core sends us requests
   ;; - STDOUT is the mechanism by which we will issue responses
   xcall flags(1907050020)
   open(ttChan=0,o,"TT:")
   

Configure and Initialize Logging

Although it is possible to debug both sides of a Traditional Bridge environment using Visual Studio, logging is always a valuable debugging tool, particularly in client/server environments. Traditional Bridge incorporates a comprehensive logging subsystem that is configurable to operate at six levels. Normal logging is considered to be level 2, and full verbose logging is achieved at level 6.

5. Add the following code, in the TRY body, below the code you just added:

   ;;Does the environment define the logging level?
   getlog("HARMONY_LOG_LEVEL", tmpa, length)
   if (length) then
   begin
       logLevel = %integer(tmpa)
   end
   else
   begin
       ;Levels are 1 to 6, 2 is normal logging, 6 is highest logging
       logLevel = 2
   end
        
   ;;Define the log file name
   logFileName = "BRIDGE_" + %string(%jbno) + ".LOG"
   
   ;;Initiate logging
   Logger.Instance = new Logger(logFileName, logLevel, false)
   

Configure and Start the Dispatcher

You're almost there, it's time to create an instance of the master dispatcher class and let it loose to do its work.

6. Add the following code, in the TRY body, below the logging code you just added:

   ;;Create a new instance of the main "dispatcher" class
   dispatcher = new MethodDispatcher()
        
   ;;Issue the "READY" message.
   ;;Harmony Core looks for this and considers the connection active when it sees it
   puts(ttChan, "READY" + %char(13)+ %char(10))
   
   ;;Start dispatching requests
   dispatcher.Dispatch(ttChan)
   

   As you can see, this is where the action happens. We create an instance of the MethodDispatcher class, we tell Harmony Core that we're ready to go, and we hand control over to the Dispatch method.

   From this point, we're out of the picture. The Traditional Bridge library code will take care of receiving requests, dispatching to routines, and issuing responses.

Log any unexpected exceptions

If anything goes wrong we should deal with it gracefully. That's what the CATCH block of the TRY/CATCH statement is for:

7. Add the following code to the CATCH block:

   ;;If anything failed, log an error if we can
   if (Logger.Instance != ^null)
   begin
       Logger.Instance.Log("DISPATCHER EXITED with exception" + ex.ToString())
   end
   

Close the Log File and STOP

There are two scenarios that can cause the program to terminate:

• The master dispatcher decides to exit from the Dispatch() method.
• An exception is trapped and logged.

In both cases, we should close the log file and terminate the application.

8. Add this code after the TRY/CATCH block, before the endmain compiler directive:

   ;;Close the log
   if (Logger.Instance != ^null)
   begin
       Logger.Instance.CloseLog()
   end
   
   stop
   

Build the Code

Before we move on, let's make sure the project builds:

9. Right-click on the TraditionalBridge project and select Build.

10. Check the Output window and verify that the build was successful.

    1>------ Build started: Project: TraditionalBridge, Configuration: Debug x64 ------
    ========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========
    

Run the Code

Let's also make sure the project runs. We can't actually make any requests right now, but we can make sure the host program starts, initializes, and reports that it is ready:

11. Right-click on the TraditionalBridge project and select Debug > Start New Instance.

You should see a DBR process start, and display the READY message:

---

Next topic: Add Helper Service Class

---