MSGRTRV(3x,L) AIX Technical Reference MSGRTRV(3x,L)
-------------------------------------------------------------------------------
msgrtrv
PURPOSE
Retrieves a message, insert, or help text.
LIBRARY
Run-time Services Library (librts.a)
SYNTAX
#include <msg00.h>
int msgrtrv (flags, compid, index, buf, nbytes)
unsigned int flags, nbyte;
char *compid, *buf;
int index;
DESCRIPTION
The msgrtrv subroutine retrieves a predefined message, insert, or help
description from a message/insert/help file or a resident message/insert table,
and then constructs the message, insert, or help text as specified and returns
the text.
The flags parameter allows default attributes to be overridden. All flag bits
for attributes you do not want to override must not be set. If no attributes
are overridden, insert text is retrieved from a file. 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. The MSGFLTAB
flag should not be set if the MSGFLHLP flag is set because helps
reside only in a message/insert/help file, not in a message/insert
table.
MSGFLMSG Retrieves message text instead of insert text.
MSGFLHLP Retrieves help text instead of insert text.
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 or insert
description resides. If the MSGFLTAB flag is not set, then the compid
parameter identifies the message/insert/help file where the message, insert, or
help description resides. In this case, the compid parameter is either:
Processed November 7, 1990 MSGRTRV(3x,L) 1
MSGRTRV(3x,L) AIX Technical Reference MSGRTRV(3x,L)
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
message/insert/help file specified by the compid parameter. The index
parameter is an integer value from 1 to 999 and identifies which message,
insert, or help description in the file or table is to be used.
The buf parameter must be either a pointer to a buffer or a pointer to a
structure, depending on the value of the nbyte parameter.
o If the nbyte parameter is greater than 0, then buf parameter points to a
buffer where the message, insert, or help text is to be stored.
o If the nbyte parameter is equal to 0, then the buf parameter points to a
msg__rtrv structure provided by the requesting program. The msg__rtrv is
defined as a typedef in the msg05.h header file.
The nbyte parameter is either the size of the buffer pointed to by the buf
parameter, or 0. The buffer size should include space for a terminating null
character. If the nbyte parameter is 0, a buffer is allocated by the msgrtrv
subroutine. The buffer pointer (msgbufp in the msg05.h header file) returned
by the msgrtrv subroutine should always be inspected by the requesting program
after the returned text has been processed. If the inspection finds other than
a NULL buffer pointer, the buffer should be freed. This should be done
regardless of the value of the return code.
RETURN VALUE
Upon successful completion, a positive value is returned. If the msgrtrv
subroutine fails, it returns a negative value that indicates the reason why the
text could not be retrieved.
The value returned upon successful completion is the actual length of the
constructed text, not including the terminating null character. The following
should be noted concerning the length:
o If the nbyte parameter was 0 and help text with a title was retrieved, the
length returned is the sum of the title length and the text length,
including the null terminators after the title and the text.
o If the nbyte parameter was not 0, and the retrieved text is longer than the
buffer provided (minus 1 character for the null terminator), the excess
text is truncated. The length of the truncated text is included in the
length returned. If the return code value is greater than the length
Processed November 7, 1990 MSGRTRV(3x,L) 2
MSGRTRV(3x,L) AIX Technical Reference MSGRTRV(3x,L)
specified by the nbyte parameter minus 1, the following considerations
should be noted:
- The length of the text returned in the buffer is the length specified
by the nbyte parameter minus one instead of the return code value.
- The requesting program knows that the retrieved text had to be
truncated in order to fit into the buffer provided.
If the msghelp 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_TABP Both the msgfltab and msgflhlp flags are on. Since helps cannot
reside in a message/insert table, this is not a valid combination
of flag bits. 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 or insert. The request is ignored.
MSG_COMP The message/insert/help file specified by the compid parameter
cannot be found. If a message was specified, then Message Services
error message 090-001 is output instead. If an insert was
specified, then the request is ignored. If help text was
specified, then Message Services error message 090-002 is output
instead.
MSG_INVL The file specified by the compid parameter is not a valid
message/insert/help file. If a message was specified, then Message
Services error message 090-001 is output instead. If an insert was
specified, then the request is ignored. If help text was
specified, then Message Services error message 090-002 is output
instead.
Processed November 7, 1990 MSGRTRV(3x,L) 3
MSGRTRV(3x,L) AIX Technical Reference MSGRTRV(3x,L)
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 was specified in the file to the puttext command
when the component file was built. If a message was specified,
then Message Services error message 090-001 is output instead. If
an insert was specified, then the request is ignored. If help text
was specified, then Message Services error message 090-002 is
output instead.
MSG_NONE The correct component files are found, but none contain the
message, insert, or help description specified by the index
parameter. If a message was specified, then Message Services error
message 090-001 is output instead. If an insert was specified,
then the request is ignored. If help text was specified, then
Message Services error message 090-002 is output instead.
MSG_REFN The requested message, insert, or help description is found but the
description references another message, insert, or help description
(in the same file) as the source of the text. The referenced
message, insert, or help description does not exist. If a message
was specified, then Message Services error message 090-001 is
output instead. If an insert was specified, the request is
ignored. If help text was specified, then Message Services error
message 090-002 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 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.
RELATED INFORMATION
In this book: "msghelp," "msgimed," "msgqued," and "message."
Processed November 7, 1990 MSGRTRV(3x,L) 4