cwbOBJ_GetSplFMsgAttr

Purpose

Retrieves an attribute of a message that's associated with a spooled file.

Syntax

 
unsigned int CWB_ENTRY  cwbOBJ_GetSplFMsgAttr(
                               cwbOBJ_ObjHandle  splFHandle,
                               cwbOBJ_KeyID      key,
                               void             *buffer,
                               unsigned long     bufLen,
                               unsigned long    *bytesNeeded,
                               cwbOBJ_DataType  *keyType,
                               cwbSV_ErrHandle   errorHandle);

Parameters

cwbOBJ_ObjHandle splFHandle - input

Handle of the spooled file.

cwbOBJ_KeyID key - input

Identifying key of the attribute to retrieve. The CWBOBJ_KEY_XXX constants define the key ids.

void *buffer - output

The buffer that will hold the attribute value, if this call returns successfully. The value of the key determines what type of data will be put into pBuffer. The type is also returned to the *keyType parameter, if provided.

unsigned long bufLen - input

The length of the buffer pointed to by pBuffer.

unsigned long *bytesNeeded - output

On output, this will be the number of bytes needed to hold result.

cwbOBJ_DataType *keyType - output

Optional, may be NULL. On output this will contain the type of data used to represent this attribute and what is stored at *buffer.

cwbSV_ErrHandle errorHandle - output

Optional, may be 0. Any returned messages will be written to this object. It is created with the cwbSV_CreateErrHandle() API. The messages may be retrieved through the cwbSV_GetErrText() API. If the parameter is set to zero, no messages will be retrievable.

Return Codes

The following list shows common return values.

CWB_NO_ERROR

Successful completion.

CWB_NOT_ENOUGH_MEMORY

Insufficient memory.

CWB_INVALID_HANDLE

Handle is not an allocated object handle.

CWB_BUFFER_OVERFLOW

Buffer too small.

CWBOBJ_RC_HOST_ERROR

Host error occurred. Text may be in errorHandle.

CWBOBJ_RC_INVALID_KEY

Key isn't valid.

CWBOBJ_RC_SPLFNOMESSAGE

The spooled file isn't waiting on a message.

CWB_API_ERROR

General API failure.

Usage

The following keys are valid:

CWBOBJ_KEY_MSGTEXT       -   Message text
CWBOBJ_KEY_MSGHELP       -   Message help text
CWBOBJ_KEY_MSGREPLY      -   Message reply
CWBOBJ_KEY_MSGTYPE       -   Message type
CWBOBJ_KEY_MSGID         -   Message ID
CWBOBJ_KEY_MSGSEV        -   Message severity
CWBOBJ_KEY_DATE          -   Message date
CWBOBJ_KEY_TIME          -   Message time

Message formatting characters will appear in the message text and should be used as follows:

&N

Force the text to a new line indented to column 2. If the text is longer than 1 line, the next lines should be indented to column 4 until the end of text or another format control character is found.

&P

Force the text to a new line indented to column 6. If the text is longer than 1 line, the next lines should be indented to column 4 until the end of text or another format control character is found.

&B

Force the text to a new line indented to column 4. If the text is longer than 1 line, the next lines should be indented to column 6 until the end of text or another format control character is found.