PBORCA_LibraryEntryExport
Description
Exports the source code for a PowerBuilder library entry to a source
buffer or file.
Syntax
|
1 2 3 4 5 6 |
INT PBORCA_LibraryEntryExport ( HPBORCA hORCASession, LPTSTR lpszLibraryName, LPTSTR lpszEntryName, PBORCA_TYPE otEntryType, LPTSTR lpszExportBuffer, LONG lExportBufferSize ); |
|
Argument |
Description |
|---|---|
|
hORCASession |
Handle to previously established ORCA |
|
lpszLibraryName |
Pointer to a string whose value is the file name of |
|
lpszEntryName |
Pointer to a string whose value is the name of the |
|
otEntryType |
A value of the PBORCA_TYPE enumerated data type 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 |
|
lExportBufferSize |
Size in bytes of lpszExportBuffer. This argument is |
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 |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
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:appd_labels.srd. Export headers are included:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
// 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:appw_connect.srw. Export headers are
included and the source is written in PBORCA_ANSI_DBCS format:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
// 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