Qorus Integration Engine®  3.1.1.p9
Job API Reference

Introduction to the Qorus Job API

Each job's Program container is set up with the following imported objects:

In addition to the above, all public constants in the OMQ namespace are available.

See also
Implementing Jobs

Job Program Container

Each job has a single Qore Program object containing the code to be defined when the job trigger time arrives, as well as any objects imported into the Program object (classes, constants, and functions listed as attributes of the job when the job is defined). Job Program objects are restricted from using elements of the Qore language related to process and thread control; the use of these functions is either dangerous or could violate the integrity of the Qorus server process and therefore is restricted.

To enforce these restrictions, job Program objects are created with the following parse restrictions:

Directive Constant Description
%no-top-level Qore::PO_NO_TOP_LEVEL_STATEMENTS No code is allowed in the top-level statement (outside a function or class)
%no-thread-control Qore::PO_NO_THREAD_CONTROL Thread management functionality is unavailable
%no-process-control Qore::PO_NO_PROCESS_CONTROL Functionality that affects the entire process is unavailable
%require-our Qore::PO_REQUIRE_OUR All variables must be declared before use

Please note that despite these restrictions, job program objects have most of the Qore language API and class library available for use.

Furthermore, the following parse defines are defined:

Define Availability Description
Qorus W, S, J Identifies code in Qorus
QorusHasAlerts W, S, J Marks the availability of the alert API (Qorus 3.0+)
QorusHasTableCache W, S, J Marks the availability of the table cache API (Qorus 3.1+)
QorusHasUserConnections W, S, J Marks the availability of the connection API (Qorus 3.0+)
QorusJob S Identifies code used in a job Program container
QorusServer W, S, J Identifies code used in Qorus server interfaces
Note
All defines set in defines (common to workflows, services, and jobs) are also set in job Program containers

Job API Functions

The following functions are imported into job program logic containers (see also OMQ::UserApi::Job):

Name Domain Availability Description
audit_check_event_string() Audit W, S, J checks if the given audit event (given as a string) is enabled
audit_check_event() Audit W, S, J checks if the given audit event (given as an integer code) is enabled
audit_get_mask() Audit W, S, J returns the audit event mask
audit_user_event() Audit W, S, J creates a user audit event (with audit event code OMQ::AE_USER_EVENT) against the workflow, service, or job instance
call_network_api() Utility W, S, J calls a system RPC API with system permissions
call_network_api_args() Utility W, S, J calls a system RPC API with system permissions with an explicit argument list argument
call_network_api_args_with_authentication() Utility W, S, J calls a system RPC API with authentication information (username and password)
call_rest_api() Utility W, S, J calls a system REST API with system permissions
call_rest_api_with_authentication() Utility W, S, J calls a system REST API with authentication information (username and password)
clear_sql_table_cache() SQL Cache W, S, J clears a cached table from the SQL cache
create_order() Utility W, S, J creates a workflow order data instance in the database and returns the workflow_instanceid of the order created
create_remote_order() Utility W, S, J creates a workflow order data instance in a remote Qorus instance and returns the workflow_instanceid of the order created
deserialize_qorus_data() Utility W, S, J deserializes strings to Qore data structures
exec_synchronous_workflow() Utility W, S, J executes a workflow order synchronously and returns the result of execution
flush_sla_events() SLA W, S, J flushes all pending SLA events to the DB
get_active_jobs() System Info W, S, J returns information about active jobs
get_datasource_dedicated() Connections W, S, J returns a dedicated Qore::SQL::Datasource object
get_datasource_pool() Connections W, S, J returns a shared Qore::SQL::DatasourcePool object
get_datasource_shared() Connections W, S, J returns a shared Qore::SQL::Datasource object
get_option() Options W, S, J returns the value of one or more system or interface options
get_qorus_options() Options W, S, J returns the value of system options
get_qorus_options_args() Options W, S, J returns the value of system options
get_qorus_option_info() Options W, S, J returns information about system options
get_qorus_option_info_args() Options W, S, J returns information about system options
get_remote_rest_connection() Connections W, S, J returns a QorusSystemRestHelper to a remote Qorus instance
get_remote_rpc_connection() Connections W, S, J returns a QorusSystemAPIHelper to a remote Qorus instance
get_running_workflow_info() System Info W, S, J returns information about a running workflow execution instance
get_running_workflow_list() System Info W, S, J returns information about running workflow execution instances
get_service_info() System Info W, S, J returns information about a service
get_session_id() System Info W, S, J returns the current application session ID
get_sql_table() SQL Cache W, S, J retrieves an AbstractTable object from the SQL cache for DML operations
get_sql_cache_info() SQL Cache W, S, J returns information about the SQL cache
get_system_info() System Info W, S, J returns information about the system
get_system_service_info() System Info W, S, J returns information about a system service
get_user_connection() Connections W, S, J returns the given user connection object
get_user_service_info() System Info W, S, J returns information about a user service
get_value_map() Value Maps W, S, J retrieves a value mapping from a value map
get_value_maps() Value Maps W, S, J retrieves a list of all known value sets
job_err() Job API J raises job errors with mandatory error and description string arguments
job_error() Job API J raises job errors
job_get_state_data() Job API J retrieves job state data if available
job_info() Job API J retrieves information about the currently-executing job
job_save_info() Job API J saves information about job processing agaainst the job instance record
job_save_state_data() Job API J saves job state data against the current job instance
job_set_trigger() Job API J sets a custom trigger time for the next job instance
job_warning() Job API J raises job warnings
log() logging W, S, J outputs a log message in the service's log file
next_sequence_value() Utility W, S, J returns the next value from the given datasource and database sequence
parse_uri_query() Utility W, S, J parses a URI query string in a URI path and returns the parsed data structure
post_sla_event_error() SLA W, S, J posts an unsuccessful event for SLA and performance tracking
post_sla_event_success() SLA W, S, J posts a successful event for SLA and performance tracking
post_sync_event() Utility W, S, J posts a workflow synchronization event given the event type name and event key
post_user_event() Utility W, S, J posts an application event of class OMQ::QE_CLASS_USER
prop_get() System Props W, S, J returns the value of the given system property key in the given domain or NOTHING if the system property does not exist
prop_update() System Props W, S, J changes (inserts, updates, or deletes) the value of one or more system properties
restart_transaction() Utility W, S, J enables recovery from restartable DB communication errors
qorus_get_local_url() System Info W, S, J returns a URL for the current system
raise_transient_alert() Alerts W, S, J raises a transient alert
runtime_properties() System Info W, S, J returns information about runtime system defines
serialize_qorus_data() Utility W, S, J serializes Qore data structures to strings
set_option() Options W, S, J sets option values on a workflow, service, or job

Job API Classes

The following classes are imported into job program logic containers:

Name Availability Description
AbstractFsRemoteReceive W, S, J provides an API for streaming data from a remote filesystem through a remote Qorus instance
AbstractParallelStream W, S, J provides an abstract base class for streaming data to or from a remote database through a remote Qorus instance and also provides static helper methods
DbRemote W, S, J provides an API wrapper for all system.sqlutil service methods
DbRemoteReceive W, S, J provides an API for streaming data from a remote database through a remote Qorus instance
DbRemoteSend W, S, J provides an API for streaming data to a remote database through a remote Qorus instance
FsRemote W, S, J provides an API wrapper for all system.fs service methods
FsRemoteSend W, S, J provides an API for streaming data to a remote filesystem through a remote Qorus instance
QorusInboundTableMapper W, S, J provides an API for mapping data to a DB table
QorusInboundTableMapperIterator W, S, J provides an iterator-based API for mapping data to a DB table
QorusRawSqlStatementOutboundMapper W, S, J provides an API for mapping from SQL statement using direct SQL statements passed in
QorusRemoteServiceHelper W, S, J provides an API for calling service methods in remote Qorus instances
QorusSqlStatementOutboundMapper W,S, J provides an API for mapping from SQL statement using SqlUtil
QorusSystemAPIHelper W, S, J provides an API for calling RPC API methods in remote Qorus instances
OMQ::QorusSystemRestHelper W, S, J provides an API for using the REST API in remote Qorus instances

Job API Modules

The following modules are imported by default into job program logic containers:

Name Availability Description
json W, S, J provides APIs for JSON data serialization and deserialization support
Mime W, S, J provides MIME definitions and functionality
Mapper W, S, J provides a data-mapping API
SoapClient W, S, J provides a SOAP client API
SqlUtil W, S, J provides high-level APIs for programmatic DML (SQL data manipulation), DDL (creating, querying, manipulating database definitions), and DBA operations
TableMapper W, S, J provides high-level APIs for mapping data to and from database tables
Util W, S, J provides utility APIs
uuid W, S, J provides an API for generating UUIDs
xml W, S, J provides APIs for parsing, validating, and generating XML documents
yaml W, S, J provides APIs for Qore's YAML-based data serialization and deserialization support
Note
other modules can be imported using the %requires directive, and it's always safe to %require a module that's already imported into the current Program container

Job API Overview

This section lists all of the functions specific to jobs.

See also
  • Qorus Common Server API for APIs and API concepts common to all Qorus server code (workflows, services, and jobs).
  • Qorus Common API for a definition of API definitions common to all Qorus user code (workflows, services, and jobs) as well as the client library.
Note
Job-specific API functions are found in the OMQ::UserApi::Job namespace and are prefixed by "job_" for consistency's sake and ease of identification.

Logging function (common API function):

Name Desc
job_err() raises job errors with mandatory error and description string arguments
job_error() raises job errors
job_get_state_data() retrieves job state data if available
job_info() retrieves information about the currently-executing job
job_save_info() saves information about job processing agaainst the job instance record
job_save_state_data() saves job state data against the current job instance
job_set_trigger() sets a custom trigger time for the next job instance
job_warning() raises job warnings
qorus-small.png
Qorus Integration Engine®