snalu62_get_message(3) — Subroutines

Name

snalu62_get_message − Converts a status vector to a string containing the formatted text of all the status values contained in the status vector. A newline character separates one message text field from another. The returned string is null-terminated.

FORMAT

STATUS_RTN snalu62_get_message(
     STATUS_VEC status_vec,
     UINT32 format,
     UINT32 length,
     char ∗buffer,
     char ∗locale
     );

Arguments

status_vec

A pointer to a STATUS_VEC array to receive the completion status information.

format

A UINT32 mask specifying the format of the message strings that the interface places in the buffer. Message strings have the following format:

facility-severity-identifier, message-text

where:

severity@is the severity of the error:

S@Successful completion I@Informational message - no error occurred W@warning message - a minor error occurred E@error message - a major error occurred F@fatal error - an error occurred that
@prevents the program from continuing

identifier@is the message identifier. message-text@is the textual explanation for the message.

Form the mask value from zero or more of the following mask values:

•SNALU62_M_TEXT

•SNALU62_M_IDENTIFIER

•SNALU62_M_SEVERITY

•SNALU62_M_FACILITY

•SNALU62_M_ALL

length

A UINT32 value specifying the length of the supplied buffer parameter.

buffer

A pointer to a char buffer to receive the complete message string. The length parameter specifies the size of this buffer. The interface truncates the message string if the buffer is not long enough to receive the complete message string plus the null character (the interface always returns the string null-terminated).

locale

This parameter is a place holder. The functionality represented by this parameter is not implemented.

Description

The following example shows the string this verb returns when the transaction program passes a status vector containing an SNALU62-E-PARERR and SNALU62-E-INVPAR status:

In this example, the status vector contains:

     status_vec[0]: 0x00000006
              [1]: 0x02138282
              [2]: 0x00000001
              [3]: 0x00000005
              [4]: 0x02138112
              [5]: 0x00000001
              [6]: 0x0000006E

The transaction program calls the snalu62_get_message verb with the SNALU62_M_ALL option:

     status = snalu62_get_message(
                        status_vec,
                        SNALU62_M_ALL,
                        length,
                        buffer,
                        NULL
                        );

The interface translates the status vector into the following string (stored into the buffer parameter):

%SNALU62-E-PARERR, parameter error, routine snalu62_deallocate
-SNALU62-E-INVPAR, invalid value supplied for type parameter

where:

E@is the severity (enabled by SNALU62_M_SEVERITY) PARERR@is the identifier (enabled by SNALU62_M_IDENTIFIER) parameter error, ...@is the text (enabled by SNALU62_M_TEXT)

In cases where snalu62_get_message returns secondary error messages, a newline character (\n) is placed between each of the messages. The returned string is null terminated.

Return Values

SNALU62_S_OK
normal successful completion

SNALU62_S_OK_TRUNC
successful completion, message text was truncated

SNALU62_S_CONVCANC
conversation cancelled