Monitor information events

The Monitor Event message SWMSG_MONITOR. More...

Modules
	Monitor event Unique IDs

Files
file	monevent.h
	Header file defining the Monitor information events and messages.

Data Structures
struct	SWMSG_MONITOR
	Message for SWEVT_MONITOR event. More...

Macros
#define	MON_PSERROR(uid)

Typedefs
typedef HqnIdent	sw_mon_channel
	SWMSG_MONITOR channel. More...
typedef HqnIdent	sw_mon_type
	SWMSG_MONITOR type. More...
typedef struct SWMSG_MONITOR	SWMSG_MONITOR
	Message for SWEVT_MONITOR event. More...

Enumerations
enum	{   MON_OVERRIDE = SW_EVENT_OVERRIDE , MON_EARLY = SW_EVENT_OVERRIDE - 1000 , MON_PRE_FILTER = SW_EVENT_NORMAL + 100 , MON_FILTER = SW_EVENT_NORMAL ,   MON_POST_FILTER = SW_EVENT_NORMAL - 100 , MON_PRE_AUGMENT = SW_EVENT_NORMAL - 400 , MON_AUGMENT = SW_EVENT_NORMAL - 500 , MON_POST_AUGMENT = SW_EVENT_NORMAL - 600 ,   MON_PRE_LOCALIZE = SW_EVENT_NORMAL - 900 , MON_LOCALIZE = SW_EVENT_NORMAL - 1000 , MON_POST_LOCALIZE = SW_EVENT_NORMAL - 1100 , MON_PRE_DEFAULT = SW_EVENT_DEFAULT + 100 ,   MON_DEFAULT_HANDLER = SW_EVENT_DEFAULT , MON_COMPATIBILITY = SW_EVENT_DEFAULT - 999 , MON_FALLBACK = SW_EVENT_DEFAULT - 1000 }
	Priority levels for SWEVT_MONITOR Handlers. More...
enum	SW_MON_CHANNELS {   MON_CHANNEL_MONITOR = 1 , MON_CHANNEL_PROGRESS , MON_CHANNEL_HALFTONE , MON_CHANNEL_STDOUT ,   MON_CHANNEL_STDERR }
	Well-known values for sw_mon_channel. More...
enum	{   MON_CLASS_ERROR = 3<<29 , MON_CLASS_WARNING = 2<<29 , MON_CLASS_INFO = 1<<29 , MON_CLASS_DEBUG = 0<<29 ,   MON_MASK_CLASS = 3<<29 , MON_SHIFT_CLASS = 29 , MON_MASK_ERRORNUM = 0xFF<<16 , MON_SHIFT_ERRORNUM = 16 ,   MON_MASK_UNIQUE = 0xFFFF }
	sw_mon_type Classifications. More...
enum	{   MON_ERROR_CRITICAL = MON_CLASS_ERROR + (3<<27) , MON_ERROR = MON_CLASS_ERROR + (1<<27) , MON_WARNING_FAILURE = MON_CLASS_WARNING + (3<<27) , MON_WARNING = MON_CLASS_WARNING + (1<<27) ,   MON_INFO_CONTROL = MON_CLASS_INFO + (3<<27) , MON_INFO = MON_CLASS_INFO + (2<<27) , MON_INFO_JOB = MON_CLASS_INFO + 0 , MON_DEBUG = MON_CLASS_DEBUG + (2<<27) ,   MON_DEBUG_VERBOSE = MON_CLASS_DEBUG + 0 , MON_MASK_SUBCLASS = 15<<27 , MON_SHIFT_SUBCLASS = 27 }
	sw_mon_type Subclassifications. More...
enum	{   MON_BASE_NONE = 0 , MON_BASE_COREJOB = 0x100 , MON_BASE_HALFTONE = 0x200 , MON_BASE_TIFF = 0x300 ,   MON_BASE_PDF = 0x400 , MON_BASE_PDFX = 0x500 , MON_BASE_HVD = 0x700 , MON_BASE_PS = 0x800 ,   MON_BASE_XPS = 0x900 , MON_BASE_PCL = 0xA00 , MON_BASE_FONT = 0xB00 , MON_BASE_FILEIO = 0xC00 ,   MON_BASE_COLOR = 0xD00 , MON_BASE_HDLT = 0xE00 , MON_BASE_PCLXL = 0xF00 , MON_BASE_SEC = 0x1000 ,   MON_BASE_XML = 0x1100 , MON_BASE_RENDER = 0x1200 , MON_BASE_RECOMBINE = 0x1300 , MON_BASE_BACKDROP = 0x1400 ,   MON_BASE_TRAPPING = 0x1500 , MON_BASE_JPEG2K = 0x1600 , MON_BASE_PNG = 0x1700 , MON_BASE_WMPHOTO = 0x1800 ,   MON_BASE_JBIG = 0x1900 , MON_BASE_CCITTFAX = 0x1A00 , MON_BASE_JPEG = 0x1B00 , MON_BASE_WCS = 0x1C00 ,   MON_BASE_IMGFILTER = 0x1D00 , MON_BASE_SKINKIT = 0x1E00 , MON_BASE_SCALABLERIP = 0x1F00 , MON_BASE_BMP = 0x2000 ,   MON_BASE_RASTERSTORE = 0x2100 , MON_BASE_LIBHVD = 0x2180 , MON_BASE_RDREVENT = 0x2200 , MON_BASE_SWAPI = 0x2280 ,   MON_BASE_SWDATA = 0x2300 , MON_BASE_TIMELINE = 0x2380 , MON_BASE_INPUTQ = 0x2400 , MON_BASE_LIMIT = 0xFFFF ,   MON_BASE_MAXIMUM = 0xFFFFFF }
	sw_mon_type Range Bases More...

Detailed Description

The Monitor Event message SWMSG_MONITOR.

The monitor event message SWMSG_MONITOR is the representation in which textual messages are sent, filtered, localized, logged and output. Monitor events have a type represented by sw_mon_type, which is decomposable into its classification, sub-classification, and potentially error number and message unique ID. Monitor events are sent to a channel represented by sw_mon_channel, with well-known values SW_MON_CHANNELS (but also extensible to include OEM-defined channels). Monitor events may have a related timeline reference.

Macro Definition Documentation

MON_PSERROR

#define MON_PSERROR

(

uid

)

Value:

                          (((uid) < MON_CLASS_ERROR) ? ((uid) < 0) ? (uid) : 0 \
                          : ((uid) & MON_MASK_ERRORNUM) >> MON_SHIFT_ERRORNUM)

Macro to extract a PS error number from a message identifier. This preserves special negative codes used internally and returns 0 if the uid is not of the ERROR classification.

Typedef Documentation

sw_mon_channel

typedef HqnIdent sw_mon_channel

SWMSG_MONITOR channel.

The Monitor Event Channel number allows multiple streams to be sent over the Monitor Event, and enables Handlers to filter messages without having to inspect the unique identifier described later.

This is used by the Core's compatibility layer to route messages through the %monitor% and %progress% devices compatibly with earlier RIP versions. As such, the Channel is primarily implementational rather than semantic. However, other Handlers can use this metadata as they wish.

It is possible to coin new channel numbers, and through use of the Monitor Event DeviceType (52) one can connect existing PostScript devices such as %monitor% or create new devices such as %errors% which send any text written to them as a Monitor Event on a specified Channel and with a specific Type.

Top eight bits are OEM number, so OEMs can generate and parse their own monitor and log messages unambiguously.

sw_mon_type

typedef HqnIdent sw_mon_type

SWMSG_MONITOR type.

This is a unique identifier for the message, comprising a classification, a subclassification, a PostScript error number for error messages, and a unique numeric field for individual message identification. This field is primarily semantic.

• Bit 31 is reserved for future use.
• Bits 29..30 are the message classification.
• Bits 27..28 are the message subclassification.
• Bits 24..26 are reserved for future use.
• Bits 0..23 are a unique identifier for this message. For classification MON_CLASS_ERROR these are:
  • Bits 16..23 are the error number for PS errors (see pserrors.h).
  • Bits 0..15 are a unique identifier. This system allows, e.g., every INVALIDFONT raised by the Core to have its source and hence its cause documented in the message.

This identifier allows messages to be unambiguously recognised without having to parse the textual content (which is harder, fragile and subject to localization).

Individual message identifiers are often of the form MON_TYPE_uniquelabel and are enumerated elsewhere, starting from a SUBCLASS and range BASE defined here. For example:

enum {
  MON_TYPE_EXAMPLEMESSAGE = MON_INFO + MON_BASE_EXAMPLEBASE,
  MON_TYPE_ANOTHEREXAMPLE,
  MON_TYPE_FINALEXAMPLE
} ;

Additionally, ERROR class messages contain a PS error number and are of the form MON_errorname_uniquelabel. For example:

enum {
  MON_INVALIDFONT_BROKENTTCMAP = MON_ERROR + MON_BASE_TRUETYPE +
                                 (INVALIDFONT << MON_SHIFT_ERRORNUM),
  MON_INVALIDFONT_MISSINGTABLE,
  MON_INVALIDFONT_BADTTVERSION,
  MON_INVALIDFONT_SOMEOTHERERRORSITE
} ;

This allows Handlers to detect particular PostScript errors, or to identify individual causes of a particular error, without having to parse the error report.

It also allows Handlers to filter out messages they don't need, log messages in different logfiles according to classification or subclass, and makes localization much easier.

SWMSG_MONITOR

typedef struct SWMSG_MONITOR SWMSG_MONITOR

Message for SWEVT_MONITOR event.

The text of a Monitor Event message is UTF-8 encoded Unicode. It can be zero length. Typically it will consist of a complete line with a terminating newline character, but this is not guaranteed.

The Monitor Event Device Type allows PostScript operators such as print and = to output text through the Monitor Event. It can be configured with the appropriate metadata for the Event, and optionally with an Encoding from which to transcode to UTF-8.

Typically the pseudo-file 'stdout' is connected to the PS Device 'output' which is configured as:

/DeviceType 52    % Monitor Event Device Type
/Password 0
/Enable true
/Channel /Monitor % MON_CHANNEL_MONITOR
/UID 16#20000000  % MON_INFO_JOB
/Timeline 0       % 0 means current interpreter Timeline

and the pdeudo-file 'stderr' is connected to the PS Device 'errors' which is configured as:

/DeviceType 52    % Monitor Event Device Type
/Password 0
/Enable true
/Channel /stderr  % MON_CHANNEL_STDERR
/UID 16#48000000  % MON_WARNING
/Timeline 0       % 0 means current interpreter Timeline

If these are also configured with an /Encoding, with a string value equal to one of the known ICU encodings, the Monitor Event Device Type will also transcode the text before issuing the Monitor Event.

If there is no configured Encoding then the default behaviour is to preserve the bytes emitted by print or =. This is achieved by leaving the low "ASCII" bytes alone, and mapping the high bytes to the Private Use Area EC80..ECFF range. These are mapped back to the original bytes by the Compatibility Handler before being written to the legacy Monitor Device %monitor%. This is for backwards compatibility reasons only - OEMs are encouraged to configure the Monitor Event Devices appropriately, and the Monitor Device and Progress Device are now marked as obsolescent.

Enumeration Type Documentation

anonymous enum

anonymous enum

Priority levels for SWEVT_MONITOR Handlers.

It is intended that a message sent as a Monitor Event passes through multiple Handlers before being output. Such Handlers can perform many functions:

Filtering/Suppression

Individual messages, ranges or classifications of messages can be suppressed, to prevent them being displayed or even logged, by a Handler that returns SW_EVENT_HANDLED. Such a Handler should normally be registered at a priority level of MON_FILTER.

Augmentation

It may be that a subsystem will want to add output when certain messages are sent, such as error messages. Such a Handler would use SwEventTail() to output additional lines before and/or after the message in question. Note that recipients 'downstream' can tell that messages are grouped in this way as all events sent by SwEventTail() share the same sw_event id as the original event. Such Handlers are registered at MON_AUGMENT.

Localization

A Handler can localize, translate or reword messages by changing the SWMSG_MONITOR message. It can modify the text and length fields to point to its own static message before passing on with SW_EVENT_CONTINUE, or if dynamically allocated it can call SwEventTail() and return its return value (changing SW_EVENT_UNHANDLED to SW_EVENT_FORCE_UNHANDLED to avoid recursion). A localization Handler is registered at a priority level of MON_LOCALIZE.

Logging

A Handler can write the message and optionally its metadata to a logfile, before or after localisation, and even before any filtering or suppression has occured. A number of priority levels are defined that can be chosen appropriately, e.g., MON_PRE_FILTER, MON_PRE_LOCALIZE, MON_PRE_DEFAULT.

Output

The Skin is expected to register a Default Handler to output and/or log textual messages. It may use the message metadata to select different windows or logfiles, or to filter or highlight certain message types. The Skin's Default Handler is registered at MON_DEFAULT_HANDLER or SW_EVENT_DEFAULT (which are defined to be the same).

Fallback

The Core provides a compatibility layer which sends messages over the %progress% and %monitor% devices if no Skin Handler has dealt with them. Note that it is strongly recommended that the Skin implements a Default Handler as it then has access to message metadata, almost all of which is lost once sent over the old device interfaces.

Enumerator
MON_OVERRIDE	Monitor overrides.
MON_EARLY	Monitor overrides.
MON_PRE_FILTER	Message suppression
MON_FILTER	Message suppression
MON_POST_FILTER	Message suppression
MON_PRE_AUGMENT	Message augmentation
MON_AUGMENT	Message augmentation
MON_POST_AUGMENT	Message augmentation
MON_PRE_LOCALIZE	Pre-localization logging
MON_LOCALIZE	Localization step
MON_POST_LOCALIZE	Post-localization logging
MON_PRE_DEFAULT	Skin output handler
MON_DEFAULT_HANDLER	Skin output handler
MON_COMPATIBILITY	Compatibility layer
MON_FALLBACK	Compatibility layer

anonymous enum

anonymous enum

sw_mon_type Classifications.

There are four message classifications, with four potential subclassifications in each.

MON_CLASS_ERROR

Error messages emitted by (or appearing to be emitted by) the PostScript Error Handler are labelled MON_ERROR. Fatal errors that will result in RIP shutdown are labelled MON_ERROR_CRITICAL.

MON_CLASS_WARNING

Messages relating to unusual situations, badly formed documents or other unanticipated problems that may have an impact on output or may result in a subsequent ERROR. Note that use of the stopped operator in PostScript can suppress such an ERROR even though a warning was issued. Warnings that indicate the RIP expects there to be an error will be labelled with the highest subclass, MON_WARNING_FAILURE. Otherwise warnings are labelled MON_WARNING.

MON_CLASS_INFO

Normal operational messages - job control, page interpretation and rendering progress, PDL metadata, timing messages etc.

MON_CLASS_DEBUG

Internal debugging messages, whether explicitly enabled or emitted by default are labelled with the DEBUG class. Explicitly requested debugging information will be labelled MON_DEBUG, and unrequested MON_DEBUG_VERBOSE.

Enumerator
MON_CLASS_ERROR	All error reports - contains error num
MON_CLASS_WARNING	Warnings that may not result in error
MON_CLASS_INFO	All other output
MON_CLASS_DEBUG	Internal debugging information
MON_MASK_CLASS	To extract the Class from a type
MON_SHIFT_CLASS	To extract the Class from a type
MON_MASK_ERRORNUM	for error number in error Class
MON_SHIFT_ERRORNUM	for 8bit error number in error Class
MON_MASK_UNIQUE	for unique part of error reports

anonymous enum

anonymous enum

sw_mon_type Subclassifications.

We predefine a number of subclasses within each Classification to provide additional information and filtering capability should it be required.

Errors:

MON_ERROR_CRITICAL

Fatal errors that will result in a RIP shutdown. Part of MON_CLASS_ERROR. Contains a PostScript error number.

MON_ERROR

Other errors reported by the PostScript Error Handler. Part of MON_CLASS_ERROR. Contains a PostScript error number.

Warnings:

MON_WARNING_FAILURE

An unusual circumstance that the RIP expects to result in an ERROR or incorrect output. Part of MON_CLASS_WARNING. Note that use of the PostScript 'stopped' operator can suppress the error the RIP may raise as a result of such a failure.

MON_WARNING

An unusual circumstance that the RIP believes it has handled correctly. Part of MON_CLASS_WARNING.

Information:

MON_INFO_CONTROL

Job control, timing and progress messages. Part of MON_CLASS_INFO.

MON_INFO

Informational messages from the RIP not directly related to job control. Part of MON_CLASS_INFO.

MON_INFO_JOB

Text emitted by PostScript jobs. Part of MON_CLASS_INFO.

Debugging:

MON_DEBUG

Explicitly enabled debugging messages. Part of MON_CLASS_DEBUG.

MON_DEBUG_VERBOSE

A verbose stream of debugging commentary that may be useful to log but which is expected to be filtered out before appearing in the UI. Part of MON_CLASS_DEBUG.

Clients may choose to treat these subclasses separately, such as sending MON_INFO_CONTROL to a specific job control log, or may use some as thresholds, such as this Handler which filters out verbose debugging:

sw_event_result RIPCALL no_verbose(sw_event * ev, void * ctx)
{
  SWMSG_MONITOR * mon = ev->message ;
 
  if ((mon->type & MON_MASK_SUBCLASS) <= MON_DEBUG_VERBOSE)
    return SW_EVENT_HANDLED ;
 
  return SW_EVENT_CONTINUE ;
}

Enumerator
MON_ERROR_CRITICAL	RIP shutdown error
MON_ERROR	Reported error
MON_WARNING_FAILURE	Warning of failure
MON_WARNING	Warning but recovered
MON_INFO_CONTROL	Job control messages
MON_INFO	Informational messages
MON_INFO_JOB	Messages from the job.
MON_DEBUG	Explicitly enabled debug.
MON_DEBUG_VERBOSE	Verbose debug
MON_MASK_SUBCLASS	To extract the class and subclass from a Type
MON_SHIFT_SUBCLASS	To extract the class and subclass from a Type

anonymous enum

anonymous enum

sw_mon_type Range Bases

Individual message identifiers are enumerated elsewhere, so that adding a new identifier in some subsystem does not cause all other subsystems to have to be rebuilt.

Systems that do not emit error class messages can be allocated a base range higher than MON_BASE_LIMIT as they won't be adding an error number as well.

Enumerator
MON_BASE_NONE	to 0FF inclusive.
MON_BASE_COREJOB	to 1FF inclusive.
MON_BASE_HALFTONE	to 2FF inclusive. Subdivided in monht.h
MON_BASE_TIFF	to 3FF inclusive. Subdivided in montiff.h
MON_BASE_PDF	to 4FF inclusive. Subdivided in monpdf.h
MON_BASE_PDFX	to 6FF inclusive. Subdivided in monpdf.h
MON_BASE_HVD	to 7FF inclusive. Subdivided in monhvd.h
MON_BASE_PS	to 8FF inclusive. Subdivided in monps.h
MON_BASE_XPS	to 9FF inclusive. Obsoleted (was monxps)
MON_BASE_PCL	to AFF inclusive. Obsoleted (was monpcl)
MON_BASE_FONT	to BFF inclusive. Subdivided in monfont.h
MON_BASE_FILEIO	to CFF inclusive. Subdivided in monfileio.h
MON_BASE_COLOR	to DFF inclusive. Subdivided in moncolor.h
MON_BASE_HDLT	to EFF inclusive. Subdivided in monhdlt.h
MON_BASE_PCLXL	to FFF inclusive. Obsoleted (was monpclxl)
MON_BASE_SEC	to 10FF inclusive. Subdivided in monsec.h
MON_BASE_XML	to 11FF inclusive. Subdivided in monxml.h
MON_BASE_RENDER	to 12FF inclusive. Subdivided in monrender.h
MON_BASE_RECOMBINE	to 13FF inclusive. Obsoleted (was monrecombine)
MON_BASE_BACKDROP	to 14FF inclusive. Subdivided in monbackdrop.h
MON_BASE_TRAPPING	to 15FF inclusive. Subdivided in montrapping.h
MON_BASE_JPEG2K	to 16FF inclusive. Subdivided in monjpeg2k.h
MON_BASE_PNG	to 17FF inclusive. Subdivided in monpng.h
MON_BASE_WMPHOTO	to 18FF inclusive. Obsoleted (was monwmphoto)
MON_BASE_JBIG	to 19FF inclusive. Subdivided in monjbig.h
MON_BASE_CCITTFAX	to 1AFF inclusive. Subdivided in monccittfax.h
MON_BASE_JPEG	to 1BFF inclusive. Subdivided in monjpeg.h
MON_BASE_WCS	to 1CFF inclusive. Obsoleted (was monwcs)
MON_BASE_IMGFILTER	to 1DFF inclusive. Subdivided in monimgfilter.h
MON_BASE_SKINKIT	to 1EFF inclusive. Subdivided in monskinkit.h
MON_BASE_SCALABLERIP	to 1FFF inclusive. Subdivided in monscalablerip.h
MON_BASE_BMP	to 20FF inclusive. Subdivided in monbmp.h
MON_BASE_RASTERSTORE	to 217F inclusive. Subdivided in moninterface.h
MON_BASE_LIBHVD	to 21FF inclusive. Subdivided in monlibhvd.h
MON_BASE_RDREVENT	to 227F inclusive. Subdivided in moninterface.h
MON_BASE_SWAPI	to 22FF inclusive. Subdivided in moninterface.h
MON_BASE_SWDATA	to 237F inclusive. Subdivided in moninterface.h
MON_BASE_TIMELINE	to 23FF inclusive. Subdivided in moninterface.h
MON_BASE_INPUTQ	to 247F inclusive. Subdivided in moninterface.h

SW_MON_CHANNELS

enum SW_MON_CHANNELS

Well-known values for sw_mon_channel.

Enumerator
MON_CHANNEL_MONITOR	C code via %monitor%
MON_CHANNEL_PROGRESS	Progress via %progress%logfile
MON_CHANNEL_HALFTONE	Halftones via %progress%halftoneinfo
MON_CHANNEL_STDOUT	File output via %stdout%
MON_CHANNEL_STDERR	Errors via %stderr%