Welcome to the reference page for QisMLog, an extended API of QisMLib, Artwork Conversion's CAD processing framework.
QisMLog is the framework's shared logging service. Every part of the framework, and any extension or program built on it, can use it to report progress, warnings, and errors in one consistent way. Messages can go to the screen, to a log file, or to a handler in your own program, and you decide how much detail appears by setting a verbosity level or switching on named channels through environment variables, which are settings the operating system hands to a program when it starts.
The component also has a second, more unusual job: a vector log. Instead of writing text, it writes geometry, so a program can dump the shapes it is working on into a GDSII file, one of the standard formats for storing chip layouts, and open that file later in a viewer to see what happened.
This page is the complete reference for the component. Here is what you will find, in the order it appears:
The vector log. The interface for writing geometry to a GDSII log file: begin and end a cell, then add boundaries, paths, text labels, and single or arrayed references to other cells, in either database units or user units. The boundary and path calls are safe to use from several threads at once.
Log channels. A way to group messages by module or component. A channel is switched on by naming it in an environment variable, and a message sent to a channel is only written if that channel is on.
The message callback. The small interface a program implements to receive each log message as it is produced, flagged as information or as a warning.
The main logging interface. The core calls that write a message to screen and file, to screen only, or only when verbose mode is on, with a note on the start-up options that must be given for messages to appear at all. Later versions add the ability to unlink the log and relink it to a file, a file handle, a client handler, or standard output; a numeric verbosity level so messages can be tiered; calls that accept pre-formatted strings; access to the channel manager; and the ability to open and close a vector log.
The debug macro. A compile-time switch for diagnostic messages that should exist only in development builds and disappear from production software.
If you are using the API into your own software, start with the main logging interface, and turn to the vector log when you need to see geometry rather than text.
QisMLog QisMLog C++ API (qismlog.h)Version ControlGridBegin_cellBoundaryBoundaryUUPathPathUUTextSrefArefEnd_cellQisMLogChannelsVersion ControlGet_channel_onoffChannel_msgChannel_strQisMLogCbVersion ControlOn_qismlog_msgQisMLogVersion ControlLog_msgScreen_msgVerbose_msgQisMLogV2Unlink_logRelink_log_file_pathRelink_log_file_ptrRelink_log_clientRelink_stdoutSet_verbose_levelVerbose_msg_levelLog_strScreen_strVerbose_strQisMLogV3ChannelsQisMLogV4Open_vector_logClose_vector_logQisMLog_debug_msg
Cast to a pointer of another version in the class hierarchy (base/derived)
Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>
The topmost base class is version 1 (V1 implied)
The cast returns NULL if a version number is not recognized/implemented
virtual void* QisMLogVector_cast(const int version) = 0;virtual const void* QisMLogVector_cast(const int version) const = 0;virtual int QisMLogVector_latest_version() const = 0;Get the file grid (in terms of file units)
xxxxxxxxxxvirtual double Grid() const = 0;Begin a new cell definition for
cellname
xxxxxxxxxxvirtual void Begin_cell(const char* cellname) = 0;Add a boundary to the vector log
xy is the list of x,y co-ordinates in database-units (DBU) or user-units (UU)
A DBU of 1 is equivalent to the file grid in meters. A UU of 1.0 is equivalent to the file units in meters
nv is the number of vertices (x,y pairs) in xy. Num. values in xy = nv*2
l, d are the layer and datatype numbers respectively
dx and dy are the offsets to the applied to xy in DBU or UU
This call is thread-safe (protected by a mutex)
xxxxxxxxxxvirtual void Boundary( const int* xy, const int nv, const unsigned short l, const unsigned short d, const int dx = 0, const int dy = 0 ) = 0;virtual void BoundaryUU( const double* xy, const int nv, const unsigned short l, const unsigned short d, const double dx = 0.0, const double dy = 0.0 ) = 0;Add a path to the vector log
xy is the list of x,y co-ordinates in database-units (DBU) or user-units (UU)
A DBU of 1 is equivalent to the file grid in meters. A UU of 1.0 is equivalent to the file units in meters
nv is the number of vertices (x,y pairs) in xy. Num. values in xy = nv*2
type can be R for round-ended, F for flush-ended or H for half-width extended paths
width is the path width in DBU or UU
l, d are the layer and datatype numbers respectively
dx and dy are the offsets to the applied to xy in DBU or UU
This call is thread-safe (protected by a mutex)
xxxxxxxxxxvirtual void Path( const int* xy, const int nv, const int width, const char type, const unsigned short l, const unsigned short d, const int dx = 0, const int dy = 0 ) = 0;virtual void PathUU( const double* xy, const int nv, const double width, const char type, const unsigned short l, const unsigned short d, const double dx = 0.0, const double dy = 0.0 ) = 0;Add a text to the vector log
text is the text string
x and y represent the insertion point in DBU
l, d are the layer and datatype numbers respectively
xxxxxxxxxxvirtual void Text(const char* text, const int x, const int y, const unsigned short l, const unsigned short d) = 0;Add a single reference to a cell
refname is the name of the cell to be referenced
x and y represent the insertion point DBU
scale, angle (degrees) and flip_y represent any scaling, rotation and mirroring respectively
xxxxxxxxxxvirtual void Sref(const char* refname, const int x, const int y, const double scale, const double angle, const bool flip_y) = 0;Add an arrayed reference to a cell
refname is the name of the cell to be referenced
x and y represent the insertion point DBU
col and row are the number of columns (nx) and rows (ny) respectively
col_dx, col_dy, row_dx and row_dy are the column and row offsets (pitches) in DBU along X and Y
scale, angle (degrees) and flip_y represent any scaling, rotation and mirroring respectively
xxxxxxxxxxvirtual void Aref( const char* refname, const int x, const int y, const int col, const int rows, const int col_dx, const int col_dy, const int row_dx, const int row_dy, const double scale, const double angle, const bool flip_y ) = 0;End the current cell definition
xxxxxxxxxxvirtual void End_cell() = 0;Represents a manager of log channels
A channel is a logical grouping of log messages usually associated with a specific module or a component
Channels can be registered (activated) via the environment variable ACS_VERBOSE_CH to a comma-separated list of names
A log message directed to a channel is only sent if that particular channel is in the list of channels
xxxxxxxxxxclass QisMLogChannels { ... };Cast to a pointer of another version in the class hierarchy (base/derived)
Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>
The topmost base class is version 1 (V1 implied)
The cast returns NULL if a version number is not recognized/implemented
xxxxxxxxxxvirtual void* QisMLogChannels_cast(const int version) = 0;virtual const void* QisMLogChannels_cast(const int version) const = 0;virtual int QisMLogChannels_latest_version() const = 0;Returns
trueif the specified channel is active and ON
xxxxxxxxxxvirtual bool Get_channel_onoff(const char* channel) const = 0;Send a message to a specific
channel(cannot be NULL or empty)
fmt is the format string (printf)
xxxxxxxxxxvirtual void Channel_msg(const char* channel, const char* fmt, ...) = 0;Send a message to a specific
channel(cannot be NULL or empty)
xxxxxxxxxxvirtual void Channel_str(const char* channel, const char* str) = 0;Client interface to receive log messages as callbacks (see
QISM_ARG_LOGCB
xxxxxxxxxxclass QisMLogCb { ... };Cast to a pointer of another version in the class hierarchy (base/derived)
Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>
The topmost base class is version 1 (V1 implied)
The cast returns NULL if a version number is not recognized/implemented
xxxxxxxxxxvirtual void* QisMLogCb_cast(const int version) = 0;virtual const void* QisMLogCb_cast(const int version) const = 0;virtual int QisMLogCb_latest_version() const = 0;Callback for a single log message in response to
QisMLog::Log_msgorQisMLog::Verbose_msg
xxxxxxxxxxvirtual int On_qismlog_msg(const char* msg, const bool infoOrWarning) { return 0; }API to write log messages (to stdout/stderr or a log file) throughout the QisMLib system.
This API can be used internally by QisMLib components, as well as externally by QisMLib extensions and clients.
In order for messages to appear on the console or in a file, the appropriate options QISM_ARG_NEWLOG, QISM_ARG_APNDLOG or QISM_ARG_STDLOG must be specified to ::QisMLib_initialize_once
This API can be accessed via the QisMLib::Get_extension_api method in QisMLib 3.10+
xxxxxxxxxxclass QisMLog: public QisMExtensionAPI { ... };Cast to a pointer of another version in the class hierarchy (base/derived)
Get the latest version number. Version numbers start at 1 and are reflected in the class name using the suffix V<number>. E.g <baseclass>V<version>
The topmost base class is version 1 (V1 implied)
The cast returns NULL if a version number is not recognized/implemented
xxxxxxxxxxvirtual void* QisMLog_cast(const int version) = 0;virtual const void* QisMLog_cast(const int version) const = 0;virtual int QisMLog_latest_version() const = 0;Write a message to screen (if enabled) and log file (if enabled) (multi-thread-safe)
err : if true, write to stderr. Otherwise, write to stdout
fmt : Format of the message as used by printf class of functions
xxxxxxxxxxvirtual void Log_msg(const bool err, const char* fmt, ...) = 0;Write a message only to screen (if enabled) (multi-thread-safe)
err : if true, write to stderr. Otherwise, write to stdout
fmt : Format of the message as used by printf class of functions
xxxxxxxxxxvirtual void Screen_msg(const bool err, const char* fmt, ...) = 0;Write a message to screen (if enabled) and log file (if enabled) only if the environment variable ACS_VERBOSE is set to ON (multi-thread-safe)
err : if true, write to stderr. Otherwise, write to stdout
fmt : Format of the message as used by printf class of functions
xxxxxxxxxxvirtual void Verbose_msg(const bool err, const char* fmt, ...) = 0;xxxxxxxxxxclass QisMLogV2: public QisMLog { ... };Un-link/release the log. Any subsequent log messages will be ignored
xxxxxxxxxxvirtual void Unlink_log() = 0;Re-link the log with a file,file handle,client or stdout
xxxxxxxxxxvirtual bool Relink_log_file_path(const char* file_path) = 0;virtual void Relink_log_file_ptr(FILE* file_ptr) = 0;virtual void Relink_log_client(QisMLogCb* handle) = 0;virtual void Relink_stdout(const bool onoff) = 0;Write a log message if the verbose level is >= specified level
ACS_VERBOSE can be set to the following:
ON (verbose level = 1)
OFF (verbose level = 0) (default)
ALL (verbose level = 32768)
{level} where 0 <= level < 32768
The verbose level can also be changed in code using Set_verbose_level
xxxxxxxxxxvirtual void Set_verbose_level(const int level) = 0;virtual void Verbose_msg_level(const bool err, const int level, const char* fmt, ...) = 0;Write a pre-formatted string (msg) to the log
xxxxxxxxxxvirtual void Log_str(const bool err, const char* msg) = 0;virtual void Screen_str(const bool err, const char* msg) = 0;virtual void Verbose_str(const bool err, const int level, const char* msg) = 0;xxxxxxxxxxclass QisMLogV3: public QisMLogV2 { ... };Get access to channel logs (if enabled by the env. var
ACS_VERBOSE_CH)
xxxxxxxxxxvirtual QisMLogChannels* Channels() = 0;virtual const QisMLogChannels* Channels() const = 0;xxxxxxxxxxclass QisMLogV4: public QisMLogV3 { ... };Create/Destroy a log file (GDSII) to write vectors
name is the log directory + name. Extension .gds is automatically added
units_m and grid_m are the units and grid in meters
On success, returns a handle to the log writer. It MUST be eventually closed to avoid resource leak
xxxxxxxxxxvirtual QisMLogVector* Open_vector_log(const char* name, const double units_m, const double grid_m) = 0;virtual void Close_vector_log(QisMLogVector* handle) = 0;Print messages to stderr ONLY from those compilation units where
ACS_ASSERT_ONis defined
This should be used for debugging and diagnostic messages that are enabled/disabled at compile time
This should be disabled in production binaries
xxxxxxxxxxLast Updated -- Wed Sep 30 00:52:18 UTC 2026