ORCA Guide
ORCA Functions

Description

Imports the source code for a list of PowerBuilder objects into libraries and compiles them. The name of each object to be imported is held in an array. Other arrays hold the destination library, object type, comments, and source code. The arrays must have an element for every object.

Syntax

INT PBORCA_CompileEntryImportList ( PBORCA hORCASession, 
   LPTSTR far *pLibraryNames,
   LPTSTR far *pEntryNames, 
   PBORCA_TYPE far *otEntryTypes, 
   LPTSTR far *pComments, 
   LPTSTR far *pEntrySyntaxBuffers,
   LONG far *pEntrySyntaxBuffSizes,
   INT iNumberOfEntries, 
   PBORCA_ERRPROC pCompErrorProc,
   LPVOID pUserData );

Return value

INT. Typical return codes are:

Usage

You must set the library list and current Application object before calling this function.

PBORCA_CompileEntryImportList is useful for importing several interrelated objects -- for example, a window, its menu, and perhaps a user object that it uses.

How imported objects are processed

ORCA imports all the objects in the list, compiling each object type definition. If no errors occur, then ORCA compiles all the objects in all the listed libraries.

In the list of objects, put a user object before objects that refer to that user object so that the referenced object is imported first.

If objects refer to each other, call PBORCA_ApplicationRebuild to get an error-free compilation.

Populating the information arrays for imported objects

The information for each imported object is contained in several parallel arrays. For example, if a DataWindow named d_labels is the third element in the object name array (subscript 2), then a pointer to the name of its destination library is the third element in the library name array; its object type is the third element in the object type array; and the pointer to its source code buffer is the third element in the syntax buffer array.

Using PBORCA_BINARY to specify entry type

This value of the PBORCA_TYPE enumerated data type should be used when importing or exporting entries that contain embedded binary information such as OLE objects. The binary information is imported from a buffer previously filled on export with the hexascii representation of the binary data.

For sample code demonstrating using PBORCA_BINARY on import, see Examples.

When errors occur

When errors occur during importing, the object is brought into the library but may need editing. An object with minor errors can be opened in its painter for editing. If the errors are severe enough, the object can fail to open in the painter, and you will have to export the object, fix the source code, and import it again. If errors are due to the order in which the objects are compiled, you can call the PBORCA_ApplicationRebuild function after all the objects are imported.

Processing errors in the callback function

For each error that occurs during compiling, ORCA calls the callback function pointed to in pCompErrorProc. How that error information is returned to your calling program depends on the processing you provide in the callback function. ORCA passes information to the callback function about an error in the structure PBORCA_COMPERR. The callback function can examine that structure and store any information it wants in the buffer pointed to by pUserData.

Because you do not know how many errors will occur, it is hard to predict the size of the pUserData buffer. It is up to your callback function to keep track of the available space in the buffer.

Examples

This example builds the arrays required to import three objects into two libraries (the example assumes that source code for the objects has already been set up in the variables szWindow1, szWindow2, and szMenu1) and imports the objects.

Each time an error occurs, PBORCA_CompileEntryImportList calls the callback CompileEntryErrors. In the code you write for CompileEntryErrors, you store the error messages in the buffer pointed to by lpUserData. In the example, the lpUserData buffer has already been set up:

LPTSTR lpLibraryNames[3];
LPTSTR lpObjectNames[3];
PBORCA_TYPE ObjectTypes[3];
LPTSTR lpObjComments[3];
LPTSTR lpSourceBuffers[3];
long BuffSizes[3];
PBORCA_ERRPROC fpError;
int nReturnCode;
 
fpError = (PBORCA_ERRPROC) ErrorProc;
// Indicate Unicode source encoding
lpORCA_Info->pConfig->eImportEncoding = PBORCA_UNICODE;
PBORCA_ConfigureSession(lpORCA_Info->hORCASession, 
   lpORCA_Info->pConfig);
 
// specify the library names 
lpLibraryNames[0] = 
   _TEXT("c:\\appeon\\pb2019\\demo\\windows.pbl");
lpLibraryNames[1] = 
   _TEXT("c:\\appeon\\pb2019\\demo\\windows.pbl");
lpLibraryNames[2] = 
   _TEXT("c:\\appeon\\pb2019\\demo\\menus.pbl");
 
// specify the object names
lpObjectNames[0] = _TEXT("w_ancestor");
lpObjectNames[1] = _TEXT("w_descendant");
lpObjectNames[2] = _TEXT("m_actionmenu");
 
// set up object type array
ObjectTypes[0] = PBORCA_WINDOW;
ObjectTypes[1] = PBORCA_WINDOW;
ObjectTypes[2] = PBORCA_MENU;
 
// specify object comments 
lpObjComments[0] = _TEXT("Ancestor window");
lpObjComments[1] = _TEXT("descendant window");
lpObjComments[2] = _TEXT("Action menu");
 
// set pointers to source code
lpSourceBuffers[0] = (LPTSTR) szWindow1;
lpSourceBuffers[1] = (LPTSTR) szWindow2;
lpSourceBuffers[2] = (LPTSTR) szMenu1;
 
// Set up source code lengths array
BuffSizes[0] = _tcslen(szWindow1)*2;
    //Unicode source buffer
BuffSizes[1] = _tcslen(szWindow2)*2;
    //Size is always in bytes
BuffSizes[2] = _tcslen(szMenu1)*2;
 
nReturnCode = PBORCA_CompileEntryImportList(
   lpORCA_Info->hORCASession,
   lpLibraryNames, lpObjectNames, ObjectTypes,
   lpObjComments, lpSourceBuffers, BuffSizes, 3,
   fpError, lpUserData );

For more information about setting up the data buffer for the callback, see Content of a callback function and the example for PBORCA_LibraryDirectory.

In these examples, session information is saved in the data structure ORCA_Info, shown in About the examples.

See also

PBORCA_LibraryEntryExport

PBORCA_CompileEntryImport

PBORCA_CompileEntryRegenerate

PBORCA_ApplicationRebuild