Introduction

To manage message callbacks the following API commands are supported.

Overview

Some database operations (like the spice parser, cone extraction, etc) may send warning or information messages by executing a callback procedure.

The callback procedure must be registered by zmessage setCallback …​.

The typical usage is:

proc myMsgCallback {time type message file line tclScript} {
    puts "$time $type $message $file $line $tclScript"
}
zmessage init
zmessage setCallback myMsgCallback
update idletasks
zspice parse ...
zmessage finit

This callback procedure is called from zspice command during execution. The 'type' argument can be used to distinguish between different message types. Possible types are i, w and e for information, warning and error messages. Additionally t for title information.

The init command tests if the callback was successfully installed by issue a special test message with the type x. If this test fails then a background error is thrown and update idletasks is needed to see the actual error message.

zmessage setCallbackFilter ?types?

can be used to only send certain message types to the registered callback.

To re-enable all message types, use zmessage clearCallbackFilter 1.

The call zmessage finit disables messaging output.

API Commands

To manage messages the following API commands are supported.

zmessage clear

Clear all messages.

Usage:

zmessage clear

Parameters:

No parameters.

Example:

# clear all messages
zmessage clear

zmessage clearCallbackFilter

Clear the callback filter.

Usage:

zmessage clearCallbackFilter value

Parameters:

value

Value for all message types.

Example:

# set all type filters to 0 (=> no messages are forwarded to the callback)
zmessage clearCallbackFilter 0

# set all type filters to 1 (=> all messages are forwarded to the callback)
zmessage clearCallbackFilter 1

zmessage closeLogfile

Close the current log file.

Usage:

zmessage closeLogfile

Parameters:

No parameters.

Example:

# close the previously opened logfile
zmessage closeLogfile

zmessage count

Return the number of existing messages.

Usage:

zmessage count

Parameters:

No parameters.

Example:

set count [zmessage count]
puts "There are $count messages"

zmessage countFiltered

Return the number of existing filtered messages.

Usage:

zmessage countFiltered

Parameters:

No parameters.

Example:

set count [zmessage countFiltered]
puts "There are $count filtered messages"

zmessage enableDebug

Enable the given debug flag.

Usage:

zmessage enableDebug flag

Parameters:

flag

Debug flag.

Example:

zmessage enableDebug "zdb/spos"

zmessage errorsSinceLastCall

Return the number of 'fatal' and 'error' messages since last call.

Usage:

zmessage errorsSinceLastCall

Parameters:

No parameters.

Example:

set errors [zmessage errorsSinceLastCall]
puts "errors since last call: $errors"

zmessage expandType

Return a human readable version of a one character type.

Usage:

zmessage expandType type

Parameters:

type

Message type.

Example:

set expanded [zmessage expandType w]
puts "w -> $expanded"

zmessage finit

Tear down the messaging subsystem.

Usage:

zmessage finit

Parameters:

No parameters.

Example:

zmessage finit

zmessage foreach

Iterate over a range of messages.

Usage:

zmessage foreach first last indexVar timeVar typeVar messageVar filenameVar linenoVar tclScriptVar body

Parameters:

body

The Tcl script body.

filenameVar

The file name variable.

first

The first index.

indexVar

The index variable.

last

The last index (may be 'end').

linenoVar

The file line variable.

messageVar

the message text variable.

tclScriptVar

The tclScript variable.

timeVar

The timestamp variable.

typeVar

the type variable.

Example:

zmessage foreach 0 "end"  index time type message fileName fileLine tclScript  {
    puts "[zmessage expandType $type]: $message"
}

zmessage foreachFiltered

Iterate over a range of filtered messages.

Usage:

zmessage foreachFiltered first last indexVar timeVar typeVar messageVar filenameVar linenoVar tclScriptVar body

Parameters:

body

The Tcl script body.

filenameVar

The file name variable.

first

The first index.

indexVar

The index variable.

last

The last index (may be 'end').

linenoVar

The file line variable.

messageVar

the message text variable.

tclScriptVar

The tclScript variable.

timeVar

The timestamp variable.

typeVar

the type variable.

Example:

zmessage foreachFiltered 0 "end"  index time type message fileName fileLine tclScript  {
    puts "[zmessage expandType $type]: $message"
}

zmessage getCallbackFilter

Return the current callback filter.

Usage:

zmessage getCallbackFilter

Parameters:

No parameters.

Example:

foreach type [zmessage getCallbackFilter] {
    puts "[zmessage longType $type] messages are forwarded"
}

zmessage getKnownDebugFlags

Return the list of known debug flags (list of name + description) pairs.

Usage:

zmessage getKnownDebugFlags

Parameters:

No parameters.

Example:

foreach {name description} [zmessage getKnownDebugFlags] {
    # do something with $name, $description
}

zmessage init

Initialize the messaging subsystem.

Usage:

zmessage init

Parameters:

No parameters.

Example:

zmessage init

zmessage isDebugEnabled

Check if the given debug flag is enabled.

Usage:

zmessage isDebugEnabled flag

Parameters:

flag

Debug flag.

Example:

if {[zmessage isDebugEnabled "zdb/spos"]} {
    # do something
}

zmessage isInitialized

Check if the messaging subsystem is initialized.

Usage:

zmessage isInitialized

Parameters:

No parameters.

Example:

if {[zmessage isInitialized]} {
    # do something
}

zmessage longType

Return a long human readable version of a one character type.

Usage:

zmessage longType type

Parameters:

type

Message type.

Example:

set long [zmessage longType w]
puts "w -> $long"

zmessage openLogfile

Open a log file.

Usage:

zmessage openLogfile ?-append? ?-buffered? ?-printold? filename

Parameters:

-append (optional)

Open the log file in append mode.

-buffered (optional)

Enable buffering (don’t flush the log file on each new message).

-printold (optional)

Print all existing old message to the log file after opening it.

filename

The file name of the log file to be opened.

Example:

# open a log file, also print all old messages to the file
zmessage openLogfile -printold my_log.txt

zmessage print

Print a message.

Usage:

zmessage print type message ?filename? ?lineno?

Parameters:

filename (optional)

The file the message corresponds to.

lineno (optional)

The file line the message corresponds to.

message

The actual message text.

type

Message type.

Example:

# print an info message
zmessage print INF "Info message"

# print a warning message with file/line info
zmessage print WAR "Syntax error" "my_file.v" 123

zmessage printWithTclScript

Print a message.

Usage:

zmessage printWithTclScript type message tclScript ?filename? ?lineno?

Parameters:

filename (optional)

The file the message corresponds to.

lineno (optional)

The file line the message corresponds to.

message

The actual message text.

tclScript

A Tcl script.

type

Message type.

Example:

# print an info message
zmessage printWithTclScript INF "Info message" "myScript"

# print a warning message with file/line info
zmessage printWithTclScript WAR "Syntax error" "myScript" "my_file.v" 123

zmessage removeCallback

Remove a message callback.

Usage:

zmessage removeCallback

Parameters:

No parameters.

Example:

# remove the previously registered message callback
zmessage removeCallback

zmessage setCallback

Install a message callback.

Usage:

zmessage setCallback ?-replay? callback

Parameters:

-replay (optional)

Replay old messages.

callback

The callback proc to install. The callback proc will be called with time, type, message, file, and line parameters.

Example:

proc my_callback {time type message file line tclScript} {
    set formatTime [clock format $time -format "%Y-%m-%d %T"]
    set formatType [zmessage expandType $type]
    puts "$formatTime $formatType $message ($file:$line) $tclScript"
}

zmessage setCallback -replay my_callback

zmessage setCallbackFilter

Set a callback filter.

Usage:

zmessage setCallbackFilter types

Parameters:

types

List of message types.

Example:

# only forward error and warning messages to the registered callback
zmessage setCallbackFilter {ERR WAR}

zmessage suppress

Suppress messages matching the given type and pattern.

Usage:

zmessage suppress type pattern

Parameters:

pattern

Case insensitive message text pattern.

type

Message type.

Example:

# suppress warning messages that match the pattern "*bad syntax:*"
zmessage suppress WAR "*bad syntax:*"

zmessage suppressCount

Return the number of suppressed messages for the given type and pattern.

Usage:

zmessage suppressCount type ?pattern?

Parameters:

pattern (optional)

Case insensitive message text pattern. If no pattern is specified, return the number of all suppressed messages for the given type.

type

Message type.

Example:

set count1 [zmessage suppressCount WAR]
puts "$count1 warning messages have been suppressed"

set count2 [zmessage suppressCount WAR "*bad syntax:*"]
puts "$count2 '*bad syntax:*' warning messages have been suppressed"

zmessage typeCount

Return the number of existing messages of the given type.

Usage:

zmessage typeCount type

Parameters:

type

Message type.

Example:

set count [zmessage typeCount WAR]
puts "There are $count warning messages"

zmessage usedMemory

Return the number of bytes used.

Usage:

zmessage usedMemory

Parameters:

No parameters.

Example:

set mem [zmessage usedMemory]
puts "zmessage uses $mem bytes of memory"