CWBSO_GetObjHandle

Use the CWBSO_GetObjHandle API with this product.

Purpose

Gets a handle to an object in a list. The object handle that is returned by this API is valid until the list is closed or until the object handle is deleted. The object handle may be used to call the following APIs:

CWBSO_CopyObjHandle
CWBSO_DeleteObjHandle
CWBSO_DisplayObjAttr
CWBSO_GetObjAttr
CWBSO_RefreshObj
CWBSO_SetObjAttr
CWBSO_WaitForObj

Syntax

 
unsigned int CWB_ENTRY CWBSO_GetObjHandle(
                CWBSO_LIST_HANDLE listHandle,           
                unsigned long ulPosition,               
                CWBSO_OBJ_HANDLE far* lpObjectHandle,   
                CWBSO_ERR_HANDLE errorHandle);

Parameters

CWBSO_LIST_HANDLE listHandle - input: A handle to a list that is returned by a previous call to CWBSO_CreateListHandle or CWBSO_CreateListHandleEx.
unsigned long ulPosition - input: The position of the object within the list for which a handle is needed. NOTE: The first object in a list is considered position 0.
CWBSO_OBJ_HANDLE far* lpObjectHandle - output: A long pointer to a handle which is set to the handle for the IBM® i object. This handle may be used with any other API that accepts an object handle with the exception that some APIs only operate on specific types of objects.
CWBSO_ERR_HANDLE errorHandle - input: A handle to an error object. If an error occurs that there is error text for, this handle may be used to retrieve the error message and message help.

Return Codes

The following list shows common return values.

CWBSO_NO_ERROR: No error occurred.
CWBSO_BAD_LIST_HANDLE: The list handle that is specified is not valid.
CWBSO_BAD_ERR_HANDLE: The error handle that is specified is not valid.
CWBSO_BAD_LIST_POSITION: The position in list that is specified is not valid.
CWBSO_LOW_MEMORY: Not enough memory is available for the request.
CWBSO_ERROR_OCCURRED: An error occurred. Use error handle for more information.

Usage

CWBSO_CreateListHandle must be called prior to calling this API. The list handle that is returned by CWBSO_CreateListHandle must be passed as input to this API. CWBSO_CreateErrorHandle must be called prior to calling this API. The error handle that is returned by CWBSO_CreateErrorHandle must be passed as input to this API. The list must currently be open. The list is opened by calling CWBSO_OpenList. If CWBSO_CloseList is called to close a list, CWBSO_OpenList must be called again before this API can be called. You cannot access an object by using this API until that object has been included in the list. For example, if you issue this API to get the object in position 100 immediately after calling CWBSO_OpenList, the object may not immediately available. In such instances, use CWBSO_WaitForObj to wait until an object is available. The object handle that is returned by this API must be deleted by a subsequent call to CWBSO_DeleteObjHandle.