Tutorial 04 04 Add Traditional Bridge Routines

Tutorial 4: Adding Traditional Synergy Routines

The next step in the process is to add the traditional Synergy routines that you want exposed as endpoints. In your actual environment, you may have existing routines in existing libraries, in which case you would add references to those libraries in the TraditionalBridge project so that the Traditional Bridge host program (which we'll discuss later) would be linked against those libraries. For this tutorial, however, we'll add the code for sample routines directly in the TraditionalBridge project.

Add GetEnvironment.dbl

The first routine we will add has no parameters. It is a function that simply returns an alpha value. The return value is the output from the Synergy %versn function.

1. In Visual Studio Solution Explorer, right-click the Methods folder (TraditionalBridge\Source\Methods) and select Add > New Item from the context menu.

2. In the Add New Item dialog, select Code File. (If you don't see the Code File option in the Add New Item dialog, click Show All Templates to make this option visible.) Then set the name of the file to GetEnvironment.dbl and click Add.

3. Copy and paste the following code into the new source file:

   ;;*****************************************************************************
   ;;
   ;; Title:       GetEnvironment.dbl
   ;;
   ;; Description: An example routine for Traditional Bridge.
   ;;              Returns the Synergy DBL version number and operating system.
   ;;
   ;;*****************************************************************************
   
   function GetEnvironment, a
   proc
       freturn %versn
   endfunction
   

4. Save the file.

Add GetLogicalName.dbl

Now we'll add a second routine. This one is a little more complicated. It has an in parameter that is used to pass in the name of a logical. The return value of the function is the translation of that logical name in the traditional Synergy environment.

5. Right-click the Methods folder and select Add > New Item.

6. In the Add New Item dialog, select Code File, set the name of the file to GetLogicalName.dbl, and then click Add.

7. Copy and paste the following code into the new source file:

   ;;*****************************************************************************
   ;;
   ;; Title:       GetLogicalName.dbl
   ;;
   ;; Description: An example routine for Traditional Bridge.
   ;;              Returns the translation of a logical name.
   ;;
   ;;*****************************************************************************
   
   function GetLogicalName, a
       required in aLogicalName, a
       stack record
           translation,    a1024
           length,         i4
       endrecord
   proc
       xcall getlog(aLogicalName,translation,length)
   
       if (length)
           freturn translation(1:length)
    
       freturn ""
   
   endfunction
   

8. Save the file.

Add AddTwoNumbers.dbl

Now we'll add a routine with three parameters. The first two parameters are in parameters and are used to pass numeric values. The third parameter is an out parameter. The routine adds the values of the first two parameters and stores the resulting value in the third parameter.

9. Right-click the Methods folder and select Add > New Item.

10. In the Add New Item dialog, select Code File, set the name of the file to AddTwoNumbers.dbl, and then click Add.

11. Copy and paste the following code into the new source file:

    ;;*****************************************************************************
    ;;
    ;; Title:       AddTwoNumbers.dbl
    ;;
    ;; Description: An example routine for Traditional Bridge.
    ;;              Calculates and returns the sum of two numbers.
    ;;
    ;;*****************************************************************************
    
    subroutine AddTwoNumbers
        required in  number1, n
        required in  number2, n
        required out result,  n
    proc
        result = number1 + number2
        xreturn
    endsubroutine   
    

12. Save the file.

The Methods folder should now contain three files:

Add the BridgeMethods Interface

Now that we have traditional Synergy routines, we'll add the Synergy method catalog (SMC) definitions for those routines. The definitions are in the BridgeMethods interface in the SMC we added in Adding a Traditional Bridge Project, so we'll add that interface.

13. Open a Windows command prompt and navigate to the directory with the .sln file for your Harmony Core solution. Then enter the following command to open the Harmony Core GUI tool:

    harmonycore gui
    

14. When the "Loading Solution" message disappears, select Interfaces to open the Interfaces screen and then click Add interfaces in the status bar (at the very bottom of the Interfaces screen), or press CTRL+A.

15. In the "Add interfaces" dialog, select BridgeMethods (which is the only interface that will be available to select) and click OK. BridgeMethods will now be displayed on the Interfaces screen:

    

16. Select File > Save from the menu to save the setting you just added.

---

Next topic: Adding Dispatcher Classes for Routines

---