msgqued
Purpose
Issues a queued message.
Library
Run-time Services Library (librts.a)
Syntax
#include <msg00.h>
int msgqued (flags, compid, index [, sevcode [, errcode||)
unsigned int flags;
char *compid;
int index, sevcode;
long errcode;
Description
The msgqued subroutine retrieves a predefined message
description from a message/insert table or a
message/insert/help file and then constructs the message
text and writes it to the queued message file, /qmsg.
The queued message file is installed with the AIX Oper-
ating System. After installation, you can change the
default size of the queued message file (six 2048-byte
blocks) by using an editor to modify the four-digit value
between the first two asterisks ("*") in the first line
of the file. This four-digit value is in units of
2048-byte blocks.
After /qmsg reaches the size specified in the first line,
each new message added to the queue overlays the oldest
message in the file. The message queue is maintained
across IPLs.
Queued messages are directed to the console operator and
are generally system type messages.
The flags parameter allows default message attributes to
be overridden. All flag bits for attributes you do not
want to override must not be set. If no attributes are
overridden, then the message consists of the message ID
(if defined), the message text, and the date and time the
message was issued. 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.
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
error code value must be specified by the
errcode parameter.
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 points to a message/insert
table where the message description resides. If the
MSGFLTAB flag is not set, the compid parameter identifies
the message/insert/help file where the message
description resides.
The index parameter is an index into the message/insert
table or 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 in the
file is to be used.
The sevcode parameter specifies an integer severity code
that is written 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
parameter is 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
possible values for the origin code are listed in the
description. The origin code is one of the following
values:
MSGORIND Indeterminate origin.
MSGORVDD Detected in VRM. Indicates a device driver
level failure.
MSGORVCK Detected in VRM. Indicates a check parameter
detected failure in VRM.
MSGORVSV Detected in VRM. Indicates an SVC handler
detected failure in VRM.
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.
Return Value
Upon successful completion, a value of 0 is returned. If
the msgqued 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 msgqued request is ignored.
MSG_INDX The index parameter is not in the range of 1
to 999. The msgqued request is ignored.
MSG_ALLO The necessary Message Services work area
cannot be allocated. The msgqued request is
ignored.
MSG_SREG A segment register is not available for
mapping a message/insert/help file. The
msgqued request is ignored.
MSG_BADP The message/insert table pointer provided
does not point to a message/insert table.
The msgqued request is ignored.
MSG_TABI The message/insert table that is provided
does not contain the requested message. The
msgqued 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 speci-
fied component. The first six characters of
the component file name must be identical to
the six-character component ID that is speci-
fied in the file to the puttext command when
the component file was built. Message Ser-
vices error message 090-001 is output
instead.
MSG_NONE The correct component files are found, but
none contain the message description speci-
fied by the index parameter. Message Ser-
vices 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.
MSG_EXEC The fork or exec system call failed while
attempting to run the program that updates
the queued message file. The msgqued request
is ignored. The failure of exec is not
detected if the calling process catches the
SIGCLD signal. See "signal" about catching
signals and "Special Signals" about the
special handling of SIGCLD.
MSG_QMSG The queued message file, /qmsg, cannot be
opened, or its format is not valid. The
msgqued request is ignored. This condition
is not detected if the calling process
catches the SIGCLD signal. See "signal"
about catching signals and "Special Signals"
about the special handling of SIGCLD.
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 of the message/insert/help
file.
-ENOTDIR A component of the path name of the
message/insert/help file is not a directory.
-EMFILE Too many files are open for the process.
File
/qmsg
Related Information
In this book: "msghelp," "msgimed," "msgrtrv," and
"message."