About ORCA functions

All ORCA functions are external C functions that use the WINAPI macro to specify the calling convention of the function. On the Windows platform, WINAPI is defined as __stdcall.

About the code examples in this book

All ORCA functions may be called from either an ANSI client program or a Unicode client program. The code examples in this book use macros that are defined in the tchar.h file that is installed with PowerBuilder in the Shared/Appeon/PowerBuilder/cgen/h directory. If the /D _UNICODE compiler directive is set, these macros accept Unicode string arguments. If _UNICODE is not defined, these macros accept ANSI string arguments. This coding technique allows you to create ORCA programs that run successfully as either ANSI or Unicode clients.

ORCA functions can be divided into seven groups with the following functions:

  • Managing the ORCA session

  • Managing PowerBuilder libraries

  • Compiling PowerBuilder objects

  • Querying PowerBuilder objects

  • Creating executables and dynamic libraries

  • Managing source control operations involving PowerBuilder objects

Functions for managing the ORCA session

Just as you begin a session in the PowerBuilder development environment by running PowerBuilder and 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 first have a current application. You also set the library list search path if you plan to view or modify objects or create executables. ORCA has the same requirements, but in reverse order. In ORCA, you set the library list and then set the current application.

ORCA functions that do not involve compiling objects or building applications do not require a library list and current application. These are the library management functions. For source control functions, PBORCA_SccSetTarget implicitly sets the library list and current application.

Session management

Listed here are the session management functions (which all have the prefix PBORCA_), the purpose of each, and their equivalents in the PowerBuilder development environment:

Function (prefix PBORCA_)

Purpose

Equivalent in PowerBuilder

ConfigureSession

Sets session properties that affect the behavior of subsequent ORCA commands

Options

SessionOpen

Opens an ORCA session and returns the session handle

Starting PowerBuilder

SessionClose

Closes an ORCA session

Exiting PowerBuilder

SessionSetLibraryList

Specifies the libraries for the session

File>Library List

SessionSetCurrentAppl

Specifies the Application object for the session

File>Select Application

SessionGetError

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 can be called outside the context of a library list and current application.

Listed here are the library management functions (which all have the prefix PBORCA_), the purpose of each, and their equivalents in the PowerBuilder Library painter:

Function (prefix PBORCA_)

Purpose

Equivalent in PowerBuilder

LibraryCommentModify

Modify the comments for a library

Library>Properties

LibraryCreate

Create a new library file

Library>Create

LibraryDelete

Delete a library file

Library>Delete

LibraryDirectory

Get the library comments and a list of its objects

List view

LibraryEntryCopy

Copy an object from one library to another

Entry>Copy

LibraryEntryDelete

Delete an object from a library

Entry>Delete

LibraryEntryExport

Get the source code for an object

Entry>Export

LibraryEntryExportEx

Get the source code for an object

Entry>Export

LibraryEntryInformation

Get details about an object

List view

LibraryEntryMove

Move an object from one library to another

Entry>Move


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.

Listed here are the compilation functions (which all have the prefix PBORCA_), the purpose of each, and their equivalents in the PowerBuilder Library painter:

Function (prefix PBORCA_)

Purpose

Equivalent in Library painter

CompileEntryImport

Imports an object and compiles it

Entry>Import

CompileEntryImportList

Imports a list of objects and compiles them

No correspondence

CompileEntryRegenerate

Compiles an object

Entry>Regenerate

ApplicationRebuild

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.

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

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

Function (prefix PBORCA_)

Purpose

ObjectQueryHierarchy

Gets a list of an object's ancestors

ObjectQueryReference

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 before creating the executable.

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

Listed here are the functions for creating executables and libraries (which all have the prefix PBORCA_), the purpose of each, and their equivalents in the PowerBuilder development environment:

Function (prefix PBORCA_)

Purpose

Equivalent in painter

ExecutableCreate

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

Project painter

DynamicLibraryCreate

Creates a PowerBuilder dynamic library from a PBL

Project painter or Library painter: Library>Build Runtime Library

SetExeInfo

Sets additional file properties associated with the EXE and DLLs that are created

Project painter


Functions for deploying components to EAServer (Obsolete)

These functions are obsolete because EAServer is no longer supported since PowerBuilder 2017. An obsolete feature is no longer eligible for technical support and will no longer be enhanced, although it is still available.

These functions deploy an EAServer component using, or overwriting, specifications of the project object:

Function (prefix PBORCA_)

Purpose

BuildProject

Deploys component according to the project object specifications

BuildProjectEx

Overrides server name and port number when deploying component


Functions for managing source control operations

These functions allow you to perform source control operations involving PowerBuilder targets and objects:

Function (prefix PBORCA_)

Purpose

SccClose

Closes the active SCC Project

SccConnect

Initializes source control and opens a project

SccConnectOffline

Simulates a connection to source control

SccExcludeLibraryList

Names the libraries in the target library list that you do not want to be synchronized in the next PBORCA_SccRefreshTarget operation

SccGetConnectProperties

Returns the SCC connection properties associated with a PowerBuilder workspace

SccGetLatestVersion

Copies the latest version of objects from the SCC repository to the local project path

SccRefreshTarget

Refreshes the source for each of the objects in target libraries

SccSetPassword

Sets the password property prior to SccConnect

SccSetTarget

Retrieves the target file from source control, passes the application object name to ORCA, and sets the ORCA session library list