MSGIMED(3x,L) AIX Technical Reference MSGIMED(3x,L)
-------------------------------------------------------------------------------
msgimed
PURPOSE
Issues an immediate message.
LIBRARY
Run-time Services Library (librts.a)
SYNTAX
#include <msg00.h>
int msgimed (flags, compid, index [, sevcode [, errcode [, fildes]]])
unsigned int flags;
char *compid;
int index, sevcode, fildes;
long errcode;
DESCRIPTION
The msgimed subroutine retrieves a predefined message description from a
message/insert table or a message/insert/help file and then constructs the
message text and outputs it.
The flags parameter allows default message attributes to be overridden. All
flag bits for attributes you do not want to override must be off. If no
attributes are overridden, a message consisting of a message ID (if defined)
and message text is written to stderr. Attribute override flag bits that can
be set are:
MSGFLTAB Indicates that the compid parameter is a pointer to a
message/insert table instead of a pointer to a six-character
component ID identifying a message/insert/help file.
MSGFLTIM Includes with the message the time the message was issued. The
time is given in 24-hour format. This flag should always be set if
the error is logged.
MSGFLSEV Includes a severity code with the message. The severity code value
is specified by the sevcode parameter.
MSGFLERR Includes an error code with the message. The value of the error
code is specified by the errcode parameter.
MSGFLFIL Writes the message to the file specified by the fildes parameter.
If this flag is not set, then the message is written to stderr.
Processed November 7, 1990 MSGIMED(3x,L) 1
MSGIMED(3x,L) AIX Technical Reference MSGIMED(3x,L)
There is no specific flag bit defined for suppressing output of the message ID.
If you want to suppress the message ID, do not specify the displayed component
ID and the displayed message ID fields of the message description in the
message/insert table or the message/insert/help file. Suppression of the
message ID for a message output to stderr or to the output specified by the
fildes parameter causes the message to be aligned at the left margin instead of
to the right of the message ID. This allows a full 79-character width, but
does not provide component and message IDs for referencing an explanation of
the message in a reference manual.
The compid parameter is either a pointer to a message/insert table or
identifies the message/insert/help file. If the MSGFLTAB flag is set, then the
compid parameter is a pointer to a message/insert table where the message
description resides. If the MSGFLTAB flag is not set, then the compid
parameter identifies the message/insert/help file where the message description
resides. In this case, the compid parameter is either:
xxxccc For a component file, where, by convention:
xxx Identifies the software provider or product. IBM reserves the
use of the identifiers COM, com, SYc, syc, IBc, and ibc, where
c is any alphanumeric character.
ccc Identifies the particular software component.
common For the common message/insert/help file.
The index parameter is an index into the message/insert table or the
message/insert/help file specified by the compid parameter. The index
parameter is an integer value from 1 to 999 and identifies which message
description is to be used.
The sevcode parameter specifies an integer severity code that is output with
the message if the msgflerr flag is set. The following severity codes have
been defined:
MSGSVSYT System termination
MSGSVAPT Application termination
MSGSVOPR Operator-recoverable error
MSGSVAPR Application-recoverable error.
If the MSGFLSEV flag is not set, and if the errcode or fildes parameters are
specified, then a dummy sevcode parameter must be used as a place holder.
The errcode parameter is a long integer value that represents an error code
with six decimal digits. The error code is output with the message only if the
MSGFLERR flag is set. The two high-order decimal digits contain the origin
code; the four low-order digits contain an application-defined error return
code. The origin code is one of the following values:
MSGORIND Indeterminate origin.
MSGORVDD Reserved.
MSGORVCK Reserved.
Processed November 7, 1990 MSGIMED(3x,L) 2
MSGIMED(3x,L) AIX Technical Reference MSGIMED(3x,L)
MSGORVSV Reserved.
MSGORUDD Detected in AIX device driver.
MSGORUKN Detected in AIX kernel.
MSGORSHL Detected in shell command.
MSGORRTS Detected in run-time service or daemon.
MSGORAPP Detected in application above the application program interface.
If the MSGFLERR flag is not set, and if the fildes parameter is specified, then
a dummy errcode parameter must be used as a place holder.
The fildes parameter is a file descriptor indicating the opened file to which
the message is to be sent. The fildes parameter is used only if the msgflfil
flag is set.
RETURN VALUE
Upon successful completion, a value of 0 is returned. If the msgimed
subroutine fails, then it returns one of the following negative values.
The following values are defined in the msg04.h header file, which is included
by the msg00.h header file.
MSG_CPID The compid parameter is not six characters long. The request is
ignored.
MSG_INDX The index parameter is not in the range of 1 to 999. The request
is ignored.
MSG_ALLO The necessary Message Services work area cannot be allocated. The
request is ignored.
MSG_SREG A segment register is not available for mapping a
message/insert/help file. The request is ignored.
MSG_BADP The message/insert table pointer provided does not point to a
message/insert table. The request is ignored.
MSG_TABI The message/insert table that is provided does not contain the
requested message. The request is ignored.
MSG_COMP The message/insert/help file specified by the compid parameter
cannot be found. Message Services error message 090-001 is output
instead.
MSG_INVL The file specified by the compid parameter is not a valid
message/insert/help file. Message Services error message 090-001
is output instead.
MSG_MTCH The file specified by the compid parameter does not contain
descriptions for the specified component. The first six characters
of the component file name must be identical to the six-character
component ID that is specified in the file to the puttext command
Processed November 7, 1990 MSGIMED(3x,L) 3
MSGIMED(3x,L) AIX Technical Reference MSGIMED(3x,L)
when the component file was built. Message Services error message
090-001 is output instead.
MSG_NONE The correct component files are found, but none contain the message
description specified by the index parameter. Message Services
error message 090-001 is output instead.
MSG_REFN The requested message description is found but the description
references another message description (in the same file) as the
source of the text. The referenced message description does not
exist. Message Services error message 090-001 is output instead.
Note: Certain errors involve the failure of AIX system calls. In these cases,
the msghelp subroutine negates the error code that the system call
stored in errno and returns this value.
One of the following values is returned when an attempt to open a
message/insert/help file fails:
-EACCES Search permission is denied for a directory in the path prefix.
The request is ignored.
-ENOTDIR A component of the path prefix is not a directory. The request is
ignored.
-EMFILE Too many files are open for the process. The request is ignored.
One of the following values is returned when an attempt to write to the file
specified by the fildes parameter fails:
-EBADF Not a valid file descriptor open for writing.
-EFBIG The file exceeds the process's file size limit or the maximum file
size.
RELATED INFORMATION
In this book: "msghelp," "msgqued," "msgrtrv," and "message."
Processed November 7, 1990 MSGIMED(3x,L) 4