cwbSV_GetErrSubstTextIndexed

Use the cwbSV_GetErrSubstTextIndexed API with this product.

Purpose

Returns the message substitution data for the message identified by the index provided. This message attribute only pertains to IBM i returned messages. The substitution data is the data inserted into the substitution variable fields defined for the message.

Syntax

 
unsigned int CWB_ENTRY cwbSV_GetErrSubstTextIndexed(
                             cwbSV_ErrHandle  errorHandle,
                             unsigned long    index,
                             char            *substitutionData,
                             unsigned long    substitutionDataLength,
                             unsigned long   *returnLength);

Parameters

cwbSV_ErrHandle errorHandle - input: Handle that was returned by a previous call to the cwbSV_CreateErrHandle() API.
unsigned long index - input: Index value indicating which substitution data to return if multiple errors are associated with the error handle. The valid index range is from 1 to the number of messages contained in the error handle. The number of messages can be obtained by calling the cwbSV_GetErrCount() API.
char * substitutionData - input/output: Pointer to a buffer that will receive the substitution data stored in the error identified by the index. Note: The data returned is binary, hence it is NOT returned as an ASCIIZ string. Any character strings contained in the substitution data are returned as EBCDIC values.
unsigned long substitutionDataLength - input: Length of the receive buffer passed in. If the buffer is too small, the value will be truncated and CWB_BUFFER_OVERFLOW and returnLength will be set.
unsigned long * returnLength - input/output: Optional, may be NULL. A return address to store the number of bytes needed to hold the output data if the receive buffer is too small. It will also be set to the actual number of bytes of output data returned upon successful completion.

Return Codes

The following list shows common return values.

CWB_OK: Successful completion.
CWB_BUFFER_OVERFLOW: Output buffer too small, data truncated.
CWB_INVALID_POINTER: NULL passed on output parameter.
CWB_INVALID_HANDLE: Invalid handle.
CWBSV_NO_ERROR_MESSAGES: No messages are in the error handle.
CWBSV_ATTRIBUTE_NOT_SET: Attribute not set in current message.

Usage

IBM i messages may be added to the error handle when using the cwbRC_CallPgm() and cwbRC_RunCmd() API's. In these cases, you can use this API to retrieve the substitution data for the IBM i messages contained in the error handle. If there is no substitution data for the message, return code CWBSV_ATTRIBUTE_NOT_SET will be returned. An index value of 1 works with the lowest-level (i.e. oldest) message in the error handle. An index value equal to the count returned by the cwbSV_GetErrCount() API works with the top-level (i.e. most recent) message in the error handle. Index values less than 1 act as if 1 was passed in. Index values greater than the number of messages contained in the error handle act as if the returned count value from the cwbSV_GetErrCount() API was passed in. Use the returnLength parameter to determine the actual number of bytes returned in the substitution data when the return code is CWB_OK. The substitution data returned on this API could be used on a subsequent host retrieve message API call (QSYS/QMHRTVM) to retrieve the format of the substitution data or to return secondary help text with the substitution data added in. Host API's are called using the cwbRC_CallPgm() API.