Mapper API class. More...

Static Public Member Methods
static *hash< auto >	getUserContextInfo ()
	returns a hash for the current user context

static auto	getGlobalConfigItemValue (string item, *hash< auto > local_context, bool expand_complex_values=True)
	returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

static auto	getGlobalConfigItemValueWithDefault (string item, auto default_value, *hash< auto > local_context, bool expand_complex_values=True)
	returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

static hash< auto >	getSystemInfo ()
	returns a hash of system info

static auto	getValueMap (string mapname, string key)
	Gets a lookup value from the value map by a key; the value map must be registered to the current interface.

static auto	expandTemplatedValue (auto value, *hash< auto > local_context, bool expand_complex_values=True)
	expands all variables in a templated string

static hash< auto >	propGet ()
	returns a hash of all system properties in all domains

static *hash< auto >	propGet (string domain)
	returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist

static auto	propGet (string domain, string key)
	returns the value of the given system property key in the given domain or NOTHING if the system property does not exist

static SqlUtil::AbstractTable	getSqlTable (string datasource, string table_name, bool register_dependency=True)
	get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

static SqlUtil::AbstractTable	getSqlTable (AbstractDatasource datasource, string table_name, bool register_dependency=True)
	get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

static	logFatal (softstring msg,...)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logError (softstring msg,...)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logWarn (softstring msg,...)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logInfo (softstring msg,...)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logDebug (softstring msg,...)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logTrace (softstring msg,...)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logArgsFatal (softstring msg, *softlist< auto > args)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logWithLevel (int level, string msg,...)
	Writes to the current interface log file with the given log level.

static	logWithLevelArgs (int level, string msg, *softlist< auto > args)
	Writes to the current interface log file with the given log level.

static	logArgsError (softstring msg, *softlist< auto > args)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logArgsWarn (softstring msg, *softlist< auto > args)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logArgsInfo (softstring msg, *softlist< auto > args)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logArgsDebug (softstring msg, *softlist< auto > args)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

static	logArgsTrace (softstring msg, *softlist< auto > args)
	Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Detailed Description

Mapper API class.

Since: Qorus 4.1

Member Function Documentation

◆ expandTemplatedValue()

static auto OMQ::MapperApi::MapperApi::expandTemplatedValue	(	auto	value,
		*hash< auto >	local_context,
		bool	expand_complex_values = `True`
	)

static

expands all variables in a templated string

Parameters

value	templated string to be expanded; see Config Item / Building Block Template Substitution Strings for more information on this parameter
local_context	local context supplied by the caller (plus user context info is added - see MapperApi::getUserContextInfo() method)
expand_complex_values	if True then lists and hashes will have their string values expanded recursively

Returns: the value of the string as substituted with all variables expanded recursively until there are no more expansions to perform (or the derived value is not a string)

Exceptions

LIST-VALUE-ERROR	cannot parse list value expression
REST-EXPRESSION-ERROR	cannot parse REST expression and argument
UNSUPPORTED-CONTEXT-ERROR	if an unknown context variable is specified to be expanded
FORMAT-ERROR	if the templated string doesn't have correct format (e.g. unescaped dollar sign that does not represent a variable)
SENSITIVE-DATA-FORMAT-ERROR	if the `"$sensitive:<skey>.<svalue>.field-ref..."` value or `"$sensitive-alias:<alias>.field-ref..."` template string does not have the required format

Since

Qorus 4.1.1 added the expand_complex_values argument

See also: Config Item / Building Block Template Substitution Strings

◆ getGlobalConfigItemValue()

static auto OMQ::MapperApi::MapperApi::getGlobalConfigItemValue	(	string	item,
		*hash< auto >	local_context,
		bool	expand_complex_values = `True`
	)

static

returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

Parameters

item	the name of the configuration item to retrieve the value
local_context	the caller can supply its "local" context for template variables (plus user context info is added - see MapperApi::getUserContextInfo() method)
expand_complex_values	if True then lists and hashes will have their string values expanded recursively

Returns: the value of the given configuration item on global level

Exceptions

CONFIG-ITEM-ERROR thrown if the configuration item is not valid

Note: the value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution

Since

Qorus 4.1.1 added the expand_complex_values argument

See also: getGlobalConfigItemValueWithDefault()

◆ getGlobalConfigItemValueWithDefault()

static auto OMQ::MapperApi::MapperApi::getGlobalConfigItemValueWithDefault	(	string	item,
		auto	default_value,
		*hash< auto >	local_context,
		bool	expand_complex_values = `True`
	)

static

returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

Parameters

item	the name of the configuration item to retrieve the value
default_value	the value to be returned if the value is not set
local_context	the caller can supply its "local" context for template variables (plus user context info is added - see MapperApi::getUserContextInfo() method)
expand_complex_values	if True then lists and hashes will have their string values expanded recursively

Returns: the value of the given global configuration item or default_value, if no value is set at the global level for the given configuration item

Note

the value is always substituted with UserApi::expandTemplatedValue()
if the config item is not set, default_value is returned after substitutions with UserApi::expandTemplatedValue()
make sure and escape any "$" characters with a backslash ("\") to avoid template substitution

Since

Qorus 4.1.1 added the expand_complex_values argument

See also: getGlobalConfigItemValue()

◆ getSqlTable() [1/2]

static SqlUtil::AbstractTable OMQ::MapperApi::MapperApi::getSqlTable	(	AbstractDatasource	datasource,
		string	table_name,
		bool	register_dependency = `True`
	)

static

get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

Parameters

datasource	a DatasourcePool object for a Qorus datasource; note that if the Qore::SQL::DatasourcePool object cannot be matched back to a known Qorus datasource, an `INVALID-DATASOURCE` exception will be thrown
table_name	the name of the table to be acquired; the handling of this parameter is identical to that in SqlUtil::Table::constructor(); names are converted to lower-case before performing the lookup and storage in the cache to ensure that the cache is based on case-insensitive lookups
register_dependency	if True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again

Returns: an SqlUtil::AbstractTable object corresponding to the parameters

Exceptions

INVALID-DATASOURCE this exception is thrown if the datasource argument cannot be matched to a known Qorus datasource

Note

INVALID-DATASOURCE exceptions can be thrown with a valid Qorus datasource if the given datasource has been reset since it was acquired
other exceptions can be thrown when acquiring the table, for example if the given table is not accessible or if there are technical errors communicating with the database server, etc
you need to call clear_sql_table_cache() any time the table structure has changed

Example:: SqlUtil::AbstractTable t = MapperApi::getSqlTable(datasource_pool, "my_table");

See also

Qorus SQL Object Cache

Since: Qorus 7.0

◆ getSqlTable() [2/2]

static SqlUtil::AbstractTable OMQ::MapperApi::MapperApi::getSqlTable	(	string	datasource,
		string	table_name,
		bool	register_dependency = `True`
	)

static

get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

Example:: SqlUtil::AbstractTable t = MapperApi::getSqlTable("my_datasource", "my_table");

Parameters

datasource	a Qorus datasource name
table_name	the name of the table to be acquired; the handling of this parameter is identical to that in SqlUtil::Table::constructor(); names are converted to lower-case before performing the lookup and storage in the cache to ensure that the cache is based on case-insensitive lookups
register_dependency	if True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again

Returns: an SqlUtil::AbstractTable object corresponding to the parameters

Exceptions

INVALID-DATASOURCE this exception is thrown if the datasource argument cannot be matched to a known datasource

Note

other exceptions can be thrown when acquiring the table, for example if the given table is not accessible or if there are technical errors communicating with the database server, etc
you need to call clear_sql_table_cache() any time the table structure has changed

See also

Qorus SQL Object Cache

Since: Qorus 7.0

◆ getSystemInfo()

static hash< auto > OMQ::MapperApi::MapperApi::getSystemInfo ( )

static

returns a hash of system info

Returns

a hash of system info with the following keys:

instance-key: value of the system option by the same name
session-id: the session ID for the current Qorus application session
omq-version: the version string for the Qorus server
omq-version-code: a numeric code of the Qorus server version, where
major = (x / 10000),

minor = (x / 100) % 100, = x % 100

this value is suitable for comparisons (ex: for Qorus 2.6.0, omq-version-code = 20600)
qore-version: the version string for the qore build used
datamodel-version: the datamodel version required by this version of Qorus
omq-schema: the datasource string for the system schema (without the password)
omquser-schema: the datasource string for the user schema (without the password)
starttime: the date and time when the instance was started
hostname: the hostname of the machine where the Qorus server is running
pid: the PID of the Qorus server process
threads: number of threads currently active
schema-properties: a hash of schema properties with the following keys:
omq-schema-version
omq-schema-compatibility
omq-load-schema-compatibility
logfile: the path for the system log file

◆ getUserContextInfo()

static *hash< auto > OMQ::MapperApi::MapperApi::getUserContextInfo ( )

static

returns a hash for the current user context

Example:: *hash<auto> h = MapperApi::getUserContextInfo();

Returns

a hash describing the current user context or NOTHING if called outside a workflow, service, or job; hash keys are as follows:

when called in a service:
- "type": "service"
- "servicetype": the type of service ("user" or "system")
- "name": the name of the service
- "version": the version of the service
- "id": the service id
- "context_user": the current username context, if any
when called in a job:
- "type": "job"
- "name": the name of the job
- "version": the version of the job
- "id": the job id
- "job_instanceid": the job_instanceid of the current job instance
- "context_user": the current username context, if any
when called in a workflow:
- "type": "workflow"
- "name": the name of the workflow
- "version": the version of the workflow
- "id": the workflow id
- "workflow_instanceid": the workflow_instanceid of the current workflow instance (if available)
- "stepname": the name of the current step (if available)
- "stepversion": the version of the current step (if available)
- "stepid": the id of the current step (if available)
- "ind": the name of the current step index (if available)
- "execid": the execution ID of the current workflow execution instance (if available)
- "context_user": the current username context, if any

◆ getValueMap()

static auto OMQ::MapperApi::MapperApi::getValueMap	(	string	mapname,
		string	key
	)

static

Gets a lookup value from the value map by a key; the value map must be registered to the current interface.

Parameters

mapname	name of the value map
key	a key name

Returns: the value assigned to the key

Exceptions

VALUE-MAP-ERROR the given value map is unknown or not registered to the current interface

◆ logArgsDebug()

static OMQ::MapperApi::MapperApi::logArgsDebug	(	softstring	msg,
		*softlist< auto >	args
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments
args	the arguments for the format string msg

See also: UserApi::logDebug()

Since: Qorus 7.0

◆ logArgsError()

static OMQ::MapperApi::MapperApi::logArgsError	(	softstring	msg,
		*softlist< auto >	args
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments
args	the arguments for the format string msg

See also: UserApi::logError()

Since: Qorus 7.0

◆ logArgsFatal()

static OMQ::MapperApi::MapperApi::logArgsFatal	(	softstring	msg,
		*softlist< auto >	args
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments
args	the arguments for the format string msg

See also: UserApi::logFatal()

Since: Qorus 7.0

◆ logArgsInfo()

static OMQ::MapperApi::MapperApi::logArgsInfo	(	softstring	msg,
		*softlist< auto >	args
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments
args	the arguments for the format string msg

See also: UserApi::logInfo()

Since: Qorus 7.0

◆ logArgsTrace()

static OMQ::MapperApi::MapperApi::logArgsTrace	(	softstring	msg,
		*softlist< auto >	args
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments
args	the arguments for the format string msg

See also: UserApi::logTrace()

Since: Qorus 7.0

◆ logArgsWarn()

static OMQ::MapperApi::MapperApi::logArgsWarn	(	softstring	msg,
		*softlist< auto >	args
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments
args	the arguments for the format string msg

See also: UserApi::logWarn()

Since: Qorus 7.0

◆ logDebug()

static OMQ::MapperApi::MapperApi::logDebug	(	softstring	msg,
			...
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments

See also: UserApi::logArgsDebug()

Since: Qorus 7.0

◆ logError()

static OMQ::MapperApi::MapperApi::logError	(	softstring	msg,
			...
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments

See also: UserApi::logArgsError()

Since: Qorus 7.0

◆ logFatal()

static OMQ::MapperApi::MapperApi::logFatal	(	softstring	msg,
			...
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments

See also: UserApi::logArgsFatal()

Since: Qorus 7.0

◆ logInfo()

static OMQ::MapperApi::MapperApi::logInfo	(	softstring	msg,
			...
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments

See also: UserApi::logArgsWarn()

Since: Qorus 7.0

◆ logTrace()

static OMQ::MapperApi::MapperApi::logTrace	(	softstring	msg,
			...
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments

See also: UserApi::logTrace()

Since: Qorus 7.0

◆ logWarn()

static OMQ::MapperApi::MapperApi::logWarn	(	softstring	msg,
			...
	)

static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters

msg	the format string for a vsprintf() call with the remaining arguments

See also: UserApi::logArgsWarn()

Since: Qorus 7.0

◆ logWithLevel()

static OMQ::MapperApi::MapperApi::logWithLevel	(	int	level,
		string	msg,
			...
	)

static

Writes to the current interface log file with the given log level.

Parameters

level	log levels as defined by Logger::LoggerLevel
msg	the format string for the log message, arguments follow

Since: Qorus 7.0

◆ logWithLevelArgs()

static OMQ::MapperApi::MapperApi::logWithLevelArgs	(	int	level,
		string	msg,
		*softlist< auto >	args
	)

static

Writes to the current interface log file with the given log level.

Parameters

level	log levels as defined by Logger::LoggerLevel
msg	the format string for the log message
args	optional argument to format specifiers in msg

Since: Qorus 7.0

◆ propGet() [1/3]

static hash< auto > OMQ::MapperApi::MapperApi::propGet ( )

static

returns a hash of all system properties in all domains

Example:: hash<auto> h = MapperApi::propGet();

Returns: a hash of all system properties in all domains; the top-level keys are domain keys which have as values hashes with all key-value pairs set in the domain

◆ propGet() [2/3]

static *hash< auto > OMQ::MapperApi::MapperApi::propGet ( string domain )

static

returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist

Example:: *hash<auto> h = MapperApi::propGet(domain);

Returns: a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist

◆ propGet() [3/3]

static auto OMQ::MapperApi::MapperApi::propGet	(	string	domain,
		string	key
	)

static

returns the value of the given system property key in the given domain or NOTHING if the system property does not exist

Example:: auto val = MapperApi::propGet(domain, key);

Returns: the value of the given system property key in the given domain

The documentation for this class was generated from the following file:

MapperApi.qc

Static Public Member Methods

Detailed Description

Member Function Documentation

◆ expandTemplatedValue()

◆ getGlobalConfigItemValue()

◆ getGlobalConfigItemValueWithDefault()

◆ getSqlTable() [1/2]

◆ getSqlTable() [2/2]

◆ getSystemInfo()

◆ getUserContextInfo()

◆ getValueMap()

◆ logArgsDebug()

◆ logArgsError()

◆ logArgsFatal()

◆ logArgsInfo()

◆ logArgsTrace()

◆ logArgsWarn()

◆ logDebug()

◆ logError()

◆ logFatal()

◆ logInfo()

◆ logTrace()

◆ logWarn()

◆ logWithLevel()

◆ logWithLevelArgs()

◆ propGet() [1/3]

◆ propGet() [2/3]

◆ propGet() [3/3]