MSGHELP(3x,L) AIX Technical Reference MSGHELP(3x,L) ------------------------------------------------------------------------------- msghelp PURPOSE Issues help text. LIBRARY Run-time Services Library (librts.a) SYNTAX #include 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