ajmess.c

Macro ajFatal

Fatal error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.
Input
format:(Input)Format
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Fatal error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.

See Also

See other functions in this section

Availability

In release 6.4.0

Macro ajMessCrash

Crash error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.
Input
format:(Input)Format
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Crash error message to standard error. Includes filename and line number in the source code that invokes it. Newline is added automatically at the end of the format string.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessInvokeDebugger

Used to trace in a debugger as a breakpoint

Synopsis

Prototype
void ajMessInvokeDebugger (
      void
);

TypeNameRead/WriteDescription
void RETURN

Returns
void:No return value

Description

Used to trace in a debugger as a breakpoint

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessRegBeep

Sets a function to process beeps

Synopsis

Prototype
AjMessVoidRoutine ajMessRegBeep (
      AjMessVoidRoutine func
);

TypeNameRead/WriteDescription
AjMessVoidRoutinefuncFunctionFunction to be registered
AjMessVoidRoutine RETURNPreviously defined function

Input
func:(Function)Function to be registered
Returns
AjMessVoidRoutine:Previously defined function

Description

Sets a function to process beeps

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessRegOut

Sets a function to write messages

Synopsis

Prototype
AjMessOutRoutine ajMessRegOut (
      AjMessOutRoutine func
);

TypeNameRead/WriteDescription
AjMessOutRoutinefuncFunctionFunction to be registered
AjMessOutRoutine RETURNPreviously defined function

Input
func:(Function)Function to be registered
Returns
AjMessOutRoutine:Previously defined function

Description

Sets a function to write messages

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessRegDump

Sets a function to dump data

Synopsis

Prototype
AjMessOutRoutine ajMessRegDump (
      AjMessOutRoutine func
);

TypeNameRead/WriteDescription
AjMessOutRoutinefuncFunctionFunction to be registered
AjMessOutRoutine RETURNPreviously defined function

Input
func:(Function)Function to be registered
Returns
AjMessOutRoutine:Previously defined function

Description

Sets a function to dump data

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessRegErr

Sets a function to report errors

Synopsis

Prototype
AjMessOutRoutine ajMessRegErr (
      AjMessOutRoutine func
);

TypeNameRead/WriteDescription
AjMessOutRoutinefuncFunctionFunction to be registered
AjMessOutRoutine RETURNPreviously defined function

Input
func:(Function)Function to be registered
Returns
AjMessOutRoutine:Previously defined function

Description

Sets a function to report errors

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessRegExit

Sets a function to exit

Synopsis

Prototype
AjMessOutRoutine ajMessRegExit (
      AjMessOutRoutine func
);

TypeNameRead/WriteDescription
AjMessOutRoutinefuncFunctionFunction to be registered
AjMessOutRoutine RETURNPreviously defined function

Input
func:(Function)Function to be registered
Returns
AjMessOutRoutine:Previously defined function

Description

Sets a function to exit

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessRegCrash

Sets a function to crash

Synopsis

Prototype
AjMessOutRoutine ajMessRegCrash (
      AjMessOutRoutine func
);

TypeNameRead/WriteDescription
AjMessOutRoutinefuncFunctionFunction to be registered
AjMessOutRoutine RETURNPreviously defined function

Input
func:(Function)Function to be registered
Returns
AjMessOutRoutine:Previously defined function

Description

Sets a function to crash

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessRegWarn

Sets a function to print warnings

Synopsis

Prototype
AjMessOutRoutine ajMessRegWarn (
      AjMessOutRoutine func
);

TypeNameRead/WriteDescription
AjMessOutRoutinefuncFunctionFunction to be registered
AjMessOutRoutine RETURNPreviously defined function

Input
func:(Function)Function to be registered
Returns
AjMessOutRoutine:Previously defined function

Description

Sets a function to print warnings

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessBeep

Calls the defined beep function, if any. Otherwise prints ASCII 7 to standard error.

Synopsis

Prototype
void ajMessBeep (
      void
);

TypeNameRead/WriteDescription
void RETURN

Returns
void:No return value

Description

Calls the defined beep function, if any. Otherwise prints ASCII 7 to standard error.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajUser

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

Synopsis

Prototype
void ajUser (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputFormat string
...varargVarargVariable length argument list
void RETURN

Input
format:(Input)Format string
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajUserDumpC

Prints a string unchanged. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

Synopsis

Prototype
void ajUserDumpC (
      const char* txt
);

TypeNameRead/WriteDescription
const char*txtInputString to print unchanged
void RETURN

Input
txt:(Input)String to print unchanged
Returns
void:No return value

Description

Prints a string unchanged. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajUserDumpS

Prints a string unchanged. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

Synopsis

Prototype
void ajUserDumpS (
      const AjPStr str
);

TypeNameRead/WriteDescription
const AjPStrstrInputString to print unchanged
void RETURN

Input
str:(Input)String to print unchanged
Returns
void:No return value

Description

Prints a string unchanged. Calls the defined output function (if any). Otherwise prints the message to standard error with an extra newline.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessOut

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with no newline.

Synopsis

Prototype
void ajMessOut (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputFormat string
...varargVarargVariable length argument list
void RETURN

Input
format:(Input)Format string
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error with no newline.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajVUser

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error.

Synopsis

Prototype
void ajVUser (
      const char* format,
      va_list args
);

TypeNameRead/WriteDescription
const char*formatInputFormat string
va_listargsVarargVariable length argument list
void RETURN

Input
format:(Input)Format string
args:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats a message. Calls the defined output function (if any). Otherwise prints the message to standard error.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessDump

Formats a message. Calls the dump function (if any). Otherwise no further action.

Synopsis

Prototype
void ajMessDump (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputformat string.
...varargVarargVariable length argument list.
void RETURN

Input
format:(Input)format string.
:(Vararg)Variable length argument list.
Returns
void:No return value

Description

Formats a message. Calls the dump function (if any). Otherwise no further action.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessGetCountError

Returns the number of times the error routines have been called.

Synopsis

Prototype
ajint ajMessGetCountError (
      void
);

TypeNameRead/WriteDescription
ajint RETURNError function call count.

Returns
ajint:Error function call count.

Description

Returns the number of times the error routines have been called.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajErr

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

Synopsis

Prototype
void ajErr (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputFormat
...varargVarargVariable length argument list
void RETURN

Input
format:(Input)Format
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajVErr

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

Synopsis

Prototype
void ajVErr (
      const char* format,
      va_list args
);

TypeNameRead/WriteDescription
const char*formatInputFormat
va_listargsVarargVariable length argument list
void RETURN

Input
format:(Input)Format
args:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline.

The error message count is incremented by 1 for each call.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajDie

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

Synopsis

Prototype
void ajDie (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputFormat
...varargVarargVariable length argument list
void RETURN

Input
format:(Input)Format
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajVDie

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

Synopsis

Prototype
void ajVDie (
      const char* format,
      va_list args
);

TypeNameRead/WriteDescription
const char*formatInputFormat
va_listargsVarargVariable length argument list
void RETURN

Input
format:(Input)Format
args:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats an error message. Calls the error function (if any). Otherwise prints the message to standard error with a trailing newline. Then kills the application.

The error message count is incremented by 1 for each call.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajWarn

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

Synopsis

Prototype
void ajWarn (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputFormat
...varargVarargVariable length argument list
void RETURN

Input
format:(Input)Format
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajVWarn

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

Synopsis

Prototype
void ajVWarn (
      const char* format,
      va_list args
);

TypeNameRead/WriteDescription
const char*formatInputFormat
va_listargsVarargVariable length argument list
void RETURN

Input
format:(Input)Format
args:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats a warning message. Calls the warning function (if any). Otherwise prints the message to standard error with a trailing newline.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessExitmsg

Formats an exit message and calls the exit function (if any). Otherwise prints the message to standard error with a trailing newline and exist with code EXIT_FAILURE.

Use this function for errors that while being unrecoverable are not a problem with the AJAX code.

Note that there errors are logged but that this routine will exit without any chance to interrupt it (see the crash routine in ajMessCrashFL), this could be changed to allow the application to register an exit handler.

Synopsis

Prototype
void ajMessExitmsg (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputFormat
...varargVarargVariable length argument list
void RETURN

Input
format:(Input)Format
:(Vararg)Variable length argument list
Returns
void:No return value

Description

Formats an exit message and calls the exit function (if any). Otherwise prints the message to standard error with a trailing newline and exist with code EXIT_FAILURE.

Use this function for errors that while being unrecoverable are not a problem with the AJAX code.

Note that there errors are logged but that this routine will exit without any chance to interrupt it (see the crash routine in ajMessCrashFL), this could be changed to allow the application to register an exit handler.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessCrashFL

This is the routine called by the ajFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

Synopsis

Prototype
void ajMessCrashFL (
      const char* format,
      ...
);

TypeNameRead/WriteDescription
const char*formatInputFormat
...varargVarargVariable length argument list
void RETURN

Input
format:(Input)Format
:(Vararg)Variable length argument list
Returns
void:No return value

Description

This is the routine called by the ajFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessVCrashFL

This is the routine called by the ajVFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

Synopsis

Prototype
void ajMessVCrashFL (
      const char* format,
      va_list args
);

TypeNameRead/WriteDescription
const char*formatInputFormat
va_listargsVarargVariable length argument list
void RETURN

Input
format:(Input)Format
args:(Vararg)Variable length argument list
Returns
void:No return value

Description

This is the routine called by the ajVFatal macro and others.

This routine may encounter errors itself, in which case it will attempt to call itself to report the error. To avoid infinite recursion we limit this to just one reporting of an internal error and then we abort.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessGetMessageC

Returns the current message text.

Synopsis

Prototype
const char* ajMessGetMessageC (
      void
);

TypeNameRead/WriteDescription
const char* RETURNMessage text

Returns
const char*:Message text

Description

Returns the current message text.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessGetSysmessageC

Returns the system message text from 'strerror' from the standard C library.

Synopsis

Prototype
const char* ajMessGetSysmessageC (
      void
);

TypeNameRead/WriteDescription
const char* RETURNSystem error message.

Returns
const char*:System error message.

Description

Returns the system message text from 'strerror' from the standard C library.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessErrorInit

Initialises the stored program name.

Synopsis

Prototype
void ajMessErrorInit (
      const char* progname
);

TypeNameRead/WriteDescription
const char*prognameInputProgram name.
void RETURN

Input
progname:(Input)Program name.
Returns
void:No return value

Description

Initialises the stored program name.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessSetErr

Stores the source file name (converted to a base name) and the source line number to be reported by the crash routines.

Invoked automatically by a macro (e.g. ajFatal) where needed.

Synopsis

Prototype
void ajMessSetErr (
      const char* filename,
      ajint line_num
);

TypeNameRead/WriteDescription
const char*filenameInputsource filename, __FILE__
ajintline_numInputsource line number, __LINE__
void RETURN

Input
filename:(Input)source filename, __FILE__
line_num:(Input)source line number, __LINE__
Returns
void:No return value

Description

Stores the source file name (converted to a base name) and the source line number to be reported by the crash routines.

Invoked automatically by a macro (e.g. ajFatal) where needed.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessErrorSetFile

Opens a file and sets this to be the error file.

Synopsis

Prototype
AjBool ajMessErrorSetFile (
      const char* errfile
);

TypeNameRead/WriteDescription
const char*errfileInputError file name
AjBool RETURNajTrue on success

Input
errfile:(Input)Error file name
Returns
AjBool:ajTrue on success

Description

Opens a file and sets this to be the error file.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessOutCode

Writes an output message for a given message code.

Synopsis

Prototype
void ajMessOutCode (
      const char* code
);

TypeNameRead/WriteDescription
const char*codeInputMessage code
void RETURN

Input
code:(Input)Message code
Returns
void:No return value

Description

Writes an output message for a given message code.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessErrorCode

Writes an error message for a given message code.

Synopsis

Prototype
void ajMessErrorCode (
      const char* code
);

TypeNameRead/WriteDescription
const char*codeInputError code
void RETURN

Input
code:(Input)Error code
Returns
void:No return value

Description

Writes an error message for a given message code.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessCrashCodeFL

Writes an error message for a given message code and crashes.

Synopsis

Prototype
void ajMessCrashCodeFL (
      const char* code
);

TypeNameRead/WriteDescription
const char*codeInputError code
void RETURN

Input
code:(Input)Error code
Returns
void:No return value

Description

Writes an error message for a given message code and crashes.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessCodesDelete

Deletes the message codes table.

Synopsis

Prototype
void ajMessCodesDelete (
      void
);

TypeNameRead/WriteDescription
void RETURN

Returns
void:No return value

Description

Deletes the message codes table.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajDebug

Writes a debug message to the debug file if debugging is on. Typically, debugging is turned on by adding '-debug' to the command line or by defining a variable prefix_DEBUG

Avoid using this call in any code which can be invoked before the command line processing is complete as it can be a problem to find a reasonable file name for debug output under these circumstances.

Synopsis

Prototype
void ajDebug (
      const char* fmt,
      ...
);

TypeNameRead/WriteDescription
const char*fmtInputFormat.
...varargVarargVariable argument list.
void RETURN

Input
fmt:(Input)Format.
:(Vararg)Variable argument list.
Returns
void:No return value

Description

Writes a debug message to the debug file if debugging is on. Typically, debugging is turned on by adding '-debug' to the command line or by defining a variable prefix_DEBUG

Avoid using this call in any code which can be invoked before the command line processing is complete as it can be a problem to find a reasonable file name for debug output under these circumstances.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajDebugOn

Test whether debugging is on.

Synopsis

Prototype
AjBool ajDebugOn (
      void
);

TypeNameRead/WriteDescription
AjBool RETURNTrue if user has enabled debugging

Returns
AjBool:True if user has enabled debugging

Description

Test whether debugging is on.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajDebugTest

Tests a token string and returns true if the user has requested debug output

Synopsis

Prototype
AjBool ajDebugTest (
      const char* token
);

TypeNameRead/WriteDescription
const char*tokenInputToken name
AjBool RETURNTrue if token has debugging requested

Input
token:(Input)Token name
Returns
AjBool:True if token has debugging requested

Description

Tests a token string and returns true if the user has requested debug output

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessGetDebugfile

Returns the file used for debug output, or NULL if no debug file is open.

Synopsis

Prototype
FILE* ajMessGetDebugfile (
      void
);

TypeNameRead/WriteDescription
FILE* RETURNC runtime library file handle for debug output.

Returns
FILE*:C runtime library file handle for debug output.

Description

Returns the file used for debug output, or NULL if no debug file is open.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajUserGet

Writes a prompt to the terminal and reads one line from the user.

Synopsis

Prototype
ajint ajUserGet (
      AjPStr* pthis,
      const char* fmt,
      ...
);

TypeNameRead/WriteDescription
AjPStr*pthisOutputBuffer for the user response.
const char*fmtInputFormat string
...varargVarargVariable argument list.
ajint RETURNLength of response string.

Input
fmt:(Input)Format string
:(Vararg)Variable argument list.
Output
pthis:(Output)Buffer for the user response.
Returns
ajint:Length of response string.

Description

Writes a prompt to the terminal and reads one line from the user.

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessExit

Delete any static initialised values

Synopsis

Prototype
void ajMessExit (
      void
);

TypeNameRead/WriteDescription
void RETURN

Returns
void:No return value

Description

Delete any static initialised values

See Also

See other functions in this section

Availability

In release 6.4.0

Function ajMessExitDebug

Delete any static initialised values for ajDebug calls

Synopsis

Prototype
void ajMessExitDebug (
      void
);

TypeNameRead/WriteDescription
void RETURN

Returns
void:No return value

Description

Delete any static initialised values for ajDebug calls

See Also

See other functions in this section

Availability

In release 6.4.0