PBORCA_ObjectQueryHierarchy

Description

Queries a PowerBuilder object to get a list of the objects in its ancestor hierarchy. Only windows, menus, and user objects have an ancestor hierarchy that can be queried.

Syntax

INT PBORCA_ObjectQueryHierarchy ( HPBORCA hORCASession, 
   LPTSTR lpszLibraryName, 
   LPTSTR lpszEntryName, 
   PBORCA_TYPE otEntryType, 
   PBORCA_HIERPROC pHierarchyProc, 
   LPVOID pUserData );

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

lpszEntryName

Pointer to a string whose value is the name of the object being queried.

otEntryType

A value of the PBORCA_TYPE enumerated data type specifying the object type of the entry being queried. The only values allowed are:

PBORCA_WINDOW

PBORCA_MENU

PBORCA_USEROBJECT

pHierarchyProc

Pointer to the PBORCA_ObjectQueryHierarchy callback function. The callback function is called for each ancestor object.

The information ORCA passes to the callback function is the ancestor object name, stored in a structure of type PBORCA_HIERARCHY.

pUserData

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

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


Return value

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

-5      PBORCA_LIBLISTNOTSET

Library list not set

-6      PBORCA_LIBNOTINLIST

Library not in library list

-7      PBORCA_LIBIOERROR

Library I/O error

-9      PBORCA_INVALIDNAME

Name does not follow PowerBuilder naming rules


Usage

You must set the library list and current Application object before calling this function.

Examples

This example queries the window object w_processdata in the library WINDOWS.PBL to get a list of its ancestors. The lpUserData buffer was previously set up to point to space for storing the list of names.

For each ancestor in the object's hierarchy, PBORCA_ObjectQueryHierarchy calls the callback ObjectQueryHierarchy. In the code you write for ObjectQueryHierarchy, you store the ancestor name in the buffer pointed to by lpUserData. In the example, the lpUserData buffer has already been set up:

PBORCA_HIERPROC fpHierarchyProc;
fpHierarchyProc = (PBORCA_HIERPROC)GetHierarchy;
lpORCA_Info->lReturnCode = PBORCA_ObjectQueryHierarchy(
   _TEXT("c:\\app\\windows.pbl"),
   _TEXT("w_processdata"), 
   PBORCA_WINDOW,
   fpHierarchyProc, 
   lpUserData );

For more information about setting up the data buffer for the callback, see Content of a callback function and the example for PBORCA_LibraryDirectory.

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

See also

PBORCA_ObjectQueryReference