CWBSO_GetObjAttr

Purpose

Retrieves the value of an attribute from an object.

Syntax

 
unsigned int CWB_ENTRY CWBSO_GetObjAttr(
                CWBSO_OBJ_HANDLE objectHandle,          
                unsigned short usAttributeID,           
                char far* lpszBuffer,                   
                unsigned long ulBufferLength,           
                unsigned long far* lpulBytesNeeded,     
                CWBSO_ERR_HANDLE errorHandle);

Parameters

CWBSO_OBJ_HANDLE objectHandle - input

A handle to an object that was returned by a previous call to CWBSO_GetObjHandle or CWBSO_CopyObjHandle.

unsigned short usAttributeID - input

The identifier of the attribute to be retrieved. The valid values for this parameter depend on the type of object. See the appropriate header files for the valid values:

cwbsojob.h
cwbsomsg.h
cwbsoprt.h
cwbsosfl.h

char far* lpszBuffer - output

A long pointer to the output buffer where the attribute value will be placed. The value that is returned by this API is NOT a translated string. For instance, *END would be returned instead of Ending page for the ending page attribute of a spooled file. See SOA attribute special values for information on special values that may be returned for each type of object. The output buffer is not changed when the return code is not set to CWBSO_NO_ERROR.

unsigned long ulBufferLength - input

The size, in bytes, of the output buffer argument.

unsigned long far* lpulBytesNeeded - output

A long pointer to an unsigned long that will be set to the number of bytes needed to place the entire attribute value in the output buffer. When this value is less than or equal to the size of output buffer that is specified, the entire attribute value is placed in the output buffer. When this value is greater than the size of output buffer that is specified, the output buffer contains a null string. The output buffer is not changed beyond the bytes that are needed for the attribute value. This value is set to zero when the return code is not set to CWBSO_NO_ERROR.

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_OBJ_HANDLE: The object handle that is specified is not valid.
CWBSO_BAD_ERR_HANDLE: The error handle that is specified is not valid.
CWBSO_BAD_ATTRIBUTE_ID: The attribute key is not valid for this object.
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_GetObjHandle or CWBSO_CopyObjHandle must be called prior to calling this API. The object handle that is returned by CWBSO_GetObjHandle or CWBSO_CopyObjHandle 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.