Reports information about the directory of a PowerBuilder library, including the list of objects in the directory.


INT PBORCA_LibraryDirectory ( HPBORCA hORCASession, 
   LPTSTR lpszLibName, 
   LPTSTR lpszLibComments, 
   INT iCmntsBuffLen, 
   LPVOID pUserData );




Handle to previously established ORCA session.


Pointer to a string whose value is the file name of the library for which you want directory information.


Pointer to a buffer in which ORCA will put comments stored with the library.


Length of the buffer (specified in TCHARs) pointed to by lpszLibComments. The recommended length is PBORCA_MAXCOMMENTS + 1.


Pointer to the PBORCA_LibraryDirectory callback function. The callback function is called for each entry in the library.

The information ORCA passes to the callback function is entry name, comments, size of entry, and modification time, stored in a structure of type PBORCA_DIRENTRY.


Pointer to user data to be passed to the PBORCA_LibraryDirectory callback function.

The user data typically includes the buffer or a pointer to the buffer in which the callback function formats the directory information as well as information about the size of the buffer.

Return value

INT. Typical return codes are:

Return code


0       PBORCA_OK

Operation successful


Invalid parameter list


Bad library name


Library I/O error


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

Comments for the library

PBORCA_LibraryDirectory puts the library comments in the string pointed to by lpszLibComments. The callback function can store comments for individual objects in the UserData buffer.

Information about library entries

The information you get back about the individual entries in the library depends on the processing you provide in the callback function. ORCA passes information to the callback function about a library entry in the structure PBORCA_DIRENTRY. The callback function can examine that structure and store any information it wants in the buffer pointed to by pUserData.

When you call PBORCA_LibraryDirectory, you do not know how many entries there are in the library. There are two approaches you can take:

  • Allocate a reasonably sized block of memory and reallocate the buffer if it overflows (illustrated in About ORCA callback functions).

  • Let lpUserDataBuffer point to the head of a linked list. For each PBORCA_DIRENTRY returned, dynamically allocate a new list entry to capture the required information (illustrated in the example that follows).


This example defines a linked list header:

typedef struct libinfo_head
   TCHAR      szComments[PBORCA_MAXCOMMENT+1];
   INT        iNumEntries;
   PLIBINFO_ENTRY         pEntryAnchor;
   PLIBINFO_ENTRY         pLast;

Each invocation of the DirectoryProc callback function allocates a new linked list entry, defined as follows:

typedef struct libinfo_entry
   TCHAR     szEntryName[41];
   LONG   lEntrySize; 
   LONG      lObjectSize;
   LONG      lSourceSize;
   PBORCA_TYPE     otEntryType;
   libinfo_entry  *   pNext;
PBORCA_LISTPROC         fpDirectoryProc;
PLIBINFO_HEAD        pHead;
fpDirectoryProc    = (PBORCA_LISTPROC) DirectoryProc;
pHead = new LIBINFO_HEAD;
_tcscpy(pHead->szLibName, _TEXT("c:\\myapp\test.pbl");
memset(pHead->szComments, 0x00, 
pHead->iNumEntries = 0;
pHead->pEntryAnchor = NULL;
pHead->pLast = NULL;
lpORCA_Info->lReturnCode = PBORCA_LibraryDirectory(
   (PBORCA_MAXCOMMENT+1), // specify length in TCHARs
// See PBORCA_LibraryEntryInformation example
if (lpORCA_Info->lReturnCode == PBORCA_OK)
// CleanUp -  Release allocated memory
   INT      iErrCode = PBORCA_OK;
   PLIBINFO_ENTRY         pCurrEntry;
   PLIBINFO_ENTRY         pNext;
   INT      idx;
for (idx = 0, pCurrEntry = pHead->pEntryAnchor; 
   (idx < pHead->iNumEntries) && pCurrEntry; idx++)
   pNext = pCurrEntry->pNext;
   delete pCurrEntry;
   if (pNext)
       pCurrEntry = pNext;
   else pCurrEntry = NULL;
delete pHead;
return iErrCode;
// Callback procedure used by PBORCA_LibraryDirectory
void __stdcall DirectoryProc(PBORCA_DIRENTRY
     *pDirEntry, LPVOID lpUserData)
   PLIBINFO_HEAD      pHead;
   PLIBINFO_ENTRY      pNewEntry;
   PLIBINFO_ENTRY      pTemp;
   pHead = (PLIBINFO_HEAD) lpUserData;
   memset(pNewEntry, 0x00, sizeof(LIBINFO_ENTRY));
   if (pHead->iNumEntries == 0)
      pHead->pEntryAnchor = pNewEntry;
      pHead->pLast = pNewEntry;
      pTemp = pHead->pLast;
      pTemp->pNext = pNewEntry;
      pHead->pLast = pNewEntry;
   pNewEntry->lEntrySize = pDirEntry->lEntrySize;
   pNewEntry->otEntryType = pDirEntry->otEntryType;

In these examples, session information is saved in the data structure ORCA_Info, shown in About the examples.

See also