PBORCA_LibraryDirectory

Description

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

Syntax

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

Argument

Description

hORCASession

Handle to previously established ORCA session.

lpszLibName

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

lpszLibComments

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

iCmntsBuffLen

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

pListProc

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.

pUserData

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

Description

0       PBORCA_OK

Operation successful

-1      PBORCA_INVALIDPARMS

Invalid parameter list

-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.

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

Examples

This example defines a linked list header:

typedef struct libinfo_head
{
   TCHAR      szLibName[PBORCA_SCC_PATH_LEN];
   TCHAR      szComments[PBORCA_MAXCOMMENT+1];
   INT        iNumEntries;
   PLIBINFO_ENTRY         pEntryAnchor;
   PLIBINFO_ENTRY         pLast;
} LIBINFO_HEAD, FAR *PLIBINFO_HEAD;

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;
} LIBINFO_ENTRY, FAR *PLIBINFO_ENTRY;
   
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, 
   sizeof(pHead->szComments));
pHead->iNumEntries = 0;
pHead->pEntryAnchor = NULL;
pHead->pLast = NULL;
lpORCA_Info->lReturnCode = PBORCA_LibraryDirectory(
   lpORCA_Info->hORCASession, 
   pHead->szLibName, 
   pHead->szComments, 
   (PBORCA_MAXCOMMENT+1), // specify length in TCHARs
   fpDirectoryProc, 
   pHead); 
// See PBORCA_LibraryEntryInformation example
if (lpORCA_Info->lReturnCode == PBORCA_OK)
   GetEntryInfo(pHead);  
CleanUp(pHead);
// CleanUp -  Release allocated memory
INT CleanUp(PLIBINFO_HEAD  pHead)
{
   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;
   pNewEntry = (PLIBINFO_ENTRY) new LIBINFO_ENTRY;
   memset(pNewEntry, 0x00, sizeof(LIBINFO_ENTRY));
   if (pHead->iNumEntries == 0)
   {
      pHead->pEntryAnchor = pNewEntry;
      pHead->pLast = pNewEntry;
   }
   else
   {
      pTemp = pHead->pLast;
      pTemp->pNext = pNewEntry;
      pHead->pLast = pNewEntry;
   }
   pHead->iNumEntries++;
   _tcscpy(pNewEntry->szEntryName, 
      pDirEntry->lpszEntryName);
   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

PBORCA_LibraryEntryInformation