Qorus Integration Engine®  4.0.3_git
OMQ::UserApi::Job Namespace Reference

main job API namespace More...

Classes

class  JobApi
 primary job API class More...
 
class  QorusJob
 The abstract class for Qorus jobs. More...
 

Functions

 job_error (string err, softstring desc="", auto info, softstring severity=OMQ::ES_Major, softbool business=False)
 raises an error in a running job; does not affect the flow of execution in the job code More...
 
 job_warning (string err, softstring desc="", auto info, softbool business=False)
 raises a warning in a running job; does not affect the flow of execution in the job code More...
 
 job_err (string err, string desc_fmt)
 raises an error in a running job; does not affect the flow of execution in the job code More...
 
 job_warn (string err, string desc_fmt)
 raises a warning in a running job; does not affect the flow of execution in the job code More...
 
 job_save_info (auto info)
 saves information against the job instance in the database More...
 
hash< auto > job_info ()
 returns a hash of job information about the current job More...
 
 job_save_state_data (hash< auto > data)
 serializes the given hash and stores against the job's state data in JOB_STATE_DATA More...
 
*hash< auto > job_get_state_data ()
 returns any job state state data stored with job_save_state_data() More...
 
bool job_set_trigger (date ts)
 sets a one-time custom trigger time for the job; returns True if set, False if ignored More...
 

Detailed Description

main job API namespace

Qorus job API namespace.

Function Documentation

◆ job_err()

OMQ::UserApi::Job::job_err ( string  err,
string  desc_fmt 
)

raises an error in a running job; does not affect the flow of execution in the job code

the error information is stored in the job_errors table with a severity of OMQ::ES_Major and the business flag set to True

Parameters
errthe error code
desc_fmtthe format specifier for the warning description string; following arguments will be included in the description string as combined with vsprintf()
Since
Qorus 3.1.0
See also

◆ job_error()

OMQ::UserApi::Job::job_error ( string  err,
softstring  desc = "",
auto  info,
softstring  severity = OMQ::ES_Major,
softbool  business = False 
)

raises an error in a running job; does not affect the flow of execution in the job code

the error information is stored to the job_errors table, errors errors with a severity less than or equal to OMQ::ES_Warning are treated as warnings

Parameters
errthe error code
desca description for the error
infoadditional information to be saved with the error (data structures are serialized in YAML format and saved in the database)
severitythe severity of the error, errors with a severity less than or equal to OMQ::ES_Warning are treated as warnings; see Error Severity Codes for valid values (default = OMQ::ES_Major)
businessset to True if the error represents a business error
Since
Qorus 3.1.0 if the severity is less than or equal to OMQ::ES_Warning, the job instance does not get an OMQ::JS_Error status
See also

◆ job_get_state_data()

*hash<auto> OMQ::UserApi::Job::job_get_state_data ( )

returns any job state state data stored with job_save_state_data()

Returns
any job state state data stored with job_save_state_data()
Note
job state state data is automatically cleared when a job instance gets a OMQ::StatComplete status
See also
Since
Qorus 3.1.0

◆ job_info()

hash<auto> OMQ::UserApi::Job::job_info ( )

returns a hash of job information about the current job

Returns
a hash with the following keys:
  • jobid: the metadata jobid of the job type
  • job_instanceid: the id of the job instance
  • name: the job name
  • version: the job version
  • description: the job description
  • trigger: a string describing the timer/trigger for the job
  • last_executed: the last executed date/time of the job (NOTHING if never executed before the current iteration)
  • last_executed_job_instanceid: the last executed instance id of the job
  • 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
Note
the data returned here is different from the data stored by job_save_info()
See also

◆ job_save_info()

OMQ::UserApi::Job::job_save_info ( auto  info)

saves information against the job instance in the database

The information is serialized in YAML format and saved in the database in the JOB_INSTANCE row as a part of the job results.

This information is returned in the API as the info key in REST Job Result Hash data, for example in the return value to the REST GET /api/latest/jobresults/{id} call.

Parameters
infothe information to save
Note
the data stored here is different from the data returned by job_info()
See also

◆ job_save_state_data()

OMQ::UserApi::Job::job_save_state_data ( hash< auto >  data)

serializes the given hash and stores against the job's state data in JOB_STATE_DATA

Parameters
datathe state data to serialize and store against the job's state data in JOB_STATE_DATA
Note
job state state data is automatically cleared when a job instance gets a OMQ::StatComplete status
Since
Qorus 3.1.0
See also

◆ job_set_trigger()

bool OMQ::UserApi::Job::job_set_trigger ( date  ts)

sets a one-time custom trigger time for the job; returns True if set, False if ignored

Parameters
tsthe timestamp to trigger the job; must be in the future and before the next trigger time
Returns
True if set, False if ignored; the call will be ignored if the date/time value is in the past or after the next scheduled job trigger time
Note
when this API returns with a True return value, the job's custom trigger time has already been committed to the database
Since
Qorus 3.1.0
See also
JobApi::setTrigger()

◆ job_warn()

OMQ::UserApi::Job::job_warn ( string  err,
string  desc_fmt 
)

raises a warning in a running job; does not affect the flow of execution in the job code

the warning information is stored to the job_errors table with a severity of OMQ::ES_Warning and the business flag set to True

Parameters
errthe warning or error code
desc_fmtthe format specifier for the warning description string; following arguments will be included in the description string as combined with vsprintf()
Since
Qorus 3.1.0
See also

◆ job_warning()

OMQ::UserApi::Job::job_warning ( string  err,
softstring  desc = "",
auto  info,
softbool  business = False 
)

raises a warning in a running job; does not affect the flow of execution in the job code

the warning information is stored to the job_errors table with a severity of OMQ::ES_Warning

Parameters
errthe warning or error code
desca description for the warning
infoadditional information to be saved with the warning (data structures are serialized in YAML format and saved in the database)
businessset to True if the warning represents a business warning
Since
Qorus 3.1.0
See also