CWBSO_GetObjHandle

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 will be set to the handle for the iSeries™ 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.