Sybase Technical Library - Product Manuals Home
[Search Forms] [Previous Section with Hits] [Next Section with Hits] [Clear Search] Expand Search

 About This Book [Table of Contents] Chapter 2:  ORCA Functions

ORCA Guide

[-] Chapter 1: Using ORCA

Chapter 1
Using ORCA

About this chapter

This chapter describes the Powersoft Open Library API (ORCA).

It explains the correspondence between tasks a PowerBuilder developer can do in the Library painter and tasks you want to do programmatically with ORCA for a PowerBuilder library.

It also explains the constraints involved in developing ORCA programs and who should and should not use ORCA, as well as the functions available in ORCA and how to conduct an ORCA session in your program.

What is ORCA?

ORCA is software for accessing the PowerBuilder Library Manager functions that PowerBuilder uses in the Library painter. A program (very often a C program) can use ORCA to do the same kinds of object and library management that the Library painter interface provides.

History of ORCA

ORCA was created for CASE tool vendors as part of the Powersoft CODE (Client/Server Open Development Environment) program. CASE tools needed programmatic access to PowerBuilder libraries to create and modify PowerBuilder objects based on an application design.

Typical ORCA programs

Applications use ORCA to manipulate PowerBuilder objects. They may:

Sample ORCA applications

ORCA has been used for many types of tools that work with PowerBuilder, such as:

What can ORCA do?

ORCA lets your application do programmatically the same library and object management tasks that a developer does in the PowerBuilder development environment. ORCA covers most of the functionality of the Library painter, and some of that of the Application and Project painters.

You can:

Who can run programs that call ORCA?

ORCA is available with the Enterprise and Professional editions of PowerBuilder. Users of these editions of PowerBuilder can run programs that use ORCA.

ORCA is not available with the Desktop edition of PowerBuilder. Desktop users cannot run programs that call ORCA.

Who can develop programs that call ORCA?

ORCA as a development tool is designed for tool vendors who want to provide tools for PowerBuilder developers. Tool vendors must be aware of the constraints described below.

ORCA as a development tool is not meant for a wider audience of PowerBuilder developers. If you are a PowerBuilder developer, you should not develop programs that call ORCA unless you understand and observe the constraints described next.

Constraints when using ORCA Both PowerBuilder and ORCA make use of the PowerBuilder compiler. However, the compiler is not reentrant and more than one program cannot use it simultaneously. Therefore, PowerBuilder cannot be running when your programs call ORCA.

Tool providers who use ORCA must code their programs carefully so that when a PowerBuilder developer calls their ORCA-based modules, their tool:

  1. Exits PowerBuilder.
  2. Performs the requested ORCA function.
  3. Restarts PowerBuilder.

If the PowerBuilder development environment is not shut down while ORCA is running, your PowerBuilder libraries can become corrupted. For this reason, casual use of ORCA is not recommended.

Installing ORCA

ORCA is available to developers using PowerBuilder Enterprise and PowerBuilder Professional on the Windows NT, Windows 95, Windows 3.1, and UNIX platforms.

To run ORCA programs

To run programs that use ORCA, you need the ORCA DLL (called PBORC60.DLL in PowerBuilder Version 6). When you install PowerBuilder, it is installed in the same directory with other PowerBuilder DLLs.

To develop ORCA programs

To develop C programs that use ORCA, you need several items, all on the PowerBuilder installation CD:

What you need

Where to find it on the PowerBuilder installation CD

This ORCA documentation

In \pb\orca

C development files (PBORCA.H and PBORCA.LIB)

For 16-bit Windows : in \orca\orca16

For 32-bit Windows : in \orca\orca32

Sample application An ORCA sample application is available that demonstrates all of the ORCA function calls in a C program with a user interface developed in PowerBuilder.

You can find the sample application on the Powersoft ftp site in \pub2\pbuilder\samples\

ORCA and the PowerBuilder Library painter

A PowerBuilder library (PBL) is a binary file. It stores objects you define in the PowerBuilder painters in two forms: source and compiled. The source for an object is text. The compiled form is binary and is not human-readable.

The Library painter lets the PowerBuilder developer view and maintain the contents of a PBL. The painter lists the objects in a PBL with their properties, such as modification date and comments.


In the Library painter, the PowerBuilder developer can delete, move, compile, export, and import objects--and can use source control systems and create PowerBuilder dynamic libraries and DLLs.

From the Library painter, you can open objects in their own painters and view and modify the objects graphically.

Objects in a PowerBuilder library

When you open an object in a painter, PowerBuilder interprets the library entries and displays the object in a graphical format. The painter does not display the source code. If you change the object graphically and save it again in the PBL, PowerBuilder rewrites the source code to incorporate the changes and recompiles the object.

Object source code

The Library painter lets you export source code, study and even modify it in any text editor, and import it back into the library. PowerBuilder compiles the imported object to check that the source code is valid. It will not import objects that fail to compile.

Source code exported to a file has two header lines before the source code. These header lines must not be included if you import the source using ORCA:

$PBExportComments$Tell us about the application level

You can view the exported source code in the PowerBuilder file editor:


Learning source code syntax

The syntax for object source code is not documented. The only way to learn what belongs in source code is by exporting objects and studying their source.

ORCA and source code

ORCA has an export function so it can examine and modify existing objects. The exported source is stored in a text buffer in the program. The ORCA source does not have the two header lines that the Library painter exports.

PowerBuilder commands and ORCA functions

Most ORCA functions have a counterpart in the Library painter, the Application painter, the Project painter, or the commands that start and stop a PowerBuilder session.

The next section identifies the ORCA functions, their purpose, and what they correspond to in the PowerBuilder development environment.

About ORCA functions

ORCA functions can be divided into six functional groups:

Functions for managing the ORCA session

Just as you begin a session in the PowerBuilder development environment by running PowerBuilder and you end the session by exiting PowerBuilder, you need to open a session when using ORCA and close the session when finished.

Library list and current application

In the PowerBuilder development environment, you must have a current application. You also set the library list search path if you plan to view or modify objects or create executables. Using ORCA, you have the same requirement, but the order is reversed. In ORCA, you set the library list then set the current application.

ORCA functions that don't involve compiling objects or building applications do not require a library list and current application. These are the library management functions and source control functions.

Session management

The session management functions (which all have the prefix PBORCA_) and their equivalents in the PowerBuilder development environment are:

Function (prefix PBORCA_)


Equivalent in PowerBuilder


Opens an ORCA session and returns the session handle

Starting PowerBuilder


Closes an ORCA session

Exiting PowerBuilder


Specifies the libraries for the session

Application painter: Entry>Properties, Libraries tab


Specifies the Application object for the session

Application painter: File>Open or New


Provides information about an error

No correspondence

Functions for managing PowerBuilder libraries

The library management functions are similar to commands in the Library painter. These functions allow you to create and delete libraries, modify library comments, and see the list of objects located within a library. They also allow you to examine objects within libraries, export their syntax, and copy, move, and delete entries.

These functions may be called outside the context of a library list and current application.

The library management functions (which all have the prefix PBORCA_) and their equivalents in the PowerBuilder Library painter are:

Function (prefix PBORCA_)


Equivalent in PowerBuilder


Modify the comments for a library



Create a new library file



Delete a library file



Get the library comments and a list of its objects

Main view


Copy an object from one library to another



Delete an object from a library



Get the source code for an object



Get details about an object

Main view


Move an object from one library to another


Functions for importing and compiling PowerBuilder objects

These functions allow you to import new objects into a library from a text listing of their source code and to compile entries that already exist in a library.

Entries in a library have both a source code representation and a compiled version. When you import a new object, PowerBuilder compiles it. If there are errors, it is not imported.

You must set the library list and current application before calling these functions.

The compilation functions (which all have the prefix PBORCA_) and their equivalents in the PowerBuilder Library painter are:

Function (prefix PBORCA_)


Equivalent in Library painter


Imports an object and compiles it



Imports a list of objects and compiles them

No correspondence


Compiles an object



Compiles all the objects in all the libraries associated with an application

Design>Incremental Rebuild or Design>Full Rebuild

Compilation functions are not the functions that create an executable from a library. See "Functions for creating executables and dynamic libraries" .

Functions for querying PowerBuilder objects

The object query functions get information about an object's ancestors and the objects it references.

The library list and current application must be set before calling these functions.

The object query functions (which all have the prefix PBORCA_) are listed below. There are no direct correspondences to PowerBuilder commands:

Function (prefix PBORCA_)



Gets a list of an object's ancestors


Gets a list of the objects an object refers to

Functions for creating executables and dynamic libraries

These functions allow you to create executables and PowerBuilder Dynamic Libraries (PBDs and DLLs). You can specify the same options for Pcode and machine code and tracing that you can specify in the Project painter.

Using ORCA, PBDs or DLLs must be created in a separate step from creating the executable.

The library list and current application must be set before calling these functions.

The functions for creating executables and libraries (which all have the prefix PBORCA_) and their equivalents in the PowerBuilder development environment are:

Function (prefix PBORCA_)


Equivalent in painter


Creates an executable application using ORCA's library list and current Application object

Project painter


Creates a PowerBuilder dynamic library from a PBL

Project painter or Library painter: Library>Build Runtime Library

Functions for implementing source control

The source control functions provide a way to check an object in to or out of a PowerBuilder library using PowerBuilder native source control. You can also find out an object's checkout status.

These functions allow you to implement version control using version control systems that don't have a PowerBuilder interface.

The library list and current application do not need to be set before calling these functions.

The source management functions (which all have the prefix PBORCA_) and their equivalents in the PowerBuilder Library painter are:

Function (prefix PBORCA_)


Equivalent in Library painter


Checks an object into a library

Source>Check In or Source>Clear Check Out Status


Checks an object out of a library

Source>Check Out


Reports objects that are registered or checked out

Source>View Check Out Status

About ORCA callback functions

Several ORCA functions require you to code a callback function. A callback function provides a way for the called program (the ORCA DLL or the Library Manager) to execute code in the calling program (the ORCA program executable).

How ORCA uses callbacks

ORCA uses callback functions when an unknown number of items need to be processed. The purpose of the callback function is to process each of the returned items, and in most cases return the information to the user.

Optional or required

Some callbacks handle errors that occur when the main work is being done--for example, when compiling objects or building executables. For handling errors, the callback function is optional. Other callbacks handle the information you wanted when you called the function--such as each item in a directory listing. Callbacks for information functions are required.

ORCA functions that use callbacks

These functions (which all have the prefix PBORCA_) use a callback function:

ORCA function call (prefix PBORCA_)

Purpose of callback




Called once for each compile error


Called once for each link error


Called once for each library entry name


Called once for every ancestor name


Called once for every object referenced in the entry


Called once for each object that is registered or checked out in a library

How a callback works

ORCA calls a callback function like this:

  1. The calling program allocates a buffer to hold data (the UserData buffer).
  2. The calling program calls an ORCA function, passing it pointers to the callback function and the UserData buffer.
  3. When the ORCA function needs to report information, it calls the callback function. It passes pointers to the structure holding the information and the UserData buffer.
  4. The callback function reads the information in the structure and formats it in the UserData buffer.Steps 3 and 4 repeat for each piece of information ORCA needs to report. An ORCA function may call the callback once, several times, or not at all, depending on whether errors occur or information needs to be reported.
  5. The ORCA function completes and returns control to the calling program, which reads the information in the UserData buffer.


Content of a callback function

The processing that occurs in the callback function is entirely up to you. This section illustrates a simple way of handling it.

UserData buffer

In this example, the UserData buffer is a structure with a field whose value points to the actual message buffer. Other fields keep track of the message buffer's contents as it is filled:

typedef struct ORCA_UserDataInfo {
LPSTR lpszBuffer; // Buffer to store data DWORD dwCallCount; // # of messages in buffer DWORD dwBufferSize; // size of buffer DWORD dwBufferOffset; // current offset in buffer } ORCA_USERDATAINFO, FAR *PORCA_USERDATAINFO;

Calling program

In the calling program, the UserDataInfo structure is initialized. The calling program does not know how much room will be required for messages, so it allocates 60000 bytes (an arbitrary size). If you are gathering link errors, it's probably enough. It might not be enough if you wanted directory information for a large library:

PORCA_USERDATAINFO lpUserDataBuffer;CHAR InfoBuffer[60000];

lpUserDataBuffer = &UserDataBuffer;

lpUserDataBuffer->dwCallCount = 0;lpUserDataBuffer->dwBufferOffset = 0;lpUserDataBuffer->dwBufferSize = 60000;lpUserDataBuffer->lpszBuffer = &InfoBuffer;

// Initialize all of InfoBuffer to 0memset(lpUserDataBuffer->lpszBuffer, 0x00, (size_t) lpUserDataBuffer->dwBufferSize);

Create Proc instance The calling program also needs to create a Proc instance of the callback function that it will pass to the ORCA function:

FARPROC lpCallbackProc;
lpCallbackProc = MakeProcInstance((FARPROC)CallbackFunc, hInst);

Call ORCA The calling program calls the ORCA function, passing the callback function pointer and the UserData buffer pointer. This example calls PBORCA_ExecutableCreate, whose callback type is PBORCA_LNKPROC:

rtn = PBORCA_ExecutableCreate(..., (PBORCA_LNKPROC) lpCallbackProc, lpUserDataBuffer);

Free Proc instance When control returns from ORCA back to the calling program, the calling program can free the Proc instance:


Process results Finally, the calling program can process or display information that the callback function stored in the UserData buffer.

Callback program

The callback program receives a structure with the current error or information and stores the information in the message buffer pointed to by lpszBuffer in the UserData buffer. It also manages the pointers stored in the UserData buffer.

Simple callback A simple callback might do the following:

This code implements a callback called LinkErrors for PBORCA_ExecutableCreate:

void WINAPI LinkErrors(PPBORCA_LINKERR lpLinkError,
LPVOID lpUserData)
{ PORCA_USERDATAINFO lpData; LPSTR lpCurrentPtr; int iNeededSize; lpData = (PORCA_USERDATAINFO) lpUserData;

// Keep track of number of link errors lpData->dwCallCount++;

// Is buffer already full? if (lpData->dwBufferOffset == lpData->dwBufferSize) return;

// How long is the new message? // Message length plus carriage rtn and newline iNeededSize = strlen(lpLinkError->lpszMessageText) + 2; // Set pointer for copying message to buffer lpCurrentPtr = lpData->lpszBuffer + lpData->dwBufferOffset;

// Check if there's room for the message // plus the final message if ((iNeededSize + strlen("Buffer full")) > (lpData->dwBufferSize - lpData->dwBufferOffset)) { // If almost full, copy final message // and set offset to end of buffer strcat(lpCurrentPtr, "Buffer full"); lpData->dwBufferOffset = lpData->dwBufferSize;

} else { // If not full, copy link error message, // CR and LF, and update offset strcat(lpCurrentPtr, lpLinkError->lpszMessageText); strcat(lpCurrentPtr, "\r\n"); lpData->dwBufferOffset += iNeededSize; } return;}

A more complex callback The ORCA sample application implements more elaborate buffer management. When the buffer is full, the callback allocates another, larger buffer, then copies the old data to the new buffer and adds the new message. It updates the pointer in the UserData buffer to the new message buffer. It also keeps track of handles to the buffers so that the globally allocated memory can be freed again.

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 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:

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:

nReturnCode WINAPI SetUpSession(HPBORCA hORCASession)
{ char szApplName[36]; int nReturnCode; LPSTR lpLibraryNames[2] =

// 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 strcpy(szApplName, "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 INFO 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.

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.

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.

 About This Book [Table of Contents] Chapter 2:  ORCA Functions