ORCA Guide
Writing ORCA programs

Before calling any other ORCA functions, you need to open a session. The PBORCA_SessionOpen function returns a handle that ORCA uses to manage this program's ORCA session. The handle type HPBORCA is defined as LPVOID, meaning that it can be a pointer to any type of data. This is because within ORCA it is mapped to a structure not available to the calling program.

Sample code

This sample C function opens an ORCA session:

HPBORCA WINAPI SessionOpen()
{
   HPBORCA hORCASession;
   hORCASession = PBORCA_SessionOpen();
   return hORCASession;
}

The next step in writing an ORCA program depends on the intent of the program. The choices are:

Comparison to PowerBuilder

This is similar to the requirements of the PowerBuilder development environment. In the Library painter, you can copy entries from one PBL to another, even if they are outside the current application or library list. You can export the syntax of a library entry that is not in the library list. However, you can only import entries into libraries in the current application's library list.

In the PowerBuilder development environment, you select an Application object in the Application painter and then set the library search path on the Application object's property sheet. With ORCA, you set the library list first and then set the Application object.

Set once per session

You can set the library list and current application only once in an ORCA session. To use another library list and application, close the ORCA session and open a new session.

Sample code

This sample C function sets the library list and the current application:

int WINAPI SetUpSession(HPBORCA hORCASession)
{
   TCHAR szApplName[36];
   int nReturnCode;
   LPTSTR lpLibraryNames[2] = 
    {_TEXT("c:\\pbfiles\\demo\\master.pbl"),
     _TEXT("c:\\pbfiles\\demo\\work.pbl")};
 
   // Call the ORCA function
   nReturnCode = PBORCA_SessionSetLibraryList(
      hORCASession, lpLibraryNames, 2);
   if (nReturnCode != 0)
   return nReturnCode;  // return if it failed
 
   // Set up the string containing the appl name
   _tcscpy(szApplName, _TEXT("demo"));
 
   // The appl object is in the first library
   nReturnCode = PBORCA_SessionSetCurrentAppl(
     hORCASession, lpLibraryName[0], szApplName))
   return nReturnCode;
}

After the library list and application are set, you can call any ORCA function using the handle returned by the PBORCA_SessionOpen function. Most of the function calls are fairly straightforward. Others, like those requiring callbacks, are a bit more complicated.

For information about callback functions, see About ORCA callback functions.

The last step in an ORCA program is to close the session. This allows the Library Manager to clean up and free all resources associated with the session.

This sample C function closes the session:

void    WINAPI SessionClose(hORCASession)
{
   PBORCA_SessionClose(hORCASession);
   return;
}