c_lasmsg - Print a standard LAS message to the terminal

SYNTAX

#include "las.h"

FUNCTION c_lasmsg (fatalflg, msgkey, format, ...)

     long fatalflg;
     char *msgkey;
     char *format;
     ...


PARAMETERS

fatalflg (input, long)

Flag indicating if the message is a fatal message. A nonzero value (TRUE) indicates a fatal message. The specified message will be printed to the terminal followed by a standard LAS fatal error message. The program will terminate.

A value of zero (FALSE) indicates a nonfatal message. The specified message will be printed to the terminal and the function will complete successfully.

msgkey (input, character, length (*))

LAS message key. This string will be enclosed in square brackets at the beginning of the line and should be no more than 17 characters in length. If msgkey is an empty string ("") or if it contains nothing but spaces, a key of "informational" will be printed. Standard message keys are of the form FUNC-KEY, where FUNC is the name of the function and KEY is a unique key.

format (input, character, length(*))

Message format like that passed to the C function, printf(). If any '%' format specifiers are included in format, an additional argument must be supplied to the function for each specifier. Please see the manual pages for printf().

The maximum length of the message must be less than 1024 characters. Longer messages will result in the over-writing of memory.


DESCRIPTION

This routine provides the functionality of the C function printf() for printing standard LAS messages. It calls the LAS support routine c_errmsg() to print all messages to the terminal and save them in the TAE session log.

If fatalflg is TRUE, the specified message is printed to the terminal and is examined to determine if the standard LAS fatal error message should be printed. If msgkey ends with "-fatal" and the specified message is "Fatal error encountered", the standard fatal error message will not be printed. If either of these conditions are false, the standard message will be printed using a message key of the form "FUNC-fatal". In either case, the program will terminate.

c_lasmsg() obsoletes c_errmsg() and should be used in its place in all LAS application development.


EXAMPLES

1. The function call:
   c_lasmsg(TRUE, "fstfmtin-start", "Starting line %d must be less than %d", sl, nl);
will generate the following output and cause the program to terminate.
   [fstfmtin-start] Starting line 1500 must be less than 1100
   [fstfmtin-fatal] Fatal error encountered
2. The function call:
   c_lasmsg(TRUE, "copy-fatal", "Fatal error encountered");
will generate the following output and cause the program to terminate.
   [copy-fatal] Fatal error encountered
3. The function calls:
   c_lasmsg(FALSE, "copy-alloc", "Error allocating memory");
   c_clean(vblock, "copy", hostout, &one);
will generate the following output. c_lasmsg() will print the first line and complete successfully while c_clean() will remove any output files, if necessary, generate the standard fatal error message, and terminate the program.
   [copy-alloc] Error allocating memory
   [copy-fatal] Fatal error encountered


RETURN VALUE

c_lasmsg() returns

     E_SUCC (0)       --> successful completion
     Does not return  --> when fatalflg == TRUE


SPECIAL CONSIDERATIONS

To access this routine, you will also need to link to:

     $LASLIB/las.a --> Unix object library