5.2 XML Commands

These commands can be transmitted using TCP (e.g. telnet), HTTP and using the Command line options -cmd and -send-cmd .

Command	Answer (packed in <spooler><answer>)
<add_jobs>	<ok>
<add_order>	<ok> <order>
<job_chain.modify>	<ok>
<job_chain_node.modify>	<ok>
<kill_task>	<ok>
<lock>	<ok>
<lock.remove>	<ok>
<modify_hot_folder>	<ok>
<modify_job>	<ok>
<modify_order>	<ok>
<modify_spooler>	<ok>
<param>	<ok>
<param.get>	<param>
<params>	<ok>
<params.get>	<params>
<process_class>	<ok>
<process_class.remove>	<ok>
<remove_job_chain>	<ok>
<remove_order>	<ok>
<schedule.remove>	<ok>
<scheduler_log.log_categories.reset>	<ok>
<scheduler_log.log_categories.set>	<ok>
<scheduler_log.log_categories.show>	<log_categories>
<show_calendar>	<calendar>
<show_history>	<history>
<show_job>	<job>
<show_job_chain>	<job_chain>
<show_job_chains>	<job_chains>
<show_jobs>	<jobs>
<show_order>	<order>
<show_state>	<state>
<show_task>	<task>
<start_job>	<ok> <task>
<terminate>	<ok>

XML Elements

XML Element <add_jobs>

<add_jobs >

job

</add_jobs>

Jobs are added with temporary="yes" and then started. Every job is deleted as soon as it ends.

Note that job names must be unique.

Parent Elements

<commands> -

XML Element <add_order>

<add_order

job_chain	= "name"
id	= "id"
priority	= "number"
title	= "text"
state	= "text"
job	= "name"
web_service	= "name"
at	= "timestamp"	Order Starting Time
end_state	= "text"	State before which the order should be successfully completed and should leave the job chain

>

params	Parameters
run_time
xml_payload	XML Payload

</add_order>

Adds a new order.

When the <params> element is specified, then the Scheduler creates a Variable_set and makes it available in Order.payload() .

    <add_order job_chain="job_chain" id="1234" title="My First Order" state="100 at="now+3:00">

    <params>
        <param name="a_parameter" value="a value"/>
    
    </params>
</add_order>
        

Parent Elements

<commands> -

Attributes

job_chain="name"

The name of the job chain in which the order is being processed.

id="id"

The alphanumerical identification of the order. (Note that this parameter may not be set to id - which is an XML reserved word.)

priority="number"

title="text"

The title of the order.

state="text"

job="name"

web_service="name"

When an order has been completed and the end of the job chain reached, it is then transformed with a style sheet and forwarded to a Web Service.

See <web_service> .

at="timestamp" (Initial value:now) Order Starting Time

"now", "yyyy-mm-dd HH:MM[:SS]", "now + HH:MM[:SS]" and "now + SECONDS" are possible.

See also Order.at .

end_state="text" State before which the order should be successfully completed and should leave the job chain

See Order.end_state .

XML Element <check_folders>

<check_folders > </check_folders>

Checks the configuration directories for changes and updates the respective objects in the Job Scheduler. On Windows operating systems changes to a directory are noticed immediately, on Unix systems this could take up to 60 seconds.

The command is available in the built-in HTML interface and is used. for example, when developing jobs for Unix in order to shorten the waiting time until changes to the configuration are noticed by the Job Scheduler.

<check_folders/>

Parent Elements

<commands> -

XML Element <job_chain.modify>

<job_chain.modify

job_chain	= "name"	Specifies a job chain
state	= "state"

> </job_chain.modify>

<job_chain.modify job_chain="my_job_chain" state="stopped"/>

Parent Elements

<commands> -

Attributes

job_chain="name" Specifies a job chain

state="state"

Not possible with distributed job chains.

Possible values are:

Individual job nodes can be stopped with <job_chain_node.modify action="stop"> .

Messages

[ERROR]	SCHEDULER-384	job_chain is distributed and therefore does not support operation ''
[ERROR]	SCHEDULER-405	Setting state='' is not possible while job chain has state ''

XML Element <job_chain_node.modify>

<job_chain_node.modify

job_chain	= "name"	Specifies the job chain
state	= "state"	Specifies the job chain node
action	= "action"

> </job_chain_node.modify>

<job_chain_node.modify job_chain="my_job_chain" state="100" action="stop"/>

Parent Elements

<commands> -

Attributes

job_chain="name" Specifies the job chain

state="state" Specifies the job chain node

action="action"

Not allowed for distributed job chains.

Possible values are action="process", action="stop" and action="next_state", as described for Job_chain_node.action .

A complete job chain can be stopped using <job_chain.modify state="stopped"> .

Messages

[info]

SCHEDULER-859

Due to action='next_state' the state '' has been skipped. Next state is ''

XML Element <kill_task>

<kill_task

job	= "job_name"
id	= "number"
immediately	= "yes|no"

> </kill_task>

Stops non-API tasks ( <process> or <script language="shell"> ) together with any sub-processes. To do this, the Job Scheduler determines all sub-processes and stops them. Further, on Unix systems the process group task processes will be stopped.

<kill_task job="my_job" id="4711"/>
        

Parent Elements

<commands> -

Attributes

job="job_name"

The job name.

id="number"

The task Id. (The attribute may not be named id - this term is a reserved word in XML.)

immediately="yes|no" (Initial value:no)

XML Element <lock>

<lock

name	= "name"	The lock name
max_non_exclusive	= "integer"	Restricting Non-Exclusive Use

> </lock>

A lock can stop two tasks from running at the same time.

See <lock.use> for information about the use of locks.

See also <lock.remove>

<locks>
    <lock name="switching_database"/>
    <lock name="only_three_tasks" max_non_exclusive="3"/>
</locks>

Behavior with <base>

Supplements the <lock> element in the corresponding node of the basic XML configuration . Attributes specified here have precedence over those entered in the basic XML configuration.

Parent Elements

<locks> -

Attributes

name="name" The lock name

max_non_exclusive="integer" Restricting Non-Exclusive Use

The default setting is unlimited - which means that with <lock.use exclusive="no"> an unlimited number of non-exclusive tasks can be started (but only one exclusive).

Messages

[ERROR]

SCHEDULER-887

More lock holders than new max_non_exclusive=: holders

XML Element <lock.remove>

<lock.remove

lock

= "path"

The lock name

> </lock.remove>

Removes a Lock.

See also <lock> .

Parent Elements

<commands> -

Attributes

lock="path" The lock name

The lock can only be removed when it is not active - i.e. it is neither allocated a task nor being used by a job ( <lock.use> ).

See also Lock.remove() .

XML Element <modify_hot_folder>

<modify_hot_folder

folder

= "path"

>

job
job_chain
lock	Lock Declaration
order
process_class	Process classes
schedule

</modify_hot_folder>

This command adds a child element to a configuration directory. The file name is formed according to the rules for file-based configuration of jobs and tasks (see ).

Already existing files will be overwritten.

The child element (only one can be specified) must possess a name= attribute, or, if it is an order, job_chain= and id= attributes.

Parent Elements

<commands> -

Attributes

folder="path" (Initial value:/)

Specifies the folder in which XML elements should be written. The Job Scheduler creates this directory if it does not already exist (including all higher level directories, if necessary to the root directory).

XML Element <modify_job>

<modify_job

job	= "jobname"
cmd	= "cmd"

> </modify_job>

<modify_job job="my_job" cmd="wake"/>
        

Parent Elements

<commands> -

Attributes

job="jobname"

The name of the job for which a command is intended.

cmd="cmd"

The following sub-commands may be used:

XML Element <modify_order>

<modify_order

job_chain	= "state"
order	= "id"
state	= "state"
title	= "title"
action	= "action"
setback	= "no"
priority	= "number"
suspended	= "yes|no"
at	= "timestamp"
end_state	= "text"	State before which the order should be successfully completed and should leave the job chain

>

params	Parameters
xml_payload	XML Payload
run_time

</modify_order>

    <modify_order job_chain="my_job_chain" order="42" priority="1"/>

        

Parent Elements

<commands> -

Attributes

job_chain="state"

The order job chain.

order="id"

The order identifier (alphanumerical).

state="state"

Changes the state of an order and thereby its position in a job chain. Use of this attribute causes any setbacks ( Order.setback() ) made to be cancelled.

See also Order.state

title="title"

Changes the order title

See also Order.title

action="action"

action="reset" resets the order. The order is returned to its original state: it is no longer suspended and the setback is taken back. The next start time for the job is calculated as if the job chain had been completed.

This operation is only allowed when the order in question is not being executed by a job.

Messages

[ERROR]

SCHEDULER-217

order is being processed by task

setback="no"

Is effective after an order has been setback using Order.setback() . This command ends all delays set using <delay_order_after_setback> , so that the order may be immediately executed. Note that the counter used to note how often an order has been setback remains unchanged.

See also Order.setback() and <delay_order_after_setback> .

priority="number"

suspended="yes|no"

Suspends or restarts the execution of an order - see Order.suspended .

at="timestamp"

"now", "yyyy-mm-dd HH:MM[:SS]", "now + HH:MM[:SS]" and "now + SECONDS" can be used.

Changes the next start time of a waiting order,

• whose Order.run_time has not been reached, or
• which has been setback using Order.setback() .

at="now" restarts an order which has been waiting because of Order.run_time or Order.setback() .

See also <add_order at="…"> and Order.at .

end_state="text" State before which the order should be successfully completed and should leave the job chain

See Order.end_state .

XML Element <modify_spooler>

<modify_spooler

cmd	= "cmd"
timeout	= "int"

> </modify_spooler>

The following sub-commands are not carried out after the Job Scheduler has halted because of insufficient disc space for a log file ( <state waiting_errno="…"> ): pause, reload, terminate, terminate_and_restart, let_run_terminate_and_restart. On the other hand continue, abort_immediately and abort_immediately_and_restart are immediately effective.

<modify_spooler cmd="abort_immediately_and_restart"/>
        

Parent Elements

<commands> -

Attributes

cmd="cmd"

The following subcommands are allowed:

timeout="int"

For cmd="terminate" and cmd="terminate_and_restart": the time the Job Scheduler will wait before stoping unterminated processes.

The default setting is an unlimited waiting time.

See Spooler.terminate() .

XML Element <param>

<param

name	= ""	Unique Name
value	= ""

> </param>

See <params> .

Defines the individual parameters for the Job Scheduler, a job or an order. Parameters can be overwritten and extended whilst a job or order is being executed.

Job Scheduler parameters can be called using the Spooler.variables() method.

Job parameters can be called using the Task.params() method.

The parameters of an order can be called using the Order.params() method.

See also the Variable_set class.

Behavior with <base>

Supplements the <param> element in the corresponding node of the basic XML configuration with the attribute name= . Attributes specified here have precedence over those entered in the basic XML configuration.

Parent Elements

<params> - Parameters

Attributes

name="" Unique Name

value=""

XML Element <param.get>

<param.get

name

= "name"

The parameter name

> </param.get>

Returns <param> with the Job Scheduler parameter or <ok> , when the parameter is not known.

Attributes

name="name" The parameter name

XML Element <params>

<params >

param	Single Parameters
copy_params
include

</params>

Specifies the parameters for the Job Scheduler, a job or an order. The parameters can be overwritten and extended whilst the Job Scheduler is running.

Job Scheduler parameters can be called up using the Spooler.variables() method.

Job parameters are called using the Task.params() method.

The parameters for an order can be called using the Order.payload() method.

See also the Variable_set and <sos.spooler.variable_set> classes.

Behavior with <base>

Supplements the <params> element in the corresponding node of the basic XML configuration . Attributes specified here have precedence over those entered in the basic XML configuration.

Parent Elements

<job> -

<add_order> -

<config> -

<modify_order> -

<payload> - Payload

<queued_task> -

<web_service> -

XML Element <params>

<params >

param	Single Parameters
copy_params
include

</params>

Specifies the parameters for the Job Scheduler, a job or an order. The parameters can be overwritten and extended whilst the Job Scheduler is running.

Job Scheduler parameters can be called up using the Spooler.variables() method.

Job parameters are called using the Task.params() method.

The parameters for an order can be called using the Order.payload() method.

See also the Variable_set and <sos.spooler.variable_set> classes.

Behavior with <base>

Supplements the <params> element in the corresponding node of the basic XML configuration . Attributes specified here have precedence over those entered in the basic XML configuration.

Parent Elements

<job> -

<add_order> -

<config> -

<modify_order> -

<payload> - Payload

<queued_task> -

<web_service> -

XML Element <params.get>

<params.get

name

= "name"

The parameter name

> </params.get>

Returns <params> including all Job Scheduler variables.

Attributes

name="name" The parameter name

XML Element <payload>

<payload >

params

Parameters

</payload>

If the payload is not a Variable_set object, then it will be added as text.

Parent Elements

<order> -

XML Element <process_class>

<process_class

spooler_id	= "scheduler_id"
name	= "name"
max_processes	= "number"
remote_scheduler	= "host:port"	Task execution on remote computers
replace	= "yes|no"

> </process_class>

Defines or modifies a process class.

See also <process_class.remove> .

Behavior with <base>

Supplements the <process_class> element in the corresponding node of the basic XML configuration . Attributes specified here have precedence over those entered in the basic XML configuration.

Parent Elements

<process_classes> -

Attributes

spooler_id="scheduler_id"

An element having this attribute is only active when the attribute is either:

• empty
• set to the -id= Job Scheduler start parameter
• or when the Job Scheduler -id option is not specified when starting the Job Scheduler.

name="name"

The name of the process class. Should this attribute be missing or empty ("") then the default process class will be changed.

See the process_class= attribute of the <job> element.

max_processes="number" (Initial value:30)

Limits the number of processes.

Some operating systems limit the number of processes which the Job Scheduler can start. The number of processes configured here should not exceed the number allowed by the operating system. A value below 64 is usually safe.

For Microsoft Windows systems, the maximum number of processes that are allowed to be executed in parallel is currently 30.

remote_scheduler="host:port" Task execution on remote computers

Specifies the remote computer on which the tasks of this process class are to be executed. This computer is specified using its host name or IP number and TCP port (see <config tcp_port="…"> ).

The remote computer must allow access with <allowed_host level="all"> .

Tasks executed communicate with the controlling Job Scheduler via the API. However, the following points should be noted:

• <include> within <script> is executed by a task process. The file to be included is thereby read by the computer which carries out the task.
• The Subprocess.timeout and Task.add_pid() methods do not work. The Job Scheduler cannot terminate remote subprocesses whose time limits have been exceeded.
• Log.log_file() is, as with almost all methods, carried out on the computer on which the Job Scheduler is running and thereby accesses the files of its local file system.

Some settings are taken from the remote instead of from the controlling Job Scheduler:

• sos.ini (section [java], entry javac= …)
• factory.ini (section [spooler], entry tmp= …)
• <config java_options="…">
• <config java_class_path="…">
• <config include_path="…">

Messages

[warn]	SCHEDULER-849	Timeout is not possible for a subprocess running on a remote host (it cannot be killed), pid=
[warn]	SCHEDULER-850	After lost connection to remote scheduler, process is going to be killed
[info]	SCHEDULER-848	Task pid= started for remote scheduler

replace="yes|no" (Initial value:yes)

replace="yes" replaces the existing process class.

replace="no" only changes the attributes which are set by the process class.

XML Element <process_class.remove>

<process_class.remove

process_class

= "path"

Name of the lock

> </process_class.remove>

Removes a process class.

See also <process_class> .

Parent Elements

<commands> -

Attributes

process_class="path" Name of the lock

The Job Scheduler delays deletion of a process class as long as tasks are still running in it. No new tasks will be started during this time.

See also Process_class.remove() .

XML Element <remove_job_chain>

<remove_job_chain

job_chain

= "name"

> </remove_job_chain>

REmoves a Job Chain.

This command uses the Job_chain.remove() method.

<remove_job_chain job_chain="my_job_chain" />

Parent Elements

<commands> -

Attributes

job_chain="name"

XML Element <remove_order>

<remove_order

job_chain	= "name"
order	= "id"

> </remove_order>

Removes an order from the job chain. Note that a job which is in the process of carrying out an order will not be affected by this command.

The command uses the Order.remove_from_job_chain() method.

<remove_order job_chain="my_jobchain" order="42" />

        

Parent Elements

<commands> -

Attributes

job_chain="name"

order="id"

The (alphanumerical) order identifier.

XML Element <schedule.remove>

<schedule.remove

schedule

= "path"

The schedule path

> </schedule.remove>

Removes a schedule.

See also <schedule> .

Parent Elements

<commands> -

Attributes

schedule="path" The schedule path

All tasks for jobs that use the schedule will be stopped.

Orders that use the schedule complete their job chain and will not be restarted, as long as the schedule is not available.

XML Element <scheduler_log.log_categories.reset>

<scheduler_log.log_categories.reset

delay

= "integer"

Delay in Seconds

> </scheduler_log.log_categories.reset>

Resets all log categories back to the values set as the Job Scheduler started.

See also »Log Categories«

<scheduler_log.log_categories.reset delay="360"/>

Parent Elements

<commands> -

Attributes

delay="integer" Delay in Seconds

Delays resetting of the categories by the time specified.

XML Element <scheduler_log.log_categories.set>

<scheduler_log.log_categories.set

category	= "name"	Category Name
value	= "0|1"

> </scheduler_log.log_categories.set>

See also »Log Categories«

<scheduler_log.log_categories.set category="scheduler" value="1"/>

Parent Elements

<commands> -

Attributes

category="name" Category Name

value="0|1"

1 activates the category, 0 deactivates it.

XML Element <scheduler_log.log_categories.show>

<scheduler_log.log_categories.show > </scheduler_log.log_categories.show>

See also »Log Categories«

<scheduler_log.log_categories.show/>

Parent Elements

<commands> -

XML Element <show_calendar>

<show_calendar

what	= "what"
limit	= "number"
from	= "yyyy-mm-ddThh:mm:ss"
before	= "yyyy-mm-ddThh:mm:ss"

> </show_calendar>

This command returns the start times of jobs and orders. The results are not sorted.

The limit="" attribute is per defafult set to limit="100" and thereby limits the number of results. The limit should be set to a large enough value, so that no gaps appear in the (calender) list.

<show_calendar/>
<show_calendar limit="1000" what="orders" from="2007-04-03T00:00:00" before="2007-05-01T00:00:00"/>

Parent Elements

<commands> -

Attributes

what="what"

what="orders" also returns the start times of orders.

limit="number" (Initial value:100)

Limits the number of entries that are returned in order avoid too large a result. Because calender entries are not sorted according to time but by object, this command does not return the next 100 entries but effectively 100 random entries.

The limit should be set high enough so that entries are not lost.

from="yyyy-mm-ddThh:mm:ss"

Returns calender entries after a given date & time.

before="yyyy-mm-ddThh:mm:ss"

Returns calender entries before a given date & time. The default setting is a week after from= or a week after from.

XML Element <show_history>

<show_history

job	= "job_name"
id	= "number"
next	= "number"
prev	= "number"
what	= ""

> </show_history>

<show_history id="4711" next="10"/>
        

Parent Elements

<commands> -

Attributes

job="job_name"

The job name.

id="number"

The identifier for the history. (This attribute may not be called id, as this is a reserved term in XML.)

next="number"

The first number entries made after the task id should be returned.

prev="number"

The last number entries made before the task id should be returned.

what=""

XML Element <show_job>

<show_job

job	= "name"
job_chain	= "name"
what	= ""
max_orders	= ""
max_task_history	= ""

> </show_job>

    <show_job job="my_job"/>
        

Parent Elements

<commands> -

Attributes

job="name"

The job name.

job_chain="name"

Neither orders which are in this job chain nor tasks which process such orders are returned.

what=""

max_orders=""

max_task_history=""

XML Element <show_job_chain>

<show_job_chain

job_chain	= ""	The job chain name
max_orders	= ""
max_order_history	= ""
what	= ""

> </show_job_chain>

<show_job_chains/>

Shows the job chain.

Parent Elements

<commands> -

Attributes

job_chain="" The job chain name

max_orders=""

max_order_history=""

what=""

XML Element <show_job_chains>

<show_job_chains

what	= ""
max_orders	= ""
max_order_history	= ""

> </show_job_chains>

<show_job_chains/>
        

Invisible job chains ( <job_chain visible="no"> ) will not be shown.

Parent Elements

<commands> -

Attributes

what=""

max_orders=""

max_order_history=""

XML Element <show_jobs>

<show_jobs

what	= ""
max_orders	= ""
max_task_history	= ""

> </show_jobs>

<show_jobs/>
        

Invisible jobs ( <job visible="no"> ) will not be shown.

Parent Elements

<commands> -

Attributes

what=""

max_orders=""

max_task_history=""

XML Element <show_order>

<show_order

job_chain	= "name"
order	= "id"
history_id	= "integer"
what	= ""

> </show_order>

Shows either the current order or an order out of the history.

    <show_order job_chain="my_job_chain" order="E4711"/>

        

Parent Elements

<commands> -

Attributes

job_chain="name"

The name of the job chain.

order="id"

The order identifier.

history_id="integer"

Completed orders are saved in the Job Scheduler database history. This can lead to there being more than one entry being made in the history under a particular order id, for example, when an order repeated because of the <run_time> setting. Each history entry has a history id which can be used to access the entry. The order attribute is then no longer required.

The history ID is returned by <show_job_chain what="order_history"> .

what=""

XML Element <show_state>

<show_state

what	= "what"
max_orders	= "integer"

> </show_state>

The name of the show_state element may be shortened to s.

<show_state/>
<show_state what="job_chain_orders,job_orders"/>
        

Parent Elements

<commands> -

Attributes

what="what"

(Note that this description applies to all commands; note however that some keywords will not make sense for all commands.)

The Job Scheduler filters command replies so that they do not become unnecessarily large. The following key words may be used (if combined, then separated with a comma) to extend command replies.

max_orders="integer"

Limits the number of orders that can be returned.

XML Element <show_task>

<show_task

id	= "number"
what	= ""

> </show_task>

Shows information for a current task or for a task out of the history.

<show_task id="4711"/>
        

Parent Elements

<commands> -

Attributes

id="number"

The task id.

what=""

XML Element <start_job>

<start_job

job	= "job_name"
name	= "name"
after	= "number"
at	= "yyyy-mm-dd hh:mm:ss | now | period"
force	= "yes|no"
web_service	= "name"

>

environment
params	Parameters

</start_job>

    <start_job job="my_job" at="now">

    <params>
        <param name="number" value="100"/>
    
    </params>
</start_job>
        

Parent Elements

<commands> -

Attributes

job="job_name"

The job name.

name="name"

A task can be given a name here.

after="number"

A delay - the number of seconds after which a task should be started.

at="yyyy-mm-dd hh:mm:ss | now | period" (Initial value:now)

The time at which a task is to be started. Note that the default force="yes" setting deactivates <run_time> .

Relative times - "now", "now + HH:MM[:SS]" and "now + SECONDS" - are allowed.

at="period" allows a job to start when allowed by <run_time> (that is in the current or next period).

force="yes|no" (Initial value:yes)

force="no":

• This parameter has no effect, if it is applied to a job that has already been stopped.
• The Job Scheduler postpones the start until the next period when a start time is specified using at= that is not allowed by either <run_time> or <schedule> .
• This means that at="now" functions similarly to at="period".

force="yes":

• This attribute will immediately cause a job that has been stopped to be unstopped.
• <run_time> and <schedule> are ignored when start times are specified using at=. This means that tasks will be started at the time specified when periods have not been specified.

web_service="name"

After a task has been executed, it is transformed with a style sheet and handed over to a Web Service.

See <web_service> .

XML Element <terminate>

<terminate

all_schedulers	= "yes|no"
restart	= "yes|no"
continue_exclusive_operation	= "yes|no"
timeout	= "seconds"

> </terminate>

Correct termination of the Job Scheduler (see Terminating the Job Scheduler).

<terminate>

Parent Elements

<commands> -

Attributes

all_schedulers="yes|no" (Initial value:no)

Causes all participating Job Schedulers to be stopped when used in conjunction with -exclusive

restart="yes|no" (Initial value:no)

Causess the Job Scheduler to restart.

continue_exclusive_operation="yes|no" (Initial value:no)

Causes an inactive Job Scheduler to take over operation when set in conjunction with -exclusive .

timeout="seconds"

When specified, causes the Job Scheduler to break off all tasks still running after the time specified.

XML Element <xml_payload>

<xml_payload > </xml_payload>

The <xml_payload> contains a single XML element (with unlimited child elements). The Order.xml_payload property contains this element as XML text.

Parent Elements

<order> -

<add_order> -

<modify_order> -

XML Elements

XML Element <answer>

<answer

time

= "yyyy-mm-dd hh:mm:ss.mmm"

>

ERROR	Error Messages
history	Task-History
job	Job
job_chain	Job Chain
order	Order
process_classes	Process Classes
ok	Simple Answer
log_categories	Log Categories
state	General Status of the Job Scheduler
task	Tasks

</answer>

The Job Scheduler only returns one of the child elements.

Parent Elements

<spooler> -

Attributes

time="yyyy-mm-dd hh:mm:ss.mmm"

The answer time stamp.

XML Element <ERROR>

<ERROR

time	= "yyyy-mm-dd hh:mm:ss"	Timestamp
class	= "name"	Name of the (C++) exception class
code	= "text"	Error code
text	= "text"	Error code and error text
source	= "filename"	Name of the file containing the error
line	= "number"	Line Number
col	= "number"	Column Number

> </ERROR>

Parent Elements

<answer> - Answer

<job> - Job

<task> - Tasks

Attributes

time="yyyy-mm-dd hh:mm:ss" Timestamp

class="name" Name of the (C++) exception class

code="text" Error code

text="text" Error code and error text

source="filename" Name of the file containing the error

the error file name, should it be possible to associate the error with a file.

line="number" Line Number

the line number (starting from 1) in which the error occurs, should it be possible to associate the error with a particular line.

col="number" Column Number

the number of the column in which the error occurs (starting from 1), should it be possible to associate the error with a particular column.

XML Element <file_based>

<file_based

filename	= ""	File name
last_write_time	= ""	The file timestamp in UTC
state	= ""

>

ERROR	Error Messages
removed	The incomplete removal of an object

</file_based>

Parent Elements

<process_class> -

<lock> -

<job> - Job

<job_chain> - Job Chain

<order> - Order

Attributes

filename="" File name

last_write_time="" The file timestamp in UTC

state=""

one of the following values: undefined, not_initialized, initialized, loaded, active and closed.

XML Element <history>

<history >

history.entry

Entry in the Task History

</history>

The History is read from the database.

Parent Elements

<history> - Task-History

XML Element <history.entry>

<history.entry

task	= "number"	Task id
id	= "number"	Task id (out of date)
spooler_id	= "name"	Scheduler id
job_name	= "name"	Job name
start_time	= "yyyy-mm-dd hh:mm:ss"	The task start time
end_time	= "yyyy-mm-dd hh:mm:ss"	The task end time
cause	= "cause"	The Reason for the start
steps	= "number"	Number of job steps
error	= "0|1"	"1" for a job error
error_code	= "text"	Error code
error_text	= "text"	Error code with error text

>

ERROR

Error Messages

</history.entry>

The History is read from the database.

Parent Elements

<history> - Task-History

Attributes

task="number" Task id

id="number" Task id (out of date)

Use the attribute task=.

spooler_id="name" Scheduler id

The Job Scheduler id (or "-", should the scheduler not have an id).

job_name="name" Job name

start_time="yyyy-mm-dd hh:mm:ss" The task start time

end_time="yyyy-mm-dd hh:mm:ss" The task end time

cause="cause" The Reason for the start

See <task cause="…">

steps="number" Number of job steps

error="0|1" "1" for a job error

error_code="text" Error code

The <ERROR> element will be returned instead of this attribute within <job> .

error_text="text" Error code with error text

The <ERROR> element will be returned instead of this attribute within <job> .

XML Element <job>

<job

job	= "name"	Job name
state	= "name"	State
waiting_for_process	= "yes|no"	When a job is waiting for a process
all_steps	= "number"	The number of job steps for all tasks
all_tasks	= "number"	The number of tasks already started
state_text	= "text"	The properties of job.state_text
log_file	= "dateiname"	The name of the protocol file
order	= "yes|no"	For order controlled jobs
tasks	= "number"	Maximum number of tasks allowed
next_start_time	= "yyyy-mm-dd hh:mm:ss.mmm"	Next planned start time
delay_after_error	= "yyyy-mm-dd hh:mm:ss.mmm"	delay_after_error takes effect after an error
in_period	= "yes|no"	When a <period> is valid
has_description	= "yes"	yes, when a job has a <description>
remove	= "yes"	yes, when a job is removed
temporary	= "yes"	yes, when a job is temporary

>

tasks	List of Tasks Currently Running
description
commands
params
lock.requestor
queued_tasks	Number of Queued Tasks
history	Task-History
order_queue	Order Queue
ERROR	Error Messages

</job>

Parent Elements

<jobs> -

<answer> - Answer

Attributes

job="name" Job name

state="name" State

state="none"	The initial status of a job as the Job Scheduler starts.
state="stopping"	The job has been stopped and not all tasks have ended.
state="stopped"	The job has been stopped and all tasks have ended.
state="read_error"	The status when <script> cannot be read.
state="pending"	No task is running.
state="running"	At least one task is running.

waiting_for_process="yes|no" (Initial value:no) When a job is waiting for a process

This occurs when a job attempts to start a task but the process class is not large enough.

See <job process_class="…"> .

all_steps="number" The number of job steps for all tasks

all_tasks="number" The number of tasks already started

state_text="text" The properties of job.state_text

See Job.state_text .

log_file="dateiname" The name of the protocol file

order="yes|no" (Initial value:no) For order controlled jobs

See <job order="…"> .

tasks="number" Maximum number of tasks allowed

See <job tasks="…"> .

next_start_time="yyyy-mm-dd hh:mm:ss.mmm" Next planned start time

delay_after_error="yyyy-mm-dd hh:mm:ss.mmm" delay_after_error takes effect after an error

in_period="yes|no" When a <period> is valid

has_description="yes" yes, when a job has a <description>

remove="yes" yes, when a job is removed

See <modify_job cmd="remove"> .

temporary="yes" yes, when a job is temporary

See <job temporary="yes"> .

XML Element <job_chain>

<job_chain

name	= "name"	Name of the job chain
orders	= "number"	Number of orders in the job chain
state	= "The job chain state"

>

job_chain_node

Position in a Job Chain

</job_chain>

Parent Elements

<job_chains> -

Attributes

name="name" Name of the job chain

orders="number" Number of orders in the job chain

state="The job chain state"

state="under_construction"	The initial state after Spooler.create_job_chain() .
state="finished"	After Spooler.add_job_chain() .
state="removing"	After Job_chain.remove() , and as long as orders are being executed.

XML Element <job_chain_node>

<job_chain_node

state	= "text"	Order state which has been assigned to this position in the job chain
next_state	= "text"	Next state for this order after successful processing
error_state	= "text"	Order state after an error
orders	= "number"	Number of orders at a given position in the job chain

>

job

Job

</job_chain_node>

Parent Elements

<job_chain> - Job Chain

Attributes

state="text" Order state which has been assigned to this position in the job chain

next_state="text" Next state for this order after successful processing

error_state="text" Order state after an error

orders="number" Number of orders at a given position in the job chain

XML Element <log>

<log

level	= "log_level"	The minimum level at which output is allowed
highest_level	= "log_level"	The highest level used
last_error	= "string"	The last output produced by the error level
last_warning	= "string"	The last output produced by the warning level
mail_on_error	= "boolean"
mail_on_warning	= "boolean"
mail_on_success	= "boolean"
mail_on_process	= "integer"
smtp	= "name"
mail_from	= "email_adresse"
mail_to	= "email_adresse"
mail_cc	= "email_adresse"
mail_bcc	= "email_adresse"
mail_subject	= "email_subject"

> </log>

The content of <log> is the protocol (when requested with what="log").

Parent Elements

<job> - Job

<task> - Tasks

Attributes

level="log_level" The minimum level at which output is allowed

See

highest_level="log_level" The highest level used

last_error="string" The last output produced by the error level

last_warning="string" The last output produced by the warning level

mail_on_error="boolean"

See factory.ini (section [spooler], entry mail_on_error= …)

mail_on_warning="boolean"

See factory.ini (section [spooler], entry mail_on_warning= …)

mail_on_success="boolean"

See factory.ini (section [spooler], entry mail_on_success= …)

mail_on_process="integer"

See factory.ini (section [spooler], entry mail_on_process= …)

smtp="name"

See factory.ini (section [spooler], entry smtp= …)

mail_from="email_adresse"

See factory.ini (section [spooler], entry log_mail_from= …)

mail_to="email_adresse"

See factory.ini (section [spooler], entry log_mail_to= …)

mail_cc="email_adresse"

See factory.ini (section [spooler], entry log_mail_cc= …)

mail_bcc="email_adresse"

See factory.ini (section [spooler], entry log_mail_bcc= …)

mail_subject="email_subject"

See factory.ini (section [spooler], entry log_mail_subject= …)

XML Element <log_categories>

<log_categories >

log_category

</log_categories>

See also »Log Categories«

Parent Elements

<answer> - Answer

XML Element <ok>

<ok > </ok>

An empty element, with which commands which do not return any other result are acknowledged.

Parent Elements

<answer> - Answer

XML Element <order>

<order

order	= "id"	Order identifier
title	= "text"	Title
state	= "text"	State
job_chain	= "name"	Job chain name
job	= "name"	Job
task	= "id"	Current task identifier
in_process_since	= "yyyy-mm-dd hh:mm:ss.mmm"	Task start Time
state_text	= "text"	State text
priority	= "number"	Priority
created	= "yyyy-mm-dd hh:mm:ss.mmm"	Point in time when an order is created
log_file	= "file name"	Name of the protocol file
setback	= "hh:mm:ss.mmm"	Point in time when an order is to be cancelled
next_start_time	= "yyyy-mm-dd hh:mm:ss.mmm"	Next starting time
web_service	= "name"	Name of the assigned Web Service

>

log	Protocol
run_time
payload

</order>

Parent Elements

<answer> - Answer

<order_queue> - Order Queue

Attributes

order="id" Order identifier

See Order.id

title="text" Title

See Order.title

state="text" State

See Order.state

job_chain="name" Job chain name

See Job_chain.add_order()

job="name" Job

See Order.job

task="id" Current task identifier

in_process_since="yyyy-mm-dd hh:mm:ss.mmm" Task start Time

state_text="text" State text

See Order.state_text .

priority="number" Priority

See Order.priority .

created="yyyy-mm-dd hh:mm:ss.mmm" Point in time when an order is created

log_file="file name" Name of the protocol file

setback="hh:mm:ss.mmm" Point in time when an order is to be cancelled

next_start_time="yyyy-mm-dd hh:mm:ss.mmm" Next starting time

Should this attribute not be specified, then the order will be carried out as soon as possible.

web_service="name" Name of the assigned Web Service

XML Element <order_queue>

<order_queue

length	= "number"	Number of orders in the order queue
next_start_time	= "date"	Starting time for the next order

>

order

Order

</order_queue>

Parent Elements

<job> - Job

Attributes

length="number" Number of orders in the order queue

The number of <order> elements can be zero or limited by the value that is given with the max_orders= or the what="" attributes.

next_start_time="date" Starting time for the next order

XML Element <process_classes>

<process_classes >

process_class

</process_classes>

Parent Elements

<answer> - Answer

XML Element <processes>

<processes >

process

</processes>

Parent Elements

<process_class> -

XML Element <queued_task>

<queued_task

task	= "number"	Task Id
enqueued	= "yyyy-mm-dd hh:mm:ss.mmm"	Time of entry in the task queue
start_at	= "yyyy-mm-dd hh:mm:ss.mmm"	Task start time
name	= "text"	Task Name

>

params

</queued_task>

Parent Elements

<queued_task> - Tasks in the Task Queue

Attributes

task="number" Task Id

enqueued="yyyy-mm-dd hh:mm:ss.mmm" Time of entry in the task queue

start_at="yyyy-mm-dd hh:mm:ss.mmm" Task start time

name="text" Task Name

XML Element <queued_tasks>

<queued_tasks

length

= "number"

Number of tasks in the task queue

>

queued_task

Tasks in the Task Queue

</queued_tasks>

Parent Elements

<job> - Job

Attributes

length="number" Number of tasks in the task queue

XML Element <removed>

<removed >

ERROR

Error Messages

</removed>

Parent Elements

<file_based> - File Based Objects

XML Element <replacement>

<replacement >

process_class
lock
job	Job
job_chain	Job Chain
order	Order

</replacement>

The child element has the same name as the parent element. In the case of the replacement of a job, the nesting appears as <job> <replacement> <job> . The child element contains the new object, with which the Job Scheduler is not able to replace the current object. The Job Scheduler replaces the object to be replaced (i.e. the current object) as soon as it is "free".

Parent Elements

<process_class> -

<lock> -

<job> - Job

<job_chain> - Job Chain

<order> - Order

XML Element <state>

<state

config_file	= "file name"	XML configuration
spooler_id	= "name"	Scheduler id
id	= "name"	Out of date
spooler_running_since	= "yyyy-mm-dd hh:mm:ss"	The start time of the Job Scheduler
wait_until	= "yyyy-mm-dd hh:mm:ss|never"	The next action of the Job Scheduler
state	= "state"	The state of the Job Scheduler
log_file	= "file name"	Name of the main protocol file
version	= "vv.vv.vv yyyy-mm-dd"
pid	= "number"	The Job Scheduler process id
db	= "hostware_file_name"	Database
db_waiting	= "yes|no"	Renew the Job Scheduler database connection
waiting_errno	= "number"	Error on writing a protocol (full disc)
waiting_errno_text	= "text"	The text for the waiting_errno attribute
waiting_errno_filename	= "file name"	The name of the file for which the error occured
loop	= "number"	Internal value: number of server cycles
waits	= "number"	Internal value: the number of waiting states
time	= "yyyy-mm-dd hh:mm:ss"	Out of date
tcp_port	= "integer"
udp_port	= "integer"

>

locks
jobs
job_chains
process_classes	Process Classes
subprocesses	Sub-Processes (dependent processes)
remote_schedulers

</state>

Parent Elements

<answer> - Answer

Attributes

config_file="file name" XML configuration

The name of the XML configuration file.

spooler_id="name" Scheduler id

The Job Scheduler Identifier - see the -id option.

id="name" Out of date

Out of Date. Use the spooler_id= attribute instead.

spooler_running_since="yyyy-mm-dd hh:mm:ss" The start time of the Job Scheduler

wait_until="yyyy-mm-dd hh:mm:ss|never" The next action of the Job Scheduler

state="state" The state of the Job Scheduler

The state of the Job Scheduler can be changed using the <modify_spooler cmd="…"> command.

log_file="file name" Name of the main protocol file

version="vv.vv.vv yyyy-mm-dd"

The Job Scheduler version.

pid="number" The Job Scheduler process id

db="hostware_file_name" Database

The hostware file name of the database. A password set using -password= will be supressed, unless 15 has been set as the licence key code (see sos.ini (section [licence], entry key1= …) and <licence.use> ).

db_waiting="yes|no" (Initial value:no) Renew the Job Scheduler database connection

The db_waiting element is set to "yes", should the Job Scheduler lose its connection with the database and be in the process of reconnecting itself. In this situation the Job Scheduler does not execute any jobs.

waiting_errno="number" Error on writing a protocol (full disc)

When this attribute is set, then the Scheduler waits and only reacts to commands via TCP, UDP or HTTP.

The Scheduler can be restarted using <modify_spooler cmd="continue"> .

waiting_errno_text="text" The text for the waiting_errno attribute

waiting_errno_filename="file name" The name of the file for which the error occured

loop="number" Internal value: number of server cycles

This value increases as the Job Scheduler executes operations such as a job step or a method callup.

waits="number" Internal value: the number of waiting states

This value increases by one each time the Job Scheduler does not have to execute a task and enters a waiting state.

time="yyyy-mm-dd hh:mm:ss" Out of date

Out of Date. Use <answer time="…"> instead.

tcp_port="integer"

udp_port="integer"

XML Element <subprocess>

<subprocess

pid	= "number"	The operating system process id
priority	= "priority"
timeout_at	= "yyyy-mm-dd hh:mm:ss.mmm"	Process time limit
killed	= "yes|no"	Set when a task has just been broken off (killed).

> </subprocess>

Parent Elements

<subprocesses> - Sub-Processes (dependent processes)

Attributes

pid="number" The operating system process id

priority="priority"

The process priority: on Unix systems -20 to 20, on Windows idle, below_normal, normal, above_normal or high.

timeout_at="yyyy-mm-dd hh:mm:ss.mmm" Process time limit

Is set when a process Task.add_pid() is set a time limit.

killed="yes|no" (Initial value:no) Set when a task has just been broken off (killed).

XML Element <subprocesses>

<subprocesses >

subprocess

Subprocesses (dependent processes)

</subprocesses>

Parent Elements

<state> - General Status of the Job Scheduler

<task> - Tasks

XML Element <task>

<task

task	= "number"	Task Id
id	= "number"	(out of date)
state	= "state"	State of a Task
name	= "name"
running_since	= "yyyy-mm-td hh:mm:ss.mmm"
enqueued	= "yyyy-mm-td hh:mm:ss.mmm"
start_at	= "yyyy-mm-td hh:mm:ss.mmm"
idle_since	= "yyyy-mm-td hh:mm:ss.mmm"
in_process_since	= "yyyy-mm-td hh:mm:ss.mmm"
cause	= "cause"
steps	= "number"
log_file	= "file name"
calling	= "text"
pid	= "number"
delayed_after_error_task	= "zahl"
web_service	= "name"	Name of the assigned Web Service

>

subprocesses	Sub-Processes (dependent processes)
log	Protocol
order	Order
ERROR	Error Messages

</task>

Parent Elements

<tasks> - List of Tasks Currently Running

Attributes

task="number" Task Id

id="number" (out of date)

The task id.

("id" is a reserved term in XML and therefore task should be used instead.)

state="state" State of a Task

The following values may be returned:

name="name"

The name of the task (see <start_job> ).

running_since="yyyy-mm-td hh:mm:ss.mmm"

The time when the task was loaded or started: the task start time.

enqueued="yyyy-mm-td hh:mm:ss.mmm"

The time when the task entered the task queue.

start_at="yyyy-mm-td hh:mm:ss.mmm"

The time at which the task should be started (see <start_job at="…"> ).

idle_since="yyyy-mm-td hh:mm:ss.mmm"

The time at which the task state changed to waiting_for_order.

in_process_since="yyyy-mm-td hh:mm:ss.mmm"

The time when the spooler_process() started, that is the time at which the current active job step started.

cause="cause"

The cause of a job start.

steps="number"

The number of completed job steps or calls of the Job.spooler_process() method.

log_file="file name"

The name of the protocol file. This attribute is only set so long as the task is running.

calling="text"

The name of the job method which has just been called up.

pid="number"

The identifier for the process which the task is carrying out.

delayed_after_error_task="zahl"

Wenn diese Task eine Wiederholung einer mit Fehler abgebrochen Task ist (s. Job.delay_after_error ), dann gibt dieses Attribut die Kennung der fehlerhaften Task an.

web_service="name" Name of the assigned Web Service

XML Element <tasks>

<tasks

count

= "number"

>

task

Tasks

</tasks>

Parent Elements

<job> - Job

Attributes

count="number"

The number of tasks currently running.

XML Element <waiting_jobs>

<waiting_jobs

job

= "name"

>

job

Job

</waiting_jobs>

Parent Elements

<process_class> -

Attributes

job="name"