PBORCA_LibraryEntryInformation

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

PBORCA_LibraryDirectory

PBORCA_LibraryEntryExport