Introduction

When SDK applications are launched from the Desktop, they are passed an object handle that they can use to create a session that exactly matches the session of the desktop that launched them. Further the desktop can manage these programs and for instance put up an error message if you try to close the Desktop while they are still running.

Quite a few people create programs that aren’t written using our SDK, but still are tightly integrated to Sage 300 ERP via one of our APIs such as the COM API, .Net API or Java API. You can add arbitrary EXE programs to the Desktop as icons and launch them just like any other screen.

When we designed the current UI framework, we had the intention that our UIs could be run from many places, such as VBA macros or hosted inside Internet Explorer. We also envisioned them being strung together in workflow type applications. Towards this we created the Session Manager and the Signon Manager to help tie together programs running inside the desktop with programs running outside the desktop. For information on using the Session Manager, check out this blog posting.

Generally this has worked quite well. Especially if you only signon to one company, then all the various things running will share the same session and you won’t have to signon to everything separately. However there are a few limitations to our current approach. If there are two desktops running (usually signed on to different companies) then when the external program is run, it has to present a dialog to choose which company’s session to use. This makes sense if you say start an EXE program from the start menu, since how would it know which desktop session to use? But when you run from the desktop you would expect it to just use that desktop’s session, rather than being treated like it wasn’t run from the desktop. Similarly if you started an EXE program from the desktop you would expect the Desktop to prevent closing until this program is closed, right now this check is only for SDK programs run from the desktop and doesn’t apply to anything else.

A lot of people are creating standalone EXE’s that use our APIs and they are using the Session Manager, which generally works well, but would like to get the other cases handled as nicely. So for the upcoming Sage 300 ERP 2014 release we have added some support to the Desktop to help with this. To basically allow non-SDK programs to start with the same protocol as the SDK programs so they can behave in the same manner. The alpha (developer) early release of Sage 300 ERP 2014 is available to ISVs so you can try this out now.

New Macro Substitution

If you add a program to a groupfile or if you add a program via file new in the desktop, if you specify $objecthandle$ as an argument, then this will be translated into an object handle when you are run that you can use in other API calls to get a session that matches your desktop. For instance in a group file:

[ PROGRAM ]
ID = "XX0500"
PARENT = "XX0000"
DESCRIPTION = "test ojbect key"
CMDLINE = "c:\\accpac6\\sm\\testobj\\testobj.exe $objecthandle$"
RSC = "XXSDK"

This is then the token you can use to create your session exactly from the Desktop that ran you.

If you aren’t an SDK program, you probably don’t have your own group file. However you can use a couple of SDK tools to add your item to an existing group file. The program unccgrp.exe (usually installed in c:\pluswdev\bin) will de-compile a group file (these are usually grp.dat files in a programs language folder, like ar62a\eng\grp.dat). Then you can add your own entries to this and then use ccgrp.exe to re-compile the group file. This is a bit of a kludge because it may overwritten by Product Updates and two people trying to do this at once may collide and interfere with each other. But it can be an effective and useful technique.

How to Use the Object Handle

You can then pass the object handle into a session init call and your session will be configured to match the desktop you are run from. Additionally if you want to register your windows handle, you can use the roto api to do so given the object handle. You should also clear this when you terminate.

Below is a VB program which does these things. It uses the session it gets to display the company name in a label. This way it will be connected to the right Desktop and the Desktop knows when it’s running.

Private Declare Sub rotoSetObjectWindow Lib "a4wroto.dll" (ByVal objectHandle As Long, ByVal hWnd As Long)
Dim strObjectHandle As String 

Private Sub Command1_Click()
   Unload Me
   '
   ' clear our window handle when closing so we don't block the desktop closing
   '
   rotoSetObjectWindow Val(strObjectHandle), 0
End Sub 

Private Sub Form_Load()
   Dim mSession As New AccpacCOMAPI.AccpacSession   

   '
   ' Get the object handle from the command line
   '
   strObjectHandle = Command$   

    MsgBox "Object Handle = " + strObjectHandle

    '
   ' Use the object handle to intialize the session. With this you will inherit
   ' an open session matching the desktop that launched you.
   '
   mSession.Init strObjectHandle, "XY", "XY1000", "62A"       

    '
   ' Set the window handle so the desktop can track whether you have closed
   ' effectively doing a roto openok.
   '
   rotoSetObjectWindow Val(strObjectHandle), Me.hWnd       

    Dim mDBLinkCmpRW As AccpacCOMAPI.AccpacDBLink
   Set mDBLinkCmpRW = mSession.OpenDBLink(DBLINK_COMPANY, DBLINK_FLG_READWRITE)   

    Dim CSCOM As AccpacCOMAPI.AccpacView
   Dim CSCOMFields As AccpacCOMAPI.AccpacViewFields
   mDBLinkCmpRW.OpenView "CS0001", CSCOM
   Set CSCOMFields = CSCOM.Fields   

    CSCOM.Fetch
   Label1.Caption = CSCOMFields("CONAME").Value   

End Sub