user API namespace root More...

Namespaces
	Job
	Qorus job API namespace.

	Service
	Qorus service API namespace.

	Workflow
	Qorus workflow API namespace.

Functions
public deprecated any	getOracleNumber (any $v)

public deprecated any	getSQLNumber (any $v)

public any	get_sql_number (any $v)
	returns either the value returned or the string "NULL" if the type cannot be converted to a number More...

public deprecated string	getOracleString (any $v, int $size=0)

public deprecated string	getSQLString (any $v, int $size=0)

public string	get_sql_string (any $v, int $size=0)
	returns a singly-quoted string aimed to be directly usable in dynamic SQL queries with single quote (\') characters escaped or returns the string "NULL" if the argument type is not int, float, bool, or string More...

public string	fix_quotes (string $str)
	doubles single quotes (\') in strings and returns the new string More...

public string	fix_quotes (reference $str)
	doubles single quotes (\') in strings and returns the new string More...

public string	make_select_list (any $list)
	returns a string based on a list, processed for the values in the list to be used in an SQL string with an Oracle DB More...

public string	make_select_list2 (any $driver, any $list)
	returns a string based on a list, processed for the values in the list to be used in a dynamic SQL string More...

public list	remove_from_list (list $list, any $val)
	uses the select operator to remove all occurences of a value from a list More...

public list	remove_from_list (reference $list, any $val)
	uses the select operator to remove all occurences of a value from a list More...

public deprecated list	remove_from_list_index (list $list, int $index)
	DEPRECATED: remove an element from a list. More...

public string	oracle_date (date $date)
	returns a string from a date suitable for use in a dynamic oracle SQL string More...

public string	db_date (string $driver, date $date)
	returns a string from a date suitable for use in a dynamic SQL string depending on the driver More...

public string	create_sql_string ()
	DEPRECATED: returns a string suitable for use in a dyanamic Oracle SQL query string based on the arguments passed. More...

public string	create_sql_string2 (any $driver)
	returns a string suitable for use in a dynamic SQL query string (driver-dependent) based on the arguments passed More...

public string	xml_change_encoding (string $xml, string $enc)
	returns a string with the XML encoding name changed to that given as an argument More...

public string	xml_get_encoding (string $xml)
	returns the XML encoding name given in the string (not the actual string encoding, which may be different)

public deprecated bool	parseBoolean (any $v)

public string	getExceptionString (hash $ex)

public int	compareVersion (string $lv, string $rv)
	by Util::compare_version()

public string	serialize_qorus_data (any $d)
	returns a string giving the default serialization of the given data structure for storage in Qorus More...

public any	deserialize_qorus_data (string $data)
	parses serialized data in either XML-RPC or YAML format and returns the corresponding qore data More...

public string	get_salted_string (string $str, binary $salt)
	returns a string that has been x-ored with binary "salt" data

public softint	next_sequence_value (Datasource $ds, string $name)
	returns the next sequence value for the given sequence

public softint	next_sequence_value (DatasourcePool $ds, string $name)
	returns the next sequence value for the given sequence

*hash	get_user_service_info (string $name)
	returns information about the given user service (if it's currently loaded) More...

*hash	get_system_service_info (string $name)
	returns information about the given system service (if it's currently loaded) More...

*hash	get_service_info (string $type, string $name)
	returns information about the given service (if it's currently loaded) More...

list	get_running_workflow_list (string $name, string $ver)
	returns a list of hashes giving information about the currently-running workflow execution instances More...

hash	get_running_workflow_info (softint $id)
	returns a hash of the workflow execution instance info if the ID is valid or an empty hash if not More...

softstring	create_order (string $name, *string $version, hash $params, string $status=StatReady)
	creates a workflow order data instance in the database More...

hash	exec_synchronous_workflow (string $name, string $version, hash $sdata, hash $opts, hash $ddata, softint $priority=DefaultOrderPriority, hash $orderkeys, softstring $external_order_instanceid, softint $parent_workflow_instanceid)
	executes a workflow order synchronously and returns the final status and order ID in a hash More...

int	post_user_event (string $severity, any $info)
	posts an application event of class QE_CLASS_USER More...

hash	runtime_properties ()
	returns Qorus runtime properties as a hash More...

any	call_network_api_args_with_authentication (string $user, string $pass, string $call, softlist $args)
	calls a system API with authentication information (username and password) More...

any	call_network_api_args (string $call, softlist $args)
	calls a system API with the argument list to the API method as a top-level argument to this function More...

any	call_network_api (string $call)
	calls a system API and returns the result More...

hash	get_system_info ()
	returns a hash of system info More...

int	get_session_id ()
	returns the current Qorus application session ID More...

	log (softint $lvl, softstring $msg)
	Saves the information passed to the workflow, service, job, or system log file depending on the calling context if the log level passed is equal to or lower than value of the system option verbose. More...

*int	audit_user_event (string $user_event, string $info1, string $info2)
	creates a user audit event (with audit event code AE_USER_EVENT) against the workflow, service, or job instance More...

bool	audit_check_event_string (string $opt)
	checks if the given audit event (given as a string) is enabled More...

bool	audit_check_event (softint $opt)
	checks if the given audit event (given as an integer code) is enabled More...

int	audit_get_mask ()
	returns the audit event mask More...

int	omqsleep (softint $arg)
	puts the current thread to sleep for a certain number of seconds More...

int	omqusleep (softint $arg)
	puts the current thread to sleep for a certain number of microseconds More...

any	get_qorus_options ()
	returns the value of the given system option or options More...

hash	get_qorus_option_info ()
	returns a hash giving information about system options More...

any	get_qorus_options_args (softlist $args)
	returns the value of the given system option or options More...

hash	get_qorus_option_info_args (softlist $args)
	returns a hash giving information about system options More...

hash	get_active_jobs ()
	Returns information on all active jobs visible to the calling user. More...

object	get_user_connection (string $name, bool $connect=True, bool $register_dependency=True, *hash $rtopts)
	Returns an object corresponding to a defined user connection. More...

Qore::SQL::Datasource	get_datasource_shared (string $name, bool $register_dependency=True)
	Returns a shared Datasource object with autocommit turned on from the given datasource name. More...

Qore::SQL::Datasource	get_datasource_dedicated (string $name, bool $register_dependency=True)
	returns a new, dedicated Datasource object, suitable for transaction management for long-running transactions More...

Qore::SQL::DatasourcePool	get_datasource_pool (string $name, bool $register_dependency=True)
	returns a DatasourcePool object for the given datasource name More...

hash	get_datasource_info (string $name)
	returns a hash of datasource information for the given datasource, if known, otherwise throws an exception More...

QorusSystemAPIHelper	get_remote_rpc_connection (string $name, bool $connect=True, bool $register_dependency=True)
	Returns a new QorusSystemAPIHelper object corresponding to a defined Qorus <-> Qorus remote connection. More...

QorusSystemRestHelper	get_remote_rest_connection (string $name, bool $connect=True, bool $register_dependency=True)
	Returns a new QorusSystemRestHelper object corresponding to a defined Qorus <-> Qorus remote REST connection. More...

	raise_transient_alert (string $alert, string $reason, *hash $info)
	raises a transient system alert from a workflow, service, or job More...

string	qorus_get_local_url (string $username, string $password)
	returns a string giving the local system URL More...

	set_option (hash $hash)
	Changes option values on a workflow, service, or job. More...

any	get_option ()
	Returns the value of the named workflow, service, or job option or options. More...

	block_order (softint $wfiid)
	block the given workflow order data instance More...

	unblock_order (softint $wfiid, *hash $tempdata)
	unblocks the given workflow order data instance More...

	cancel_order (softint $wfiid)
	cancel the given workflow order data instance More...

	uncancel_order (softint $wfiid, *hash $tempdata)
	uncancels the given workflow order data instance More...

deprecated any	getOption ()

deprecated	setOption (hash $hash)

*hash	getSystemServiceInfo (string $name)

*hash	getUserServiceInfo (string $name)

list	getRunningWorkflowList ()

hash	getRunningWorkflowInfo (softint $id)

softstring	createOrder (string $name, *string $version, hash $params, string $status=StatReady)

hash	runtimeProperties ()

hash	execSynchronousWorkflow (string $name, string $version, hash $sdata, hash $opts, hash $ddata, softint $priority=DefaultOrderPriority, hash $orderkeys, softstring $external_order_instanceid, softint $parent_workflow_instanceid)

any	callNetworkAPIArgsWithAuthentication (string $user, string $pass, string $call, softlist $args)

any	callNetworkAPIArgs (string $call, softlist $args)

any	callNetworkAPI (string $call, softlist $args)

hash	getSystemInfo ()

int	getSessionID ()

Detailed Description

user API namespace root

Function Documentation

bool OMQ::UserApi::audit_check_event ( softint $opt )

checks if the given audit event (given as an integer code) is enabled

Parameters

$opt	the audit event code to check; see Audit Event Codes for possible values

Returns: True if the event is audited, False if not

Since: Qorus 2.6.2

bool OMQ::UserApi::audit_check_event_string ( string $opt )

checks if the given audit event (given as a string) is enabled

Parameters

$opt	the audit event code to check; see Audit Event Strings for possible values

Returns: True if the event is audited, False if not

Exceptions

AUDIT-EVENT-ERROR the given audit event string does not exist

Since: Qorus 2.6.2

int OMQ::UserApi::audit_get_mask ( )

returns the audit event mask

Returns: the audit event mask

Since: Qorus 2.6.2

*int OMQ::UserApi::audit_user_event	(	string	$user_event,
		*string	$info1,
		*string	$info2
	)

creates a user audit event (with audit event code AE_USER_EVENT) against the workflow, service, or job instance

Parameters

$user_event	the user event code string
$info1	optional informational string for the `AUDIT_EVENTS.INFO1` field
$info2	optional informational string for the `AUDIT_EVENTS.INFO2` field

Returns: NOTHING if user event auditing is not enabled (see system option audit), or the integer audit event id

Note: nothing will be written to the AUDIT_EVENTS table if the audit system option does not include the "user-events" (AO_USER_EVENTS) option; in case this is not set, the call will have no effect

Since: Qorus 2.6.2

OMQ::UserApi::block_order ( softint $wfiid )

block the given workflow order data instance

Parameters

$wfiid the workflow order instance ID to block

Returns

a hash with the following key:

workflow_status: the status of the workflow order

An exception will be thrown if the status is OMQ::StatInProgress

Exceptions

BLOCK-WORKFLOW-ERROR invalid status, foreign session id, missing original status, uncancel operation already in progress

Since: Qorus 3.0.4.p2

any OMQ::UserApi::call_network_api ( string $call )

calls a system API and returns the result

include any arguments after the method name, ex:

callNetworkAPI("omq.system.exec-synchronous-existing", ("workflow_instanceid": $wfiid));

Parameters

$call the full api method name (ex: "omq.system.exec-synchronous-exiting"); see Network System API for a full list

Returns: the return value of the method

See also: callNetworkAPIArgsWithAuthentication(); callNetworkAPIArgs()

Exceptions

UNKNOWN-API-CALL	invalid API method
INVALID-INTERNAL-API-CALL	API may not be called internally (ex: omq.system.shutdown-wait())

Since: Qorus 2.6.3.p43 restrictions on calling certain API methods (including service methods) were removed

Note: prior to Qorus 3.0.2 this function was known as callNetworkAPI(), and is still imported with this old camel-case name for backwards compatibility

any OMQ::UserApi::call_network_api_args	(	string	$call,
		softlist	$args
	)

calls a system API with the argument list to the API method as a top-level argument to this function

Parameters

$call	the full api method name (ex: `"omq.system.exec-synchronous-exiting"`); see Network System API for a full list
$args	any arguments to the method; if multiple argument should be passed to the method, use a list of arguments here

Returns: the return value of the method

See also: callNetworkAPIArgsWithAuthentication(); callNetworkAPI()

Exceptions

UNKNOWN-API-CALL	invalid API method
INVALID-INTERNAL-API-CALL	API may not be called internally (ex: omq.system.shutdown-wait())

Since: Qorus 2.6.3.p43 restrictions on calling certain API methods (including service methods) were removed

Note: prior to Qorus 3.0.2 this function was known as callNetworkAPIArgs(), and is still imported with this old camel-case name for backwards compatibility

any OMQ::UserApi::call_network_api_args_with_authentication	(	string	$user,
		string	$pass,
		string	$call,
		softlist	$args
	)

calls a system API with authentication information (username and password)

Parameters

$user	the username to use for the call
$pass	the password to use for the call
$call	the full api method name (ex: `"omq.system.exec-synchronous-exiting"`); see Network System API for a full list
$args	any arguments to the method; if multiple argument should be passed to the method, use a list of arguments here

Returns: the return value of the method

See also: callNetworkAPIArgs(); callNetworkAPI()

Exceptions

UNKNOWN-API-CALL	invalid API method
INVALID-INTERNAL-API-CALL	API may not be called internally (ex: omq.system.shutdown-wait())

Since: Qorus 2.6.3.p43 restrictions on calling certain API methods (including service methods) were removed

Note: prior to Qorus 3.0.2 this function was known as callNetworkAPIArgsWithAuthentication(), and is still imported with this old camel-case name for backwards compatibility

any OMQ::UserApi::callNetworkAPI	(	string	$call,
		softlist	$args
	)

Deprecated:: by call_network_api()

any OMQ::UserApi::callNetworkAPIArgs	(	string	$call,
		softlist	$args
	)

Deprecated:: by call_network_api_args()

any OMQ::UserApi::callNetworkAPIArgsWithAuthentication	(	string	$user,
		string	$pass,
		string	$call,
		softlist	$args
	)

Deprecated:: by call_network_api_args_with_authentication()

OMQ::UserApi::cancel_order ( softint $wfiid )

cancel the given workflow order data instance

Parameters

$wfiid the workflow order instance ID to cancel

Returns

a hash with the following key:

workflow_status: the status of the workflow order

An exception will be thrown if the status is OMQ::StatInProgress

Exceptions

CANCEL-WORKFLOW-ERROR invalid status, foreign session id, missing original status, uncancel operation already in progress

Since: Qorus 3.0.4.p2

softstring OMQ::UserApi::create_order	(	string	$name,
		*string	$version,
		hash	$params,
		string	$status = `StatReady`
	)

creates a workflow order data instance in the database

Creates a workflow order data instance of the specified type with the data passed

Parameters

$name	the name of the workflow
$version	the version of the workflow; if this parameter is not passed, then the latest version of the workflow (determined by the latest created date for the workflow_instance entry) will be used
$params	The hash passed must have at either a `staticdata` key or an `external_order_instanceid` key, valid keys: `staticdata:` the initial static data for the order `dynamicdata:` the initial dynamic data for the order `tempdata:` the initial temporary data for the order `external_order_instanceid:` the external order instance ID for the workflow data `orderkeys:` a hash of order keys for the order `scheduled:` the earliest date and time the order can be processed; if this date is given as a future date/time value and a StatReady status is given, then the initial status of the workflow order data instance will be automatically changed to StatScheduled instead of StatReady `priority:` the order priority (default DefaultOrderPriority) from 0 - 999; priority 0 is the highest; 999 is the lowest `parent_workflow_instanceid:` a loosely-coupled workflow that will be marked as the parent of this workflow; if this key is not set, and this function is called from workflow code (even indirectly, by calling a service method that calls this function in the same thread as the call from workflow code), the new order will be loosely-coupled with the calling workflow order as the parent; to keep this from happening, set the value of this key to `False`
$status	create the workflow order data instance with this status; may be either: StatReady which is the default value StatBlocked meaning: do not process the order, wait for unblocking later

Returns: the workflow instance ID created (returned as a string)

Exceptions

SUBMIT-DATA-ERROR unknown workflow, invalid status

Note: prior to Qorus 3.0.2 this function was known as createOrder(), and is still imported with this old camel-case name for backwards compatibility

Since: Qorus 3.0.4.p2 this function accepts the tempdata key

public string OMQ::UserApi::create_sql_string ( )

DEPRECATED: returns a string suitable for use in a dyanamic Oracle SQL query string based on the arguments passed.

Deprecated:: Oracle-specific; use create_sql_string2() instead

Note: : use of dynamic SQL is discouraged; use bind by value instead

public string OMQ::UserApi::create_sql_string2 ( any $driver )

returns a string suitable for use in a dynamic SQL query string (driver-dependent) based on the arguments passed

Note: : use of dynamic SQL is discouraged; use bind by value instead

softstring OMQ::UserApi::createOrder	(	string	$name,
		*string	$version,
		hash	$params,
		string	$status = `StatReady`
	)

Deprecated:: by create_order()

public string OMQ::UserApi::db_date	(	string	$driver,
		date	$date
	)

returns a string from a date suitable for use in a dynamic SQL string depending on the driver

Note: : use of dynamic SQL is discouraged; use bind by value instead

public any OMQ::UserApi::deserialize_qorus_data ( string $data )

parses serialized data in either XML-RPC or YAML format and returns the corresponding qore data

auto-detects XML-RPC or YAML decoding

Parameters

$data the string data to deserialize

Returns: the Qore data represented by the string arugment

hash OMQ::UserApi::exec_synchronous_workflow	(	string	$name,
		*string	$version,
		hash	$sdata,
		*hash	$opts,
		*hash	$ddata,
		softint	$priority = `DefaultOrderPriority`,
		*hash	$orderkeys,
		*softstring	$external_order_instanceid,
		*softint	$parent_workflow_instanceid
	)

executes a workflow order synchronously and returns the final status and order ID in a hash

Parameters

$name	the workflow name
$version	the workflow version (if NOTHING then the latest version of the workflow will be used)
$sdata	the static data hash for the workflow order
$opts	the options for the synchronous workflow execution instance
$ddata	the optional initial dynamic data hash for the workflow order
$priority	the order priority for the order
$orderkeys	optional order keys for the order
$external_order_instanceid	the optional external order instanceid for the order
$parent_workflow_instanceid	an optional loosely-coupled workflow order ID that will be marked as the parent of this order; if this key is not set, and this function is called from workflow code (even indirectly, by calling a service method that calls this function in the same thread as the call from workflow code), the new order will be loosely-coupled with the calling workflow order as the parent; to keep this from happening, set the value of this key to `False`

Returns

a hash of workflow order information with the following keys:

workflow_instanceid: the workflow order instance ID
status the order status commit to the database (for possible values, see Workflow, Segment, and Step Status Descriptions)

Since: Qorus 2.6.3.p28 the version parameter may be NOTHING, meaning take the latest version

Note: prior to Qorus 3.0.2 this function was known as execSynchronousWorkflow(), and is still imported with this old camel-case name for backwards compatibility

hash OMQ::UserApi::execSynchronousWorkflow	(	string	$name,
		*string	$version,
		hash	$sdata,
		*hash	$opts,
		*hash	$ddata,
		softint	$priority = `DefaultOrderPriority`,
		*hash	$orderkeys,
		*softstring	$external_order_instanceid,
		*softint	$parent_workflow_instanceid
	)

Deprecated:: by exec_synchronous_workflow()

public string OMQ::UserApi::fix_quotes ( string $str )

doubles single quotes (\') in strings and returns the new string

Note: : use of dynamic SQL is discouraged; use bind by value instead

public string OMQ::UserApi::fix_quotes ( reference $str )

doubles single quotes (\') in strings and returns the new string

Note: : use of dynamic SQL is discouraged; use bind by value instead

hash OMQ::UserApi::get_active_jobs ( )

Returns information on all active jobs visible to the calling user.

If any active jobs are not accessible to the calling user, then they are filtered from the hash returned.

Returns

a hash is keyed by job name; the hash values are job information hashes with the following keys:

jobid: the metadata jobid of the job type
name: the job name
version: the job version
description: the job description
trigger: a string describing the timer/trigger for the job
[job_instanceid]: the id of the job instance (will only have a value if the job is currently executing)
[last_executed]: the last executed date/time of the job (NOTHING if not yet executed)
[expiry_date]: the expiry date of the job, if any; if this date is present, then the job will not run automatically after this date
single_instance: True if the job can only be run in a single Qorus instance, False if no such restriction is enabled
[next]: the next trigger date/time; this key is only included if the job is active
active: this value is always True because this API only returns information about active jobs

Since: Qorus 2.8.1.p4

Qore::SQL::Datasource OMQ::UserApi::get_datasource_dedicated	(	string	$name,
		bool	$register_dependency = `True`
	)

returns a new, dedicated Datasource object, suitable for transaction management for long-running transactions

Parameters

$name	the name of the datasource
$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: a new, dedicated Datasource object, suitable for transaction management for long-running transactions

Exceptions

DATASOURCE-ERROR The given connection is not known or is a system datasource

See also: get_datasource_pool(); get_datasource_shared()

Since: Qorus 3.0

hash OMQ::UserApi::get_datasource_info ( string $name )

returns a hash of datasource information for the given datasource, if known, otherwise throws an exception

Parameters

$name the name of the datasource

Returns

a hash of datasource information for the given datasource, if known, otherwise throws an exception; the following keys are returned in the hash:

name (string): the name of the connection
type (string): the DBI driver providing the DB connection
user (string): the username for the connection, if any
pass (string): the password for the connection, if any
charset (string): the DB-specific character encoding for the connection
db (string): The database name of the connection
options (hash): an optional hash of options for the DBI driver for this connection; also "min" and "max" for the DatasourcePool minimum and maximum options
locked (bool): a flag indicating if the datasource is locked or not (the system datasource "omq" is locked)
up (bool): a flag indicating if monitoring has discovered if the datasource is up or not
desc (string): a string description of the datasource without the password
desc_pwd (string): a string description of the datasource with the password (can be passed to the Datasource and DatasourcePool constructor, for example)
monitor (bool): a flag indicating if the datasource is monitored or not
status (string): "OK" if the datasource is up or an error string if the datasource is down; set by monitoring
last_check (date/time): the date and time of the last monitoring check
shared_pool (string): a string giving the pool state (only present if a pool has been initialized on the datasource)
deps (list): a list of hashes giving interface objects that depend on the connection; each entry is a hash with the following keys:
type: "WORKFLOW", "SERVICE", or "JOB"
workflowid: for workflows, gives the workflow ID
serviceid: for services, gives the service ID
jobid: for jobs, gives the job ID
name: the name of the workflow, service, or job
version: the version of the workflow, service, or job
desc: a string description of the object

Exceptions

DATASOURCE-ERROR unknown datasource

Since: Qorus 3.0

Qore::SQL::DatasourcePool OMQ::UserApi::get_datasource_pool	(	string	$name,
		bool	$register_dependency = `True`
	)

returns a DatasourcePool object for the given datasource name

Parameters

$name	the name of the datasource
$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: a DatasourcePool object

Exceptions

DATASOURCE-ERROR unknown or system datasource

See also: get_datasource_shared(); get_datasource_dedicated()

Since: Qorus 3.0

Qore::SQL::Datasource OMQ::UserApi::get_datasource_shared	(	string	$name,
		bool	$register_dependency = `True`
	)

Returns a shared Datasource object with autocommit turned on from the given datasource name.

Parameters

$name	the name of the datasource
$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: a shared Datasource object with autocommit turned on

Exceptions

DATASOURCE-ERROR The given connection is not known or is a system datasource

See also: get_datasource_pool(); get_datasource_dedicated()

Since: Qorus 3.0

any OMQ::UserApi::get_option ( )

Returns the value of the named workflow, service, or job option or options.

If the option is not set on the workflow, service, or job level (depending on the calling context) and it is a valid system option, then the value of the system option will be returned.

Returns: the value requested directly if only one argument is passed, otherwise a hash of option keys and values; note that if called from a workflow and no arguments are passed to the function all workflow-level options are returned as a hash

Note

when called from workflow code, invalid options do not cause an errors to be raised; the associated key values in the hash returned will be NOTHING
prior to Qorus 3.0.2 this function was known as setOption(), and is still imported with this old camel-case name for backwards compatibility

hash OMQ::UserApi::get_qorus_option_info ( )

returns a hash giving information about system options

Since: Qorus 2.8.1.p3

hash OMQ::UserApi::get_qorus_option_info_args ( softlist $args )

returns a hash giving information about system options

Since: Qorus 2.8.1.p3

any OMQ::UserApi::get_qorus_options ( )

returns the value of the given system option or options

Since: Qorus 2.8.1.p3

any OMQ::UserApi::get_qorus_options_args ( softlist $args )

returns the value of the given system option or options

Since: Qorus 2.8.1.p3

QorusSystemRestHelper OMQ::UserApi::get_remote_rest_connection	(	string	$name,
		bool	$connect = `True`,
		bool	$register_dependency = `True`
	)

Returns a new QorusSystemRestHelper object corresponding to a defined Qorus <-> Qorus remote REST connection.

Parameters

$name	the name of the connection
$connect	if False an unconnected object will be returned, otherwise the object is already connected
$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: a new QorusSystemRestHelper object

Exceptions

GET-REMOTE-ERROR The given connection is not known

Since: Qorus 3.0

QorusSystemAPIHelper OMQ::UserApi::get_remote_rpc_connection	(	string	$name,
		bool	$connect = `True`,
		bool	$register_dependency = `True`
	)

Returns a new QorusSystemAPIHelper object corresponding to a defined Qorus <-> Qorus remote connection.

Parameters

$name	the name of the connection
$connect	if False an unconnected object will be returned, otherwise the object is already connected
$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: a new QorusSystemAPIHelper object

Exceptions

GET-REMOTE-ERROR The given connection is not known

Since: Qorus 3.0

hash OMQ::UserApi::get_running_workflow_info ( softint $id )

returns a hash of the workflow execution instance info if the ID is valid or an empty hash if not

returns an empty hash if the workflow execution ID is not currently valid

Parameters

$id	workflow execution instance id

Returns

a hash of the workflow execution instance info if the ID is valid or an empty hash if not; if valid, the hash will have the following keys:

name: the name of the workflow
version: version of the workflow
workflowid: the workflowid of the workflow
executionID: the workflow execution instance id (same as the argument)
mode: WM_Normal, WM_Recovery, WM_Synchronous
status: WISInitializing, WISRunning, WISWaiting, WISStopping
iterations: number of segment iterations performed so far
totalSegments: number of segments executed
errors: total number of errors encountered
warnings: total number of warnings raised
starttime: date/time the execution instance was started
options: options set on the workflow execution instance
logfile: log file name

See also: get_running_workflow_list()

Note: prior to Qorus 3.0.2 this function was known as getRunningWorkflowInfo(), and is still imported with this old camel-case name for backwards compatibility

list OMQ::UserApi::get_running_workflow_list	(	*string	$name,
		*string	$ver
	)

returns a list of hashes giving information about the currently-running workflow execution instances

Parameters

$name	optional workflow name for filtering the result list
$ver	optional workflow version for filtering the result list (only used if name also passed)

Returns

a list of hashes giving information about the currently-running workflow execution instances; if no matching workflow execution instances are running, then an empty list is returned; otherwise each list element is a hash with the following keys:

executionID: the workflow execution instance id
- name: the name of the workflow
- version: version of the workflow
- workflowid: the workflowid of the workflow
- mode: WM_Normal, WM_Recovery, WM_Synchronous
- status: WISInitializing, WISRunning, WISWaiting, WISStopping
- iterations: number of segment iterations performed so far
- totalSegments: number of segments executed
- errors: total number of errors encountered
- warnings: total number of warnings raised
- starttime: date/time the execution instance was started
- options: options set on the workflow execution instance
- logfile: log file name

Note: prior to Qorus 3.0.2 this function was known as getRunningWorkflowList(), and is still imported with this old camel-case name for backwards compatibility

*hash OMQ::UserApi::get_service_info	(	string	$type,
		string	$name
	)

returns information about the given service (if it's currently loaded)

to get information about services whether they are loaded or not, call:

$omqservice.system.omqmap.lookupserviceinfo(<type>, <name>)

Parameters

$type	the type of service (either `"system"` or `"user"`; case is ignored)
$name	the name of the system service to query

Returns

a hash of service information or NOTHING if the service is not loaded; the hash will have the following structure:

type: either "system" or "user" corresponding to the argument
name: the name of the service
version: version of the service
desc: description of the service
serviceid: service ID
status: SSRunning or SSLoaded
threads: number of running threads in the service
autostart: True of False if the autostart flag is set
loaded: date/time the service was loaded
methods: list of hashes for each method with name and desc keys

int OMQ::UserApi::get_session_id ( )

returns the current Qorus application session ID

Returns: the current Qorus application session ID

See also: Application Session Model for more information about the session ID

Note: prior to Qorus 3.0.2 this function was known as getSessionID(), and is still imported with this old camel-case name for backwards compatibility

public any OMQ::UserApi::get_sql_number ( any $v )

returns either the value returned or the string "NULL" if the type cannot be converted to a number

this function is designed to be used to directly put values in an SQL query that should be of NUMBER/NUMERIC/DECIMAL type

Parameters

$v	the value to use a number in an SQL query

Returns: the value passed if the value is one of the following types: int, float, bool, string, or the string "NULL" if not

Note: the use of dynamic SQL is discouraged; use bind by value instead

public string OMQ::UserApi::get_sql_string	(	any	$v,
		int	$size = `0`
	)

returns a singly-quoted string aimed to be directly usable in dynamic SQL queries with single quote (\') characters escaped or returns the string "NULL" if the argument type is not int, float, bool, or string

this function is designed to be used to directly put values in an SQL query that should be of VARCHAR/CHAR type

Parameters

$v	value to return as a string that can be directly used in an SQL query
$size	if non-zero, give the maximum size in characters of the string

Returns: a singly-quoted string aimed to be directly usable in SQL queries with single quote (\') characters escaped or returns the string "NULL" if the argument type is not int, float, bool, or string

Note: : use of dynamic SQL is discouraged; use bind by value instead

hash OMQ::UserApi::get_system_info ( )

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, sub = 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

Since: Qorus 2.6.0 added omq-version-code

Note: prior to Qorus 3.0.2 this function was known as getSystemInfo(), and is still imported with this old camel-case name for backwards compatibility

*hash OMQ::UserApi::get_system_service_info ( string $name )

returns information about the given system service (if it's currently loaded)

to get information about system services whether they are loaded or not, call:

$omqservice.system.omqmap.lookupserviceinfo("system", <name>)

Parameters

$name the name of the system service to query

Returns

a hash of user information or NOTHING if the service is not loaded; the hash will have the following structure:

type: "system"
name: the name of the service
version: version of the service
desc: description of the service
serviceid: service ID
status: SSRunning or SSLoaded
threads: number of running threads in the service
autostart: True of False if the autostart flag is set
loaded: date/time the service was loaded
methods: list of hashes for each method with name and desc keys

Note: prior to Qorus 3.0.2 this function was known as getSystemServiceInfo(), and is still imported with this old camel-case name for backwards compatibility

object OMQ::UserApi::get_user_connection	(	string	$name,
		bool	$connect = `True`,
		bool	$register_dependency = `True`,
		*hash	$rtopts
	)

Returns an object corresponding to a defined user connection.

Parameters

$name	the name of the connection
$connect	if False an unconnected object will be returned, otherwise the object is already connected
$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
$rtopts	any runtime options accepted by the connection

Returns: the object representing the connection

Exceptions

CONNECTION-ERROR The given connection is not known

Since: Qorus 3.0

*hash OMQ::UserApi::get_user_service_info ( string $name )

returns information about the given user service (if it's currently loaded)

to get information about user services whether they are loaded or not, call:

$omqservice.system.omqmap.lookupserviceinfo("user", <name>)

Parameters

$name the name of the user service to query

Returns

a hash of user information or NOTHING if the service is not loaded; the hash will have the following structure:

type: "user"
name: the name of the service
version: version of the service
desc: description of the service
serviceid: service ID
status: SSRunning or SSLoaded
threads: number of running threads in the service
autostart: True of False if the autostart flag is set
loaded: date/time the service was loaded
methods: list of hashes for each method with name and desc keys

Note: prior to Qorus 3.0.2 this function was known as getUserServiceInfo(), and is still imported with this old camel-case name for backwards compatibility

public string OMQ::UserApi::getExceptionString ( hash $ex )

Deprecated:: by Util::get_exception_string()

deprecated any OMQ::UserApi::getOption ( )

Deprecated:: by get_option()

public deprecated any OMQ::UserApi::getOracleNumber ( any $v )

Deprecated:: by get_sql_number()

public deprecated string OMQ::UserApi::getOracleString	(	any	$v,
		int	$size = `0`
	)

Deprecated:: by get_sql_string()

hash OMQ::UserApi::getRunningWorkflowInfo ( softint $id )

Deprecated:: by get_running_workflow_info()

list OMQ::UserApi::getRunningWorkflowList ( )

Deprecated:: by get_running_workflow_list()

int OMQ::UserApi::getSessionID ( )

Deprecated:: by get_session_id()

public deprecated any OMQ::UserApi::getSQLNumber ( any $v )

Deprecated:: by get_sql_number()

public deprecated string OMQ::UserApi::getSQLString	(	any	$v,
		int	$size = `0`
	)

Deprecated:: by get_sql_string()

hash OMQ::UserApi::getSystemInfo ( )

Deprecated:: by get_system_info()

*hash OMQ::UserApi::getSystemServiceInfo ( string $name )

Deprecated:: by get_system_service_info()

*hash OMQ::UserApi::getUserServiceInfo ( string $name )

Deprecated:: by get_user_service_info()

OMQ::UserApi::log	(	softint	$lvl,
		softstring	$msg
	)

Saves the information passed to the workflow, service, job, or system log file depending on the calling context if the log level passed is equal to or lower than value of the system option verbose.

Parameters

$lvl	if this value is lower than or equal to the value of the Qorus system verbose option, the message logged in the appropriate log file, otherwise the message is ignored. See Log Levels for valid values
$msg	the format string for a vsprintf() call with the remaining arguments

public string OMQ::UserApi::make_select_list ( any $list )

returns a string based on a list, processed for the values in the list to be used in an SQL string with an Oracle DB

Deprecated:

Oracle-specific; use make_select_list2() instead

Note: : use of dynamic SQL is discouraged; use bind by value instead

public string OMQ::UserApi::make_select_list2	(	any	$driver,
		any	$list
	)

returns a string based on a list, processed for the values in the list to be used in a dynamic SQL string

Note: : use of dynamic SQL is discouraged; use bind by value instead

int OMQ::UserApi::omqsleep ( softint $arg )

puts the current thread to sleep for a certain number of seconds

This function is available in the job, workflow, and service API in the same form. If the job, workflow execution instance, or service is stopping, this function returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this function (or omqusleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters

$arg	the number of seconds to sleep

Returns: 0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped

Exceptions

STOP-ERROR the current object is stopping and this function already returned -1 as a warning

int OMQ::UserApi::omqusleep ( softint $arg )

puts the current thread to sleep for a certain number of microseconds

This function is available in the job, workflow, and service API in the same form. If the job, workflow execution instance, or service is stopping, this function returns immediately with a return value of -1; otherwise the current thread is put to sleep for the full time period requested. If this function (or omqsleep()) is called again after -1 is returned, then a "STOP-ERROR" exception is thrown.

Parameters

$arg	the number of microseconds to sleep (1 microsecond = 1/1000000 of a second)

Returns: 0 if current thread was put to sleep for the full time period; -1 if the sleep was interrupted because the current object is being stopped

Exceptions

STOP-ERROR the current object is stopping and this function already returned -1 as a warning

public string OMQ::UserApi::oracle_date ( date $date )

returns a string from a date suitable for use in a dynamic oracle SQL string

Note: : use of dynamic SQL is discouraged; use bind by value instead

public deprecated bool OMQ::UserApi::parseBoolean ( any $v )

Deprecated:: by Qore::parse_boolean()

int OMQ::UserApi::post_user_event	(	string	$severity,
		any	$info
	)

posts an application event of class QE_CLASS_USER

Parameters

$severity	see Error Severity Codes for possible values
$info	the user-defined information for the event

Exceptions

POST-USER-EVENT-ERROR invalid severity value

string OMQ::UserApi::qorus_get_local_url	(	*string	$username,
		*string	$password
	)

returns a string giving the local system URL

Parameters

$username	an optional username for the new connection
$password	an optional password for the new connection

Returns: a string giving the local system URL

Note: the username and password arguments are only used if both are given

Since: Qorus 3.0.2

OMQ::UserApi::raise_transient_alert	(	string	$alert,
		string	$reason,
		*hash	$info
	)

raises a transient system alert from a workflow, service, or job

Parameters

alert	the name of the alert (ex: `"DATA-SIZE-EXCEEDED"`)
reason	the reason or verbose description of the alert
info	optional key / value details for the alert

Since: Qorus 3.0

public list OMQ::UserApi::remove_from_list	(	list	$list,
		any	$val
	)

uses the select operator to remove all occurences of a value from a list

Note: : O(n) performance

public list OMQ::UserApi::remove_from_list	(	reference	$list,
		any	$val
	)

uses the select operator to remove all occurences of a value from a list

Note: : O(n) performance

public deprecated list OMQ::UserApi::remove_from_list_index	(	list	$list,
		int	$index
	)

DEPRECATED: remove an element from a list.

Deprecated:: use the Qore splice operator instead which is faster and standard qore functionality

hash OMQ::UserApi::runtime_properties ( )

returns Qorus runtime properties as a hash

Returns: Qorus runtime properties as a hash; if no properties are set, returns an empty hash

Note: prior to Qorus 3.0.2 this function was known as runtimeProperties(), and is still imported with this old camel-case name for backwards compatibility

hash OMQ::UserApi::runtimeProperties ( )

Deprecated:: by runtime_properties()

public string OMQ::UserApi::serialize_qorus_data ( any $d )

returns a string giving the default serialization of the given data structure for storage in Qorus

the default serialization is currently YAML

Parameters

$d	the data to serialize

Returns: a YAML string representing the given data structure for storage in Qorus

OMQ::UserApi::set_option ( hash $hash )

Changes option values on a workflow, service, or job.

if called from workflow code, and the workflow has defined workflow options and an invalid option is passed to the function, an exception will be raised; however all other valid options in the hash will be set before the exception is raised

Parameters

$hash a hash of option-value pairs

Exceptions

WORKFLOW-OPTION-ERROR invalid option name

Note: prior to Qorus 3.0.2 this function was known as setOption(), and is still imported with this old camel-case name for backwards compatibility

deprecated OMQ::UserApi::setOption ( hash $hash )

Deprecated:: by set_option()

OMQ::UserApi::unblock_order	(	softint	$wfiid,
		*hash	$tempdata
	)

unblocks the given workflow order data instance

Parameters

$wfiid the workflow order instance ID to unblock

Returns

a hash with the following key:

workflow_status: the status of the workflow order

Exceptions

BLOCK-WORKFLOW-ERROR invalid status, foreign session id, missing original status, uncancel operation already in progress

Since: Qorus 3.0.4.p2

OMQ::UserApi::uncancel_order	(	softint	$wfiid,
		*hash	$tempdata
	)

uncancels the given workflow order data instance

Parameters

$wfiid the workflow order instance ID to uncancel

Returns

a hash with the following key:

workflow_status: the status of the workflow order

Exceptions

CANCEL-WORKFLOW-ERROR invalid status, foreign session id, missing original status, uncancel operation already in progress

Since: Qorus 3.0.4.p2

public string OMQ::UserApi::xml_change_encoding	(	string	$xml,
		string	$enc
	)

returns a string with the XML encoding name changed to that given as an argument

does not change the actual encoding of the string (which may be different)

Namespaces

Functions

Detailed Description

Function Documentation