Description
Returns information about an object in a PowerBuilder library. Information includes comments, size of source, size of object, and modification time.
Syntax
INT PBORCA_LibraryEntryInformation ( HPBORCA hORCASession, LPTSTR lpszLibraryName, LPTSTR lpszEntryName, PBORCA_TYPE otEntryType, PPBORCA_ENTRYINFO pEntryInformationBlock );
|
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 for which you want information. |
|
lpszEntryName |
Pointer to a string whose value is the name of the object for which you want information. |
|
otEntryType |
A value of the PBORCA_TYPE enumerated data type specifying the object type of the entry. 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 |
|
pEntryInformationBlock |
Pointer to PBORCA_ENTRYINFO structure in which ORCA will store the requested information (see Usage below). |
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 |
Usage
You do not need to set the library list or current application before calling this function.
How entry information is returned
PBORCA_LibraryEntryInformation stores information about an entry in the following structure. You pass a pointer to the structure in the pEntryInformationBlock argument:
typedef struct PBORCA_EntryInfo
{
TCHAR szComments[PBORCA_MAXCOMMENT + 1];
LONG lCreateTime; // time of entry create-mod
LONG lObjectSize; // size of object in bytes
LONG lSourceSize; // size of source in bytes
} PBORCA_ENTRYINFO, FAR *PPBORCA_ENTRYINFO;Use for the source code size
PBORCA_LibraryEntryInformation is often used to estimate the size in bytes of the source buffer needed to obtain the export source of an object. The size of the exported source varies depending on the ConfigureSession settings in effect. The following table shows how ConfigureSession variables affect the lSourceSize value that LibraryEntryInformation returns:
|
ConfigureSession variable |
Effect on ISourceSize |
|---|---|
|
ANSI/DBCS ORCA client |
No effect. User should calculate required buffer size based on the usage tips that follow this table. |
|
eExportEncoding |
No effect. PBORCA_LibraryEntryInformation always returns the number of bytes required for Unicode source. |
|
bExportHeaders=TRUE |
If otEntryType is not PBORCA_BINARY, lSourceSize will be increased by the number of bytes needed to generate Unicode export headers. |
|
bExportIncludeBinary=TRUE |
If otEntryType is not PBORCA_BINARY, lSourceSize will be increased by the number of bytes needed to generate the Unicode representation of the binary object. |
Calculating buffer size needed for non-Unicode encodings
The size of the buffer required for non-Unicode export encodings cannot be calculated in advance without actually performing the data transformation. Developers should make their own estimate to arrive at a reasonable buffer size to allocate. For example, if the source for an entry is entirely ANSI, simply divide the lSourceSize value by 2 and add 1 byte if you want a null terminator. For Unicode source, add 2 bytes for the null terminator.
Using PBORCA_BINARY for entry type
In previous releases of ORCA, it was necessary to call PBORCA_LibraryEntryInformation a second time with an otEntryType of PBORCA_BINARY to determine if an entry contained embedded OLE controls. This call determined the size of the buffer needed to hold the representation of the binary data to be exported. Although PowerBuilder still supports this feature for backward compatibility, it is more efficient to set pConfigSession->bExportIncludBinary = TRUE to obtain a buffer size sufficient for both the source and binary components of an entry.
Examples
This example obtains information about each object in a PBL. It is an extension of the example for PBORCA_LibraryDirectory.
INT EntryInfo(PLIBINFO_HEAD pHead)
{
INT iErrCode;
INT idx;
PLIBINFO_ENTRY pCurrEntry;
PBORCA_ENTRYINFO InfoBlock;
INT iErrCount = 0;
for (idx = 0, pCurrEntry = pHead->pEntryAnchor;
(idx < pHead->iNumEntries) && pCurrEntry;
idx++, pCurrEntry = pCurrEntry->pNext)
{
iErrCode = PBORCA_LibraryEntryInformation(
lpORCA_Info->hORCASession pHead->szLibName,
pCurrEntry->szEntryName,
pCurrEntry->otEntryType, &InfoBlock);
if (iErrCode == PBORCA_OK)
{
pCurrEntry->lSourceSize = InfoBlock.lSourceSize;
pCurrEntry->lObjectSize = InfoBlock.lObjectSize;
}
else
{
ErrorMsg();
iErrCount++;
}
}
if (iErrCount)
iErrCode = -1;
return iErrCode;
}See also
