ORCA Guide
ORCA Functions

Description

Exports the source code for a PowerBuilder library entry to a source buffer or file.

Syntax

INT PBORCA_LibraryEntryExport ( HPBORCA hORCASession, 
   LPTSTR lpszLibraryName, 
   LPTSTR lpszEntryName, 
   PBORCA_TYPE otEntryType, 
   LPTSTR lpszExportBuffer, 
   LONG lExportBufferSize );

Return value

INT. Typical return codes are:

Usage

You do not need to set the library list or current application before calling this function.

How the source code is returned

If pConfigSession->bExportCreateFile is FALSE, the object's source code is returned in the export buffer. If the bExportCreateFile property is TRUE, the source is written to a file in the directory pointed to by pConfigSession->pExportDirectory.

If pConfigSession->bExportHeaders is TRUE, ORCA writes the two export header lines to the beginning of the export buffer or file. The exported source code includes carriage return (hex 0D) and new line (hex 0A) characters at the end of each display line.

Source code encoding

PowerBuilder exports source in four different encoding formats. By default, ANSI/DBCS clients export source in PBORCA_ANSI_DBCS format; Unicode clients export source in PBORCA_UNICODE format. You can explicitly request an encoding format by setting pConfigSession->eExportEncoding.

Binary component

In PowerBuilder, you can explicitly request that the binary component of an object be included automatically in the export buffer or file by setting pConfigSession->eExportIncludeBinary = TRUE.

This is the recommended setting for new development. Because previous releases of ORCA did not support this feature, the old technique is still supported.

Size of source code

To find out the size of the source for an object before calling the export function, call the PBORCA_LibraryEntryInformation function first and use the pEntryInfo->lSourceSize information to calculate an appropriate lExportBufferSize value. lExportBufferSize is the size of lpszExportBuffer represented in bytes.

ORCA export processing performs all necessary data conversions before determining whether the allocated buffer is large enough to contain the export source. If not, it returns a PBORCA_BUFFERTOOSMALL return code. If lExportBufferSize is exactly the required length, PBORCA_LibraryEntryExport succeeds, but does not append a null terminator to the exported source. If lExportBufferSize is sufficiently large, ORCA appends a null terminator. Appeon recommends allocating a buffer sufficiently large to accommodate data conversions and a null terminator. lExportBufferSize is ignored if pConfigSession->bExportCreateFile = TRUE.

Determining the source size after data conversion and export

If you need to know the size of the actual buffer or file returned, you can call PBORCA_LibraryEntryExportEx instead of PBORCA_LibraryEntryExport. These functions behave exactly alike except that the PBORCA_LibraryEntryExportEx function signature includes an additional *plReturnSize argument.

Overwriting existing export files

The value of pConfigSession->eClobber determines whether existing export files are overwritten. If the export files do not exist, PBORCA_LibraryEntryExport returns PBORCA_OK regardless of the eClobber setting. The following table shows how the eClobber setting changes the action of PBORCA_LibraryEntryExport when export files already exist. A return value of PBORCA_OBJEXISTS means that the existing files were not overwritten.

Examples

This example exports a DataWindow named d_labels from the library SOURCE.PBL. It puts the PBORCA_UTF8 source code in a buffer called szEntrySource. Export headers are included:

TCHAR szEntrySource[60000];
// Indicate UTF8 source encoding
lpORCA_Info->pConfig->eExportEncoding = PBORCA_UTF8;
// Request export headers 
lpORCA_Info->pConfig->bExportHeaders = TRUE;
// Write output to memory buffer
lpORCA_Info->pConfig->bExportCreateFile = FALSE;
// Override existing session configuration
PBORCA_ConfigureSession(lpORCA_Info->hORCASession, 
lpORCA_Info->pConfig);
lpORCA_Info->lReturnCode = PBORCA_LibraryEntryExport(
lpORCA_Info->hORCASession,
   _TEXT("c:\\app\\source.pbl"),
   _TEXT("d_labels"), PBORCA_DATAWINDOW,
   (LPTSTR) szEntrySource, 60000);

This example exports a DataWindow named d_labels from the library SOURCE.PBL. It writes the PBORCA_UNICODE source code to c:\app\d_labels.srd. Export headers are included:

// Indicate UNICODE source encoding
lpORCA_Info->pConfig->eExportEncoding = PBORCA_UNICODE;
// Write to file
lpORCA_Info->pConfig->bExportCreateFile = TRUE;
// Specify output directory
lpORCA_Info->pConfig->pExportDirectory = _TEXT("c:\\app");
// Request export headers 
lpORCA_Info->pConfig->bExportHeaders = TRUE;
// Override existing session configuration
PBORCA_ConfigureSession(lpORCA_Info->hORCASession, 
lpORCA_Info->pConfig);
// Perform the actual export
lpORCA_Info->lReturnCode = PBORCA_LibraryEntryExport(
   lpORCA_Info->hORCASession,
   _TEXT("c:\\app\\source.pbl"),
   _TEXT("d_labels"), PBORCA_DATAWINDOW,
   NULL, 0);

This example exports a Window named w_connect from the library SOURCE.PBL. It contains an embedded OLE object. Both the source code and the binary object are exported to c:\app\w_connect.srw. Export headers are included and the source is written in PBORCA_ANSI_DBCS format:

// Indicate ANSI_DBCS source encoding
lpORCA_Info->pConfig->eExportEncoding = PBORCA_ANSI_DBCS;
// Export to a file
lpORCA_Info->pConfig->bExportCreateFile = TRUE;
// Specify output directory
lpORCA_Info->pConfig->pExportDirectory = _TEXT("c:\\app");
// Request export headers 
lpORCA_Info->pConfig->bExportHeaders = TRUE;
// Include binary component
lpORCA_Info->pConfig->bExportIncludeBinary = TRUE;
// Override existing session configuration
PBORCA_ConfigureSession(lpORCA_Info->hORCASession, 
lpORCA_Info->pConfig);
// Perform the actual export
lpORCA_Info->lReturnCode = PBORCA_LibraryEntryExport(
    lpORCA_Info->hORCASession,
    _TEXT("c:\\app\\source.pbl"),
    _TEXT("w_connect"), PBORCA_WINDOW,
    NULL, 0);

See also

PBORCA_ConfigureSession

PBORCA_CompileEntryImport

PBORCA_LibraryEntryExportEx