PBORCA_CompileEntryImportList

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

Argument

Description

hORCASession

Handle to previously established ORCA session.

*pLibraryNames

Pointer to an array of strings whose values are the file names of libraries into which you want to import the corresponding objects.

*pEntryNames

Pointer to an array of strings whose values are the names of objects to be imported into the corresponding libraries.

*otEntryTypes

Pointer to an array whose values are the object types of the library entries, expressed as enumerated data type PBORCA_TYPE. Values are:

PBORCA_APPLICATION

PBORCA_DATAWINDOW

PBORCA_FUNCTION

PBORCA_MENU

PBORCA_QUERY

PBORCA_STRUCTURE

PBORCA_USEROBJECT

PBORCA_WINDOW

PBORCA_PIPELINE

PBORCA_PROJECT

PBORCA_PROXYOBJECT

PBORCA_BINARY

*pComments

Pointer to an array of strings whose values are the comments for the corresponding objects.

*pEntrySyntaxBuffers

Pointer to an array of strings whose values are the source code for the corresponding objects.

*pEntrySyntaxBuffSizes

Pointer to an array of longs whose values are the lengths of the strings pointed to by *pEntrySyntaxBuffers

iNumberOfEntries

Number of entries to be imported, which is the same as the array length of all the array arguments.

pCompErrorProc

Pointer to the PBORCA_CompileEntryImportList callback function. The callback function is called for each error that occurs when imported objects are compiled.

The information ORCA passes to the callback function is error level, message number, message text, line number, and column number, stored in a structure of type PBORCA_COMPERR. The object name and script name are part of the message text.

If you don't want to use a callback function, set pCompErrorProc to 0.

pUserData

Pointer to user data to be passed to the PBORCA_CompileEntryImportList callback function.

The user data typically includes the buffer or a pointer to the buffer in which the callback function formats the error information as well as information about the size of the buffer.

If you are not using a callback function, set pUserData to 0.


Return value

INT. Typical return codes are:

Return code

Description

0       PBORCA_OK

Operation successful

-1      PBORCA_INVALIDPARMS

Invalid parameter list

-4      PBORCA_BADLIBRARY

Bad library name, library not found, or object couldn't be saved in the library

-6      PBORCA_LIBNOTINLIST

Library not in list

-7      PBORCA_LIBIOERROR

Library I/O error

-8      PBORCA_COMPERROR

Compile error

-9      PBORCA_INVALIDNAME

Name does not follow PowerBuilder naming rules

-13      PBORCA_CURRAPPLNOTSET

The current application has not been set


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.

Object dependencies

In the list of objects to be imported, put ancestor objects before their descendant objects so that the ancestors are imported first.

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.

Caution

When you import an entry with the same name as an existing entry, the old entry is deleted before the import takes place. If an import fails, the old object will already have been deleted.

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