msghelp
Purpose
Issues help text.
Library
Run-time Services Library (librts.a)
Syntax
#include <msg00.h>
int msghelp (flags, compid, index [, fildes|)
unsigned int flags;
char *compid;
int index, fildes;
Description
The msghelp subroutine retrieves a predefined help
description from a message/insert/help file and then con-
structs and outputs the help text.
The flags parameter allows default help attributes to be
overridden. All flag bits for attributes you do not want
to override must be off. If no attributes are over-
ridden, the help is written to stderr. Attribute over-
ride flag bits that can be set are:
MSGFLFIL Writes the help text to the file specified by
the fildes parameter. If this flag is not
set, then the help text is written to stderr.
There is no specific flag bit defined for suppressing
output of the help ID. If you want to suppress the help
ID, do not specify the displayed component ID and dis-
played help ID fields of the help description in the
message/insert/help file. If the help ID is suppressed,
then the help text is aligned fildes parameter causes the
help text to be aligned at the left margin instead of to
the right of the help ID. This allows a full
79-character width, but does not provide component and
help IDs for referencing an explanation of the help in a
reference manual.
The compid parameter points to a six-character string
that identifies the message/insert/help file where the
help control information resides. 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 file specified
by the compid parameter. The index parameter is an
integer value from 1 to 999 and identifies which help
description in the file is to be used.
The fildes parameter is an integer file descriptor number
indicating the opened file to which the help is to be
sent. The fildes parameter is used only if the MSGFLFIL
flag is on.
Return Value
Upon successful completion, a value of 0 is returned. 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 The MSGFLTAB flag is on. Since helps cannot
reside in a message/insert table, this is not
a valid flag for the msghelp subroutine. 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_COMP The message/insert/help file specified by the
compid parameter cannot be found. 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.
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. Message Ser-
vices error message 090-002 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-002 is output
instead.
MSG_REFN The requested help description is found but
the description references another help
description (in the same file) as the source
of the text. The referenced help description
does not exist. 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.
One of the following values is returned when an attempt
to write to the file specified by the fildes parameter
fails:
-EBADF The fildes parameter does not specify a valid
file descriptor that is open for writing.
-EFBIG The file specified by the fildes parameter
exceeds the maximum file size or file size
limit for the process.
Related Information
In this book: "msgimed," "msgqued," "msgrtrv," and
"message."