Writing ORCA programs

This section outlines the skeleton of an ORCA program, beginning with opening a session. It also describes how to build an application from scratch without having to start with a library containing an Application object.

Outline of an ORCA program

To use the ORCA interface, your calling program will:

  1. Open an ORCA session.

  2. (Optional, depending on which ORCA functions you want to call.)

    Set the library list and the current Application object.

  3. Call other ORCA functions as needed.

  4. Close the ORCA session.

First step: open a 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;
}

Optional step: set the library list and current application

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;
}

Next steps: continuing with the ORCA session

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.

Final step: close the session

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;
}

Bootstrapping a new application

Beginning with PowerBuilder 5.0, you can use ORCA to create the libraries for an entire application from object source code. You don't need to start with an existing PBL.

To import an object, ordinarily you need a library with an Application object that already exists. When you set the Application object to a NULL value during the bootstrap process, ORCA uses a temporary Application object so that you can import your own Application object. But your Application object doesn't become the current application until you close the session, start a new session, and set the current application.

To bootstrap a new application:

  1. Start an ORCA session using PBORCA_SessionOpen.

  2. Create the new library using PBORCA_LibraryCreate.

  3. Set the library list for the session to the new library using PBORCA_SessionSetLibraryList.

  4. Pass NULL variables as the library name and application name with PBORCA_SessionSetCurrentAppl.

  5. Import the Application object into the new library using PBORCA_CompileEntryImportList.

    Do not import other objects now

    Why you should import only the Application object

    Although you can import additional objects into the library, it is not a good idea. In the bootstrap session, the default Application object is the current application. If the objects have any dependencies on your Application object (for example, if they reference global variables), they will cause errors and fail to be imported.

  6. Close the session.

Finishing the bootstrapped application

The bootstrap process gets you started with the new application. To complete the process, you need to import the rest of the objects into one or more libraries.

You can only set the library list and current application once in a session, so you need to start a new ORCA session to finish the process. Since you now have a library with the Application object you want to use, the process is the same as any other ORCA session that imports objects.

To finish the bootstrapped application:

  1. Open another ORCA session.

  2. Create any additional libraries you'll need for the application.

  3. Set the library list to the library created in the bootstrap procedure plus the empty libraries just created.

  4. Set the current application to the Application object imported in the bootstrap procedure.

  5. Import objects into each of the libraries as needed.

When to create the libraries

You can create the additional libraries during the first bootstrap procedure. However, you should not import objects until the second procedure, when the correct Application object is current.