To use the ORCA interface, your calling program will:
-
Open an ORCA session.
-
(Optional, depending on which ORCA functions you want to call.)
Set the library list and the current Application object.
-
Call other ORCA functions as needed.
-
Close the ORCA session.
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:
-
If the program only manages libraries, moves entries among libraries, or looks at the source for entries, there are no other required calls. You can continue with your ORCA session.
-
If the program calls other ORCA functions, you must set the library list and then set the current application.
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; }