MSGHELP(3x,L) AIX Technical Reference MSGHELP(3x,L)
-------------------------------------------------------------------------------
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 constructs 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 overridden, the help is written to stderr. Attribute override 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 displayed 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:
Processed November 7, 1990 MSGHELP(3x,L) 1
MSGHELP(3x,L) AIX Technical Reference MSGHELP(3x,L)
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 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 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
Processed November 7, 1990 MSGHELP(3x,L) 2
MSGHELP(3x,L) AIX Technical Reference MSGHELP(3x,L)
when the component file was built. Message Services error message
090-002 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-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."
Processed November 7, 1990 MSGHELP(3x,L) 3