1.7 Command Line Operation

The Job Scheduler is started using a straightforward command.

C:\>…scheduler installation path…\bin\scheduler.exe …\my_scheduler_configuration.xml …

user@host:~>…installation path…/bin/scheduler …/my_scheduler_configuration.xml …

Parameters for the command line operations described here and which are written to the right of the "=" can be set in inverted commas ("") or in apostrophes / single quotes ('').

The Job Scheduler installation program creates the start script - either .\bin\jobscheduler.cmd (Windows) or ./bin/jobscheduler.sh (Unix), in which command line options and environment variables are already set. This script can be modified as required.

Note that the start script and environment variables are described in the »Installation and Configuration« handbook.

The command line can be used in the following ways:

• Starting the Job Scheduler
• Installation of a Windows Service
• Forwarding a Job to a Job Scheduler
• Forwarding an Order to a Running Job Scheduler
• Sending an XML Command to a Running Job Scheduler
• Stopping a Job Scheduler with 'kill'
• Show the XML Schema
• Expand the Java Class Path
• Show Version Number

Starting the Job Scheduler

The scheduler file name must be completely and absolutely specified and be given an ".exe" ending on Windows systems. This is because the Job Scheduler requires the complete file name in order to be able to start either a job or itself.

c:\bin\scheduler.exe c:\scheduler\config.xml -log-dir=c:\scheduler\logs

Installation of a Windows Service

Forwarding a Job to a Job Scheduler

A temporary job is forwarded to the target Job Scheduler, which is addressed using -scheduler =host:port .

This job only exists until the Job Scheduler is restarted.

echo ls -l | scheduler -scheduler=localhost:4444 -at="2006-04-04 12:00"

Forwarding an Order to a Running Job Scheduler

-scheduler =host:port is used to define the Job Scheduler which an order is forwarded to.

The order parameters (see Order.payload ) can be forwarded to the command line in the form:name = value.

scheduler -scheduler=localhost:4444 -job-chain=my_job_chain -order-id=123 city=Berlin phone="+4930 864790-0" 

Sending an XML Command to a Running Job Scheduler

Stopping a Job Scheduler with 'kill'

scheduler -kill -pid-file=/home/scheduler/scheduler.pid

Show the XML Schema

Expand the Java Class Path

Show Version Number

Options

-config=file_name Configuration file

Defines the Configuration File.

The "-config=" prefix before file names can be omitted.

This option specifies the configuration file or configuration directory. Should a configuration directory be specified, then the Job Scheduler will expect to find the configuration file in the configuration directory, under the name scheduler.xml.

The factory.ini (section [spooler], entry config= …) setting is overwritten by this parameter.

-log=file_name scheduler.log file name

This setting causes the Job Scheduler to write a detailed protocol. This protocol is intended for use in problem diagnosis. The file name should be fully specified here (i.e. as a full path).

A plus character (+) written directly before the file name causes an already existing protocol to be continued. Otherwise such a protocol will be overwritten.

Categories can be used to extend or restrict the log file. Category names are added (separated by spaces) before the file name, which is then preceded by a larger than (>) sign.

The list of categories can be found here.

log = c:/tmp/scheduler.log
log = scheduler.wait >scheduler.log
log = scheduler.wait com_server.* >scheduler.log
        

The factory.ini (section [spooler], entry log= …) setting is overwritten by this parameter.

-log-dir=directory Protocol directory

The directory in which the Job Scheduler writes log files.

log_dir= *stderr allows the Job Scheduler to write log files to the standard output (stderr, normally the screen) .

The factory.ini (section [spooler], entry log_dir= …) setting is overwritten by this parameter.

-id=scheduler_id Job Scheduler identifier (id)

The Job Scheduler only selects elements in the XML configuration whose spooler_id attributes are either empty or set to the value given here.

When the Job Scheduler ID is not specified here, then the Job Scheduler ignores the spooler_id= XML attribute and selects all the elements in the XML configuration.

See, for example, <config> .

The factory.ini (section [spooler], entry id= …) setting is overwritten by this parameter.

-cd=directory Working Directory

Changes the Working Directory.

-pid-file=File Name File name for process ID

On Unix systems: the Job Scheduler writes its process ID (PID) in this file. This file is deleted by the Job Scheduler on stopping.

-log-level=log_level (Initial value: info)     Limit protocol level

Defines the level with which protocol entries should be written. Every protocol entry is given one of the following categories: error, warn, info, debug1 to debug9 (debug1 is the same as debug).

The factory.ini (section [job], entry log_level= info) setting is overwritten by this parameter.

The factory.ini (section [spooler], entry log_level= info) setting is overwritten by this parameter.

-param=text For free use

Free text. This parameter can be read using spooler.param.

The factory.ini (section [spooler], entry param= …) setting is overwritten by this parameter.

-include-path=directory Directory path for <include>

The directory of the files which are to be included by the <include> element.

Environment variables (e.g. $HOME) are replaced by this attribute (see Settings which Allow Environment Variables to be Called).

The factory.ini (section [spooler], entry include_path= …) setting is overwritten by this parameter.

<config include_path="…"> is overwritten by this parameter.

-port=number (Initial value: 0)     HTTP, TCP and UDP ports for control commands for the Job Scheduler

Combines the tcp_port and udp_port settings.

See also -tcp-port and -udp-port .

Note that if a port is blocked, the Job Scheduler will attempt to access it for two minutes before terminating itself.

<config port="…"> is overwritten by this parameter.

-tcp-port=number (Initial value: 0)     Port for HTTP and TCP commands for the Job Scheduler

The Job Scheduler can accept commands via a TCP port whilst it is running. The number of this port is set here - depending on the operating system - with a number between 2048 and 65535. The default value is 4444.

The Job Scheduler operates a HTTP/HTML server on the same port, enabling it to be reached using a web browser - e.g. via http://localhost:4444.

The Job Scheduler does not respond to the tcp_port=0 default setting either with TCP or HTTP protocols. This setting can therefore be used to block a Job Scheduler from being accessed - for example via TCP.

See also -port .

<config tcp_port="…"> is overwritten by this parameter.

-udp-port=number (Initial value: 0)     Port for UDP commands for the Job Scheduler

The Job Scheduler can also accept UDP commands addressed to the port specified in this setting. Note that a UDP command must fit in a message and that the Job Scheduler does not answer UDP commands.

The default value of udp_port=0 does not allow the Job Scheduler to open a UDP port.

See also -port .

<config udp_port="…"> is overwritten by this parameter.

-ip-address=ip_number (Initial value: 0.0.0.0)     The interface IP address for TCP and UDP

The IP address to which the TCP and UDP ports are bound. The Job Scheduler can then only be reached by way of this address.

A host name can also be specified.

The default setting is 0.0.0.0, which stands for all IP addresses.

When another IP address as 127.0.0.1 or localhost is given, then the Job Scheduler cannot be reached by way of localhost.

<config ip_address="…"> is overwritten by this parameter.

-reuse-port Reuse of the TCP and UDP ports

This option should only be used in exceptional situations, as it switches off the test whether or not a port has been set free by the operating system.

Calls setsockopt(socket,SOL_SOCKET,SO_REUSEADDR,true).

This option should only be used in an emergency, should a port be permanently blocked by the operating system although it is no longer used by an application. This can happen with Windows XP, when an application is terminated by a debugger and UNIX can take up to a minute to release a port.

In some situations the Job Scheduler cannot be reached with -reuse-port via TCP or UDP, when the port is being used by other applications. The use of -reuse-port is not recommended.

-cmd=xmlcommand Immediately executed commands

The Job Scheduler executes xml commands such as <start_job> immediately on starting.

-ini=file name Alternative factory.ini file

Specifies the Path/ Name for an alternative factory.ini file.

When references in this documentation are made to the factory.ini file, it should be clear that the value given in this option is meant.

See also Spooler.ini_path

-sos.ini=file name Alternative sos.ini file

Specifies the Path/ Name for an alternative sos.ini global configuration file. Note that this file contains the Job Scheduler license key.

-program-file=file name Job Scheduler file name

This option is used when the Job Scheduler is called from a Java class file (for example, when debugging) and jobs are to be started in their own processes.

-service Start as a daemon

The Job Scheduler runs in the background on Unix systems , which means that output cannot be written to the terminal.

Under Unix the Job Scheduler stdin, stdout und stderr und directs the output to the scheduler.out file, which must remain writable.

-validate-xml Validate XML Ddocuments against an embedded schema

-validate-xml- switches the validation off (should the schema have errors).

See -show-xml-schema .

-env=name=value Set Environment Variables

-env=NAME=VALUE sets the NAME environment variable.

Messages

[ERROR]

SCHEDULER-318

Option -env=NAME=VALUE: missing '=' between name and value: -env=""

-exclusive Starts the Job Scheduler for Exclusive Service

Requires use of a database - see factory.ini (section [spooler], entry db= …).

More than one Job Scheduler with the same Scheduler-Id ( -id ) and the same database can be started with -exclusive. In this case, then only one Job Scheduler will become active. It is only after this active Job Scheduler fails or is stopped ( <terminate shutdown="no"> ), that another Job Scheduler will become active and take over operation. The takeover takes approximately one minute.

Warning: All participating Job Schedulers must be started -exclusive or -distributed-orders . When one Job Scheduler is started with and one without this setting, then two Job Schedulers will run simultaneously, which can lead to unexpected results.

See also -backup .

Messages

[ERROR]	SCHEDULER-357	This is a member of a cluster (option -exclusive or -distributed-orders), and therefore needs a database
[ERROR]	SCHEDULER-358	This is a member of a cluster (option -exclusive or -distributed-orders), and therefore needs a database. need_db= is not allowed
[ERROR]	SCHEDULER-359	For an exclusive or distributed Scheduler, the database is not supported
[ERROR]	SCHEDULER-362	Scheduler is aborting because it has become inactive
[ERROR]	SCHEDULER-365	Illegal character in -id=
[ERROR]	SCHEDULER-367	Scheduler is aborting because it has lost its exclusivity
[ERROR]	SCHEDULER-371	DATABASE INTEGRITY IS BROKEN
[ERROR]	SCHEDULER-372	Exclusivity has been stolen by Scheduler member ''
[ERROR]	SCHEDULER-377	After own late heart beat, Scheduler member '' has taken exclusiveness
[ERROR]	SCHEDULER-381	Scheduler is not yet active and cannot execute the operation
[ERROR]	SCHEDULER-386	Last heart beat was time, seconds ago. Something is delaying Scheduler execution, the Scheduler is aborted immediately
[warn]	SCHEDULER-823	Dead Scheduler member 'cluster_member_id' has resurrected
[warn]	SCHEDULER-827	Own heart beat is late: next_heart_beat has been announced for (this is seconds late)
[warn]	SCHEDULER-836	Deactivating that dead Scheduler
[warn]	SCHEDULER-837	Taking exclusiveness from that Scheduler
[warn]	SCHEDULER-994	No heart beat for seconds (time), expecting heart beat within seconds
[warn]	SCHEDULER-996	No heart beat for seconds (time) - Scheduler seems to be dead
[warn]	SCHEDULER-997	Making up an extra heart beat
[info]	SCHEDULER-805	No Scheduler is active
[info]	SCHEDULER-807	Using database product
[info]	SCHEDULER-811	Executing command read from database:
[info]	SCHEDULER-814	Inactive Scheduler '' has the higher backup precedence (http_url)
[info]	SCHEDULER-819	Scheduler becomes active
[info]	SCHEDULER-820	Watching heart beat of that Scheduler
[info]	SCHEDULER-821	Scheduler member 'cluster_member_id' seems to be active, claiming its last heart beat was s ago (pid=, url)
[info]	SCHEDULER-822	Scheduler member 'cluster_member_id' seems to be exclusive, claiming its last heart beat was s ago (pid=, url)
[info]	SCHEDULER-825	No exclusive Scheduler is running
[info]	SCHEDULER-826	That Scheduler has terminated
[info]	SCHEDULER-831	Waiting s for start of non-backup Scheduler
[info]	SCHEDULER-832	This is a backup Scheduler, waiting for a non-backup Scheduler
[info]	SCHEDULER-833	Watching heart beat of that exclusive Scheduler, standing by to take over operation
[info]	SCHEDULER-834	Active Scheduler has terminated properly
[info]	SCHEDULER-835	This Scheduler is becoming exclusive now
[info]	SCHEDULER-838	. heart beat detected
[info]	SCHEDULER-995	No heart beat for seconds (time), ignored for seconds because of recent database reconnect

-backup Starts a Job Scheduler as a Backup Scheduler

Only possible in combination with -exclusive .

A backup Job Scheduler only takes over operation - it cannot start a new operation. This means that after <terminate continue_exclusive_operation="no"> the backup Job Scheduler does not start, but waits for another Job Scheduler to start operation.

-backup is allocated its own service name when used together with -install-service and -remove-service . This means that the backup Job Scheduler can be run on the same computer as the active Job Scheduler as its own service.

The name of the main log file contains the "_backup" suffix.

-backup-precedence=integer (Initial value: 1)     Priority Amongst Backup Job Schedulers

Only possible in combination with -exclusive .

When more than one inactive backup Job Schedulers are available to replace a failed Job Scheduler, ( -exclusive ), then operation is taken over by the Job Scheduler allocated the lowest -backup-precedence value.

Note that it is possible for another Job Scheduler as that dictated by the highest backup-precedence to take over operation, should the backup Job Schedulers run on different computers and should the clocks of these computers not be synchronized,

The default value is 1, when -backup is set, otherwise it is 0.

-distributed-orders Distributed Orders

Requires use of a database (). More than one Job Schedulers can share the execution of orders, when they are all started under the same Scheduler-Id ( -id ), use the same database and the same configuration.

<job_chain distributed="yes"> allows a job chain to be used for distributed operation.

Messages

[ERROR]	SCHEDULER-357	This is a member of a cluster (option -exclusive or -distributed-orders), and therefore needs a database
[ERROR]	SCHEDULER-358	This is a member of a cluster (option -exclusive or -distributed-orders), and therefore needs a database. need_db= is not allowed
[ERROR]	SCHEDULER-361	No database
[ERROR]	SCHEDULER-370	Operation can only be performed on a distributed orders Scheduler
[ERROR]	SCHEDULER-373	UNEXPECTED DEACTIVATION BY SCHEDULER MEMBER
[ERROR]	SCHEDULER-375	Order is distributed and therefore does not support operation ''
[ERROR]	SCHEDULER-378	After own late heart beat, this Scheduler has been deactivated and the occupied orders have been freed by Scheduler member ''
[ERROR]	SCHEDULER-379	order is occupied by Scheduler member ''
[ERROR]	SCHEDULER-380	job_chain orders_recoverable="no" cannot be combined with distributed="yes", in
[ERROR]	SCHEDULER-384	job_chain is distributed and therefore does not support operation ''
[ERROR]	SCHEDULER-385	Deletion of order in database has failed
[warn]	SCHEDULER-812	Just before processing, order record in database has been occupied or removed
[warn]	SCHEDULER-816	Unable to release occupation in database
[warn]	SCHEDULER-817	Missing order record in database
[info]	SCHEDULER-813	Order is occupied by Scheduler ''
[info]	SCHEDULER-815	Task should end but it has just been started with an order attached, so one step will be done
[info]	SCHEDULER-829	Releasing occupied order job_chain:id
[info]	SCHEDULER-830	Because all Scheduler tasks have been killed, the order in database has not been updated. Only the occupation has been released
[info]	SCHEDULER-879	Deactivating old cluster member with same ID

-configuration-directory Configuration directory

The default directory is the live directory, which is specified in the ( -config ).

The Job Scheduler looks in this directory for jobs, job chains, permanent orders, process classes and locks.

-install-service=name Install as a Windows service

The Job Scheduler is not started by this option but installed as a Windows service. In this case the following command line options may be specified:

-cd

Note that -install-service= name is the same as -install-service -service-name= name.

-remove-service=name Remove a Windows service

Removes a service which was previously installed using -install-service.

-remove-service= name is the same as -remove-service -service-name= name.

-service-name=name (Initial value: sos_scheduler)     Windows service internal name

Only used together with -install-service or -remove-service. When this option is missing but -id=is specified, then the Job Scheduler uses the name sos_scheduler_ scheduler_id. If -backup has been set, then this option adds _backup.

-service-display=text Windows service name

Only used in conjunction with the -install-service. This name is shown by the Windows service controller. It may contain spaces. Should this option not be specified, the Job Scheduler creates a name from the service name (see -service-name=).

-service-descr=text Windows service description

Only used together with the -install-service.

-need-service=name Service required by the Job Scheduler (Windows only)

This option specifies a service such as a database server which must be running before Windows starts the Job Scheduler. This option must be used in conjunction with the -install-service.

This option can be repeated should the Job Scheduler require a number of services.

-scheduler=host:port The Job Scheduler TCP address

The name (or IP number) and port number of the Job Scheduler being addressed.

-log=file_name scheduler.log file name

This setting causes the Job Scheduler to write a detailed protocol. This protocol is intended for use in problem diagnosis. The file name should be fully specified here (i.e. as a full path).

A plus character (+) written directly before the file name causes an already existing protocol to be continued. Otherwise such a protocol will be overwritten.

Categories can be used to extend or restrict the log file. Category names are added (separated by spaces) before the file name, which is then preceded by a larger than (>) sign.

The list of categories can be found here.

log = c:/tmp/scheduler.log
log = scheduler.wait >scheduler.log
log = scheduler.wait com_server.* >scheduler.log
        

The factory.ini (section [spooler], entry log= …) setting is overwritten by this parameter.

-process-class=name

The name of the temporary job process class -, see <job process_class="…"> .

-language=script_language (Initial value: shell)     The Job Script language

Script language, see <script language="…"> .

-at=yyyy-mm-dd HH:MM (Initial value: now)     Start time

Start time - in the form "yyyy-mm-dd HH:MM[:SS]". See <at at="…"> .

A job will not be started after its start time has been passed.

The Job Scheduler uses the current time from the computer on which it is running when, for example, starting jobs.

-at=now is the default setting and causes a job to be started immediately.

-scheduler

-log

-job-chain=name Job Chain

The name of the job chain on which an order is to be run - see <add_order job_chain="…"> .

-order-id=id The Order ID

The order identifier - see <add_order id="…"> .

-title=text The Order Title

An order can be given a title. See <add_order title="…"> .

-tcp-port

-send-cmd=xmlcommand Sending a command to another Job Scheduler

This option does not start a Job Scheduler but sends an XML command to another Job Scheduler on the same computer which has the same -tcp-port= option. This can be, for example, <terminate> : -send-cmd="<terminate/>"

This command is sent to the IP address specified in the <config ip_address="…"> attribute or, should this not have been set, to 127.0.0.1.

-kill Stopping a Running Job Scheduler using 'kill'

Stops a Job Scheduler whose process is specified in the -pid-file file. The Scheduler is stopped using kill -SIGKILL.

-kill=pid Stopping a Running Job Scheduler with 'kill'

Stops the process with the specified PID using kill -SIGKILL.

-pid-file=dateiname

-show-xml-schema Writes the XML schema to stdout

The Job Scheduler comes with its own XML schema which XML commands and the XML configuration must conform to.

See the Job Scheduler XML Schema.

-expand-classpath Expand the Java Class Path

Expands the Java Class Path, which is specified as a parameter. This means that jokers are processed as sos.ini (section [java], entry class_path= …).

The Job Scheduler writes the results to stdout. Unless otherwise specified in an option, the Job Scheduler will then terminate itself, without any other output.

export CLASSPATH="`scheduler -expand-classpath='/opt/java/lib/*.jar'`"

-V Show Version Number

Causes the Job Scheduler to output its version number and date when starting.