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 con-
structs the message, insert, or help text as specified
and returns the text.
The flags parameter allows default attributes to be over-
ridden. All flag bits for attributes you do not want to
override must not be set. If no attributes are over-
ridden, 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 param-
eter identifies the message/insert/help file where the
message, insert, or help 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 char-
acter.
ccc Identifies the particular software compo-
nent.
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 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.
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 was spec-
ified 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 Ser-
vices 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 ref-
erences 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."