PBORCA_LibraryEntryExport

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

Argument

Description

hORCASession

Handle to previously established ORCA session.

lpszLibraryName

Pointer to a string whose value is the file name of the library containing the object you want to export.

lpszEntryName

Pointer to a string whose value is the name of the object being exported.

otEntryType

A value of the PBORCA_TYPE enumerated data type specifying the object type of the entry being exported. Values are:

PBORCA_APPLICATION

PBORCA_BINARY

PBORCA_DATAWINDOW

PBORCA_FUNCTION

PBORCA_MENU

PBORCA_PIPELINE

PBORCA_PROJECT

PBORCA_PROXYOBJECT

PBORCA_QUERY

PBORCA_STRUCTURE

PBORCA_USEROBJECT

PBORCA_WINDOW

lpszExportBuffer

Pointer to the data buffer in which ORCA stores the code for the exported source when the PBORCA_CONFIG_SESSION property bExportCreateFile is FALSE. This argument can be NULL if bExportCreateFile is TRUE.

lExportBufferSize

Size in bytes of lpszExportBuffer. This argument is not required if the PBORCA_CONFIG_SESSION property bExportCreateFile is TRUE.


Return value

INT. Typical return codes are:

Return code

Description

0       PBORCA_OK

Operation successful

-1      PBORCA_INVALIDPARMS

Invalid parameter list

-3      PBORCA_OBJNOTFOUND

Object not found

-4      PBORCA_BADLIBRARY

Bad library name

-7      PBORCA_LIBIOERROR

Library I/O error

-10  PBORCA_BUFFERTOOSMALL

Buffer size is too small

-33  PBORCA_DBCSERROR

Locale setting error when converting Unicode to ANSI_DBCS


Usage

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

Changes for PowerBuilder 10 and higher

In PowerBuilder 10 and higher, you can customize behavior of this function using PBORCA_CONFIG_SESSION variables. However, for backward compatibility, the default behavior has not changed.

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.

Denigrated technique

As in previous versions, after each PBORCA_LibraryEntryExport request, you can call PBORCA_LibraryEntryInformation with an otEntryType of PBORCA_BINARY. This function returns PBORCA_OK when binary data exists and you could make a second PBORCA_LibraryEntryExport call with otEntryType set to PBORCA_BINARY. For backward compatibility, setting otEntryType to PBORCA_BINARY causes the following configuration properties to be ignored: pConfigSession->bExportHeaders =TRUE and pConfigSession->bExportIncludeBinary = TRUE.

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.

PConfigSession->eClobber setting

Return value if read/write file exists

Return value if read-only file exists

PBORCA_NOCLOBBER

PBORCA_OBJEXISTS

PBORCA_OBJEXISTS

PBORCA_CLOBBER

PBORCA_OK

PBORCA_OBJEXISTS

PBORCA_CLOBBER_ALWAYS

PBORCA_OK

PBORCA_OK

PBORCA_CLOBBER_DECIDED_BY_SYSTEM

PBORCA_OBJEXISTS

PBORCA_OBJEXISTS


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