CATGETMSG(3C)			UNICOS 10.0	      Last changed: 3-25-98

NAME    [Toc]    [Back]

     catgetmsg - Reads a message from a	message	catalog

SYNOPSIS    [Toc]    [Back]

     #include <nl_types.h>

     char *catgetmsg (nl_catd catd, int	set_num, int msg_num, char (*buf,
     int buflen);

IMPLEMENTATION    [Toc]    [Back]

     UNICOS systems

     IRIX systems

STANDARDS    [Toc]    [Back]

     CRI extension

DESCRIPTION    [Toc]    [Back]

     The catgetmsg function returns the	requested message string.  The
     message string is placed in the user-supplied buffer (pointed to by
     buf) and terminated with a	null byte.  If the message is longer than
     buflen bytes, it is truncated with	a null byte.

     The catd argument is a catalog descriptor returned	from an	earlier
     call to catopen(3C); it identifies	the message catalog that contains
     the message identified by the message set (set_num) and the message
     number (msg_num).

     The set_num and msg_num arguments are defined as integer values for
     maximum portability.  However, it is recommended that programmers use
     symbolic names for	message	and set	numbers	wherever possible, rather
     than having integer values	hard-coded into	their source programs.	The
     NL_MSGSET macro in	the nl_types.h file must be passed as the set_num
     argument.

NOTES    [Toc]    [Back]

     You can use the catgetmsg and catgets(3C) functions to retrieve
     messages from a message catalog.  On UNICOS systems, catgetmsg is
     optimized for programs that retrieve only a few messages, while
     catgets(3C) is optimized for programs that	retrieve many messages.	 On
     IRIX systems, catgetmsg and catgets have comparable performance.

     Specifically, catgetmsg minimizes memory usage at the expense of more
     frequent disk accesses.  The catgets(3C) function minimizes disk
     accesses at the expense of	more memory usage.  If it is important to
     your application to minimize usage	of one of these	resources, use the
     corresponding function.

RETURN VALUES    [Toc]    [Back]

     If	successful, catgetmsg returns a	pointer	to the message string in
     buf.

     If	catgetmsg is unsuccessful because the message catalog identified by
     catd is not currently available, or the requested message is not in
     the message catalog, a pointer to a null ("") string is returned.

SEE ALSO    [Toc]    [Back]

     catgets(3C), catmsgfmt(3C), catopen(3C) describe message system
     library functions

     caterr(1),	explain(1), gencat(1), whichcat(1) describe message system
     user commands in the UNICOS User Commands Reference Manual,
     publication SR-2011

     nl_types(5) describes the file that defines message system	variables
     for use in	programs in the	UNICOS File Formats and	Special	Files
     Reference Manual, publication SR-2014

     Cray Message System Programmer's Guide, publication SG-2121, contains
     details about all aspects of the message system

     UNICOS System Libraries Reference Manual, publication SR-2080, for	the
     printed version of	this man page.