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.

LIBRARY

/usr/shlib/libsnatprm.so

SYNOPSIS

#include <sna/snatprmdf.h>

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

Valid Conversation States

HDX: All

FDX: All

SUPPLIED PARAMETERS

status_vec

A pointer to a STATUS_VEC array specifying the completion status information that the interface should convert.

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:

•facility -- is the SNALU62 or SNA facility code.

•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.

locale

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

RETURNED 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).

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:

is the facility (enabled by SNALU62_M_FACILITY) T}
E@T{ is the severity (enabled by SNALU62_M_SEVERITY) T}
PARERR@T{ is the identifier (enabled by SNALU62_M_IDENTIFIER) T}
parameter error, ...@T{ is the text (enabled by SNALU62_M_TEXT) T}

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.

RESTRICTIONS

None

RETURN VALUES

SNALU62_S_OKnormal successful completion

SNALU62_S_OK_TRUNC
successful completion, message text was truncated

SNALU62_S_CONVCANC
conversation cancelled

SNALU62_S_OPENFAI
failed to open the interface’s message text file

ERRORS