Using iWay Service Manager Command Line Console

In this section:

This section provides an overview of the Service Manager cron and schedule command line console.


Top of page

x
Command Line Basics

The iSM command line console is available directly from the command line of the server when the Service Manager is started as a standalone Java application. If the Service Manager is running as a background task (either as a Windows Started Task or as a UNIX daemon), a telnet connection to the Service Manager can be used.



x
Command Line Help

Use the help system of the Command Line to see if the Service Manager Schedule is installed. Type help after the Enter command:> prompt. If the scheduler has been properly installed, you should see cron and schedule in the listing of commands and descriptions that follows.

The schedule and cron commands also provide help for the user. To access either the schedule or cron help type either of the following commands after the command prompt:

help schedule
help cron

The following image shows the help schedule command screen:

The following image shows the cron help command screen:


Top of page

x
iWay Service Manager Cron Command Console

The cron command allows you to add, suspend, resume or cancel tasks during the current instance of the Service Manager. Unless otherwise noted in the function, tasks that are scheduled using the command console will not be saved in the repository of Service Manager nor will they be carried over from one instance of the Service Manager to the next when recycled.

Note: The preferred way to Schedule a recurring task is to use the Schedule Provider found in the iWay Service Manager Administration Console.

The cron command console was modeled after the UNIX cron and crontab entry. Most UNIX operating systems have a cron utility that allows tasks to be automatically run in the background at regular intervals by a cron daemon. These tasks are often termed as cron jobs in UNIX. To manage those cron jobs, a file called crontab (short for CRON TABle) is used. This file contains one or more lines, each line a cron job entry to be run at specified times based on the parameters of the line.



x
Listing a Task

Entering the command cron or cron list produces a listing of all currently scheduled iWay Service Manager tasks. To list one or all of the currently scheduled Service Manager tasks, the general command format is:

cron [list [-name task] | [-all]]

Parameter

Description

-name

Is the name or partial name of the task. The name can contain only part of a task name, for example, t to list all tasks that start with the letter t, te to list all tasks that start with the letters te, and so on.

-all

When the list command is issued without the all parameter, only active tasks are listed. Tasks that are suspended are not displayed. Using the -all parameter lists both active and suspended tasks.

The following image shows an example of the schedule list output.

Entering the command cron list -name <value> (in the following example case 'g*') produces a list of tasks that start with the value g. The following image shows an example of the schedule list -name function output.



x
Adding a Task

Unlike the schedule command of iSM, the cron command is very dependent on parameter positioning. Because the cron command emulates a crontab file entry, the first five fields following the cron add command specifies the day, date, and time followed by the command to be run at that interval. The table below shows the order (from top to bottom) and value of the first five fields that follow the cron add command.

Order

Value

Minutes

* or (0 - 59)

Hours

* or (0 - 23)

dayOfMonth

* or (1 - 31)

Month

* or (1 - 12)

Weekday

* or (0 - 6)

Command

Command to be executed.

Note:

Entering the command cron add will add a new task to the Scheduler. The general command format is:

cron add minutes hours dayOfMonth month weekday command -name taskName
   [[-active][-description ...][-user ... -password ...]
[-save]]

If -active flag is included in the command line, the task is immediately scheduled to run at the next scheduled time.

Parameters

Description

Minutes

A numeric value between 0 and 59 representing when within the hour the task should run.

Optional * = all minutes in the hour (same as 0-59).

Hours

A numeric value between 0 and 23 (where 0=12am, 23=11pm) representing when within the day the task should run.

Optional * = all hours in the day (same as 0-23).

dayOfMonth

A numeric value between 1 and 31 representing what day in the month the task should run.

Optional * = all days in the month).

Month

A numeric value between 1 and 12 (where 1=January, 12=December) representing what month the task should run. Alternately the name of the months may also be used, for example: January[jan], February[feb], March[mar], and so on.

Optional * = all months in the year (same as 1-12).

Weekday

A numeric value representing what day of the week the task should run, Sunday (0) through Saturday (6).

Alternately the name of the weekday may also be used, for example: Sunday[sun], Monday[mon], Tuesday[tue], Wednesday[wed], and so on.

Optional * = all days of the week (same as 0-6).

Command

The iSM command, for example, start listenerName, stop listenerName, ... that the task will execute. (For more information, see the iWay Service Manager User’s Guide).

-name

Enter a unique name to associate to the task. This name will be used when looking up the task later.

-description (optional)

Enter a brief description of the task.

-active (optional)

If set to true, the task is scheduled to run immediately.

If the value is false, then the task is not scheduled to run. If it is missing or set to false (the default), the status of the task is set to UNSCHEDULED.

-user (optional)

If the task must be run with an alternate user ID, enter the ID.

-password (optional)

If the task must be run with an alternate user ID, enter the password of the alternate user. (Required if -user is specified, ignored if -user is not included.)

-save (optional)

Save the added scheduled task in the Schedule repository. This ensures that the schedule and any changes are persisted when Service Manager is recycled.

-skipHoliday (optional)

If 'Skip Holidays' flag set ('true'), then the days checked in the Schedule's calendar are skipped.

For example, if you want to execute a shell command to clear the error_log file located in the directory c:wwwapachelogs every day at midnight, issue the following:

cron add 0 0 * * * "!cmd /c set nada=;echo %nada% > c:logserror_log" -name task1

To start up a Service Manager listener called MonthEnd on the last business day of the month (will not start the listener up on Saturday or Sunday) at 8am:

cron add 0 8 @LBDOM * * "start MonthEnd" -name task2

To start up a Service Manager listener called MonthEnd on the last day of the month at 8am:

cron add 0 8 @LD * * "start MonthEnd" -name task3

Note:



x
Canceling a Task

The cron cancel command is used to remove a task or all tasks from the Scheduler of iSM. Any tasks that were canceled (but not saved) will resume as scheduled only when iSM Service Manager restarts.

To cancel a task from the schedule of iWay Service Manager, the general command format is:

cron cancel -name task [-save] | -all]

Parameter

Description

-name

Name of the task to cancel. The named task will be canceled and removed from the Service Managers schedule.

-save

The named task is removed from the Schedule repository of Service Manager and will not be available when Service Manager is restarted.

-all

All tasks currently in the Scheduler of Service Manager are immediately removed.



x
Suspending a Task

The cron suspend command is used to suspend the next scheduling a task (or all tasks) in the Service Manager's Scheduler.

Note: Any tasks that were currently executing will complete execution but will not be rescheduled. The suspend command only prevents the task from being scheduled in the future.

To suspend a task within the schedule of iSM, the general command format is:

cron suspend [-name task]

Parameter

Description

-name

Optional name of the task to suspend. The named task scheduling will be suspended; the task will remain on the Schedule list of iSM with a status of SUSPENDED.

To restart the task at its next regularly scheduled time use the cron resume command.

  1. If -name is not supplied ALL SCHEDULED tasks will be suspended.
  2. If the suspend command is issued while a task is running, the running task is not interrupted but will complete normally and will not be rescheduled.
  3. The suspend command only prevents the task (or tasks) from being scheduled in the future.



x
Resuming a Task

The cron resume function resumes the scheduling of a suspended task (or all tasks) in the scheduler of iSM.

To resume a SUSPENDED task in the schedule of iSM, the general command format is:

cron resume [-name task]

Parameter

Description

-name

Optional name of the task to resume scheduling. The named task execution will be scheduled to start at its next regularly scheduled time.

Notes: If -name is not supplied, all SUSPENDED tasks will be scheduled to execute at their next regularly scheduled time.


Top of page

x
iWay Service Manager Schedule Command Console

The schedule command allows you to add, suspend, resume or cancel tasks during the current instance of the Service Manager. Unless otherwise noted in the function, tasks that are scheduled through the command console will not be saved in the repository of iSM nor will they be carried over from one instance of the Service Manager to the next when recycled.

Unlike the cron interface named parameters may be entered in any order (for example -hour may proceed -minute, -name may follow -command, and so on). The command line input is evaluated from left to right following the schedule command verb (add, list, cancel, or delete). Each parameter is terminated by the start of another named parameter or by a carriage return.

Note: Named parameters are parameters that are proceeded by a dash (‘-’) then the parameter name, for example, -name, -hour, and so on.



x
Listing a Schedule

Entering the command schedule or schedule list produces a listing of all currently scheduled Service Manager tasks. To list one or all of the currently scheduled Service Manager tasks the general command format is:

schedule [list [-name task]]

Parameter

Description

-name

Is the name or partial name of the task. The name can contain only part of a task name, for example, t to list all tasks that start with the letter t, te to list all tasks that start with the letters te, and so on.

-all

When the list command is issued without the all the -all parameter, only active tasks are listed. Tasks that are suspended are not displayed. Using the -all parameter lists both active and suspended tasks.

The following image shows an example of the schedule list output.

Entering the command schedule list -name <value> (in the following example case 'B*') produces a list of tasks that start with the value. The following image shows an example of the schedule list -name function output.

The schedule list displays the following information on the console.

Values

Description

name

Name of the task in the schedule.

parmMap

Parameter of the Task.

Each Scheduler entry in the dictionary represents a job and follows a particular format as a series of fields, separated by spaces and/or tabs. Each field can have a single value or a series of values.

  • min. A number between 0 and 59 that represents what minute of the hour the task should start execution. Zero (0) will start the task at the top of each hour.
  • hrs. A number between 0 and 23 that represents what hour of the day the task should start execution. Zero (0) representing midnight (12 AM); 23 representing 11 PM.
  • desc. Task description.
  • weekday. A number between 0 (Sunday) and 6 (Saturday) that represents what day of the week that the task should run on. In addition to the numerical representation the weekday names or abbreviations may also be used, for example, Sun, Mon, Tue, and so on.
parmMap

(continued)

  • month. A number between 1 (January) and 12 (December) that represents what month that the task should run on. In addition to the numerical representation the month names or abbreviations may also be used, for example, Jan, Feb, Mar, and so on.
  • active. If set to true, this task will be scheduled each and every time the Service Manager is recycled.
  • password. If this task is being executed with the credentials of a different user, enter the password of the user.
  • user. If this task must be executed under the credentials of a different user, enter the User ID to use when executing this task.
  • cmdToExecute. The command that the task will execute when the scheduled time comes. Any Service Manager command may be executed. Some Service Manager commands make more sense than others to schedule as tasks.
  • dependent. Dependent command to run when duration timer expires.
  • monthDay. A number between 1 and 31 that represents what day of the month that the task should run on. In addition to the numbers the following special values may also be entered:
    • @FMOM. First Monday of the month, can be abbreviated as @FM.
    • @LFOM. Last Friday of the month, can be abbreviated as @LF.
    • @LBDOM. Last business day of the month. This value will return the last calendar workday (Monday through Friday) of the month. This value can be abbreviated as @LBD.
    • @LDOM. Last day of the month, can be abbreviated as @LD.
parmMap

(continued)

  • duration. Time between the start of the cmdToExecute and when to start the dependent command.

    There are several ways of specifying multiple date and time values in a field:

    • The comma (,) operator specifies a list of values, for example: 1, 3, 4, 7, 8.
    • The dash (-) operator specifies a range of values, for example: 1 - 6, which is equivalent to 1, 2, 3, 4, 5, 6.
    • The asterisk (*) operator specifies all possible values for a field. For example, an asterisk in the hour time field would be equivalent to every hour (subject to matching other specified fields).
    • The slash (/) operator (called step), which can be used to skip a given number of values. For example: */3 in the hour time field is equivalent to 0, 3, 6, 9, 12, 15, 18, 21.

    So * specifies every hour, but the */3 means only those hours divisible by 3. The meaning of / specifier, however, means when the modulo is zero rather than every. If an * does not proceed the / (for example, /2, /5, and so on) it directs the scheduler to execute the command every n cycles where is the number that follows the step.

state

Current state of the task. This can be one of the following values:

  • VIRGIN. Task has not been scheduled. This state is an indication that the active flag of the task is set to false.
  • SCHEDULED. Task is scheduled to run.
  • RUNNING. Task is currently running.
  • COMPLETE. Task is complete but has not been rescheduled.
  • CANCELED. Task has been canceled and not rescheduled.
  • ERROR. Task ended in error.
lastTimeRan

Time of day that the task was last ran. A value of 'N/A' indicates that the task has not been run during this instance of the Service Manager.

nextTimeToRun

When the task is scheduled to run again.



x
Adding a Task

The add function adds a task to the schedule of iSM. Tasks added using the command line are immediately added to the schedule. Tasks added using the command line will not be persisted to the repository of iSM unless the -save option is specified in the command line.

The general command line format is:

schedule add [parameters]

Parameters

Description

-name

Enter a unique name to associate to the task. This name will be used when looking up the task later. If -name is missing the Service Manager will generate a name for the task.

-active

A value of either true or false. If true, the task is scheduled to run immediately. If the value is false then the task is not scheduled to run. Optional, if omitted, a false value is assumed.

-minute

A numeric value between 0 and 59 representing when within the hour the task should run. Optional, if omitted, an * is assumed (all minutes in the hour).

-hour

A numeric value between 0 and 23 (where 0 = 12am, 23 = 11pm) representing when within the day the task should run. Optional, if omitted, an * is assumed (all hours in the day).

-day

A numeric value between 1 and 31 representing what day in the month the task should run. Optional, if omitted, an * is assumed (all days in the month).

-month

A numeric value between 1 and 12 (where 1=January, 12=December) representing what month the task should run. Alternately, the text name of the month, (for example, January[jan], February[feb], March[mar],...) can also be used. Optional, if omitted, an * is assumed (all months in the year).

-weekday

A numeric value between 0 and 6 (where 0=Sunday and 6=Saturday) representing what day of the week the task should run. Alternately the text name of the weekdays (for example, Sunday[sun], Monday[mon], Tuesday[tue],...) can also be used. Optional, if omitted, an * is assumed (all days in the week).

-command

The Service Manager command (for example, start listener, stop listener, and so on) that the task will execute. (For more information, see the iWay Service Manager User’s Guide).

-duration

Length of time that the task will run prior to the Dependent Command. The format of duration [in seconds] is in the form [xxh][xxm]xx[s]. For example 04h30m45, which creates a duration of 4 hours, 30 minutes, and 45 seconds.

-dependent

The Service Manager command to be executed after the Duration Timer of the task has expired. (For example, start listener, stop listener, and so on) that the task will execute. (For more information, see the iWay Service Manager User’s Guide).

-user

If the task must be ran with an alternate user ID, enter the ID of the alternate user for the value of this parameter.

-password

If the task must be ran with an alternate user ID, enter the password of the alternate user for the value of this parameter.

-save

Save the added scheduled task in the repository of iSM. This allows the Service Manager to reschedule this task when the current instance is recycled.

Note:

  1. Adding a task with the same name as a currently scheduled task will cause the previously scheduled task (with the same name) to be canceled and this new task to be scheduled in place of the old task.
  2. Time parameters not entered (for example, -minute, -hour, -day, -month, -weekday) will default to the asterisk (*) operator (meaning all valid values for that field).
  3. There are several ways of specifying multiple date/time values in a field: The comma (,) operator specifies a list of values, for example: 1, 3, 4, 7, 8. The dash (-) operator specifies a range of values, for example, 1 - 6, which is equivalent to 1, 2, 3, 4, 5, 6.
  4. The asterisk (*) operator specifies all possible values for a field. For example, an asterisk in the hour time field would be equivalent to every hour (subject to matching other specified fields).
  5. The slash (/) operator (called step), which can be used to skip a given number of values. For example, */3 in the hour time field is equivalent to 0, 3, 6, 9, 12, 15, 18, 21. So * specifies every hour, but the */3 means only those hours divisible by 3. The meaning of */ specifier, however, means 'when the modulo is zero rather than every.

    It the * does not proceed the step (/) (for example, /2, /5, and so on) it directs the scheduler to execute the command every n cycles (minutes, hours, and so on) where n is the number that follows the step (/) character.



x
Adding a Task to Start a Listener

To add a Service Manager task named task2 that will start a listener named checkQueue at the top of the hour, every four hours every day of the week, every month of the year, enter the following command (all one line) following the Enter command:> prompt:

schedule add -name task2 -minute 0 -hour */4 -command start checkQueue

The following image shows the results of the command.



x
Adding a Task to Execute an External Command

To add a Service Manager task named task1 that will clear the file activity.log found in the subdirectory c:\temp every minute of every hour of every day of the week every month of the year, enter the following command (all one line) following the Enter command:> prompt:

schedule add -name task1 -command !cmd /c set x=;echo
 %x%>c:\temp\activity.log!cmd /c set x=;echo %x%>c:\temp\activity.log

The following image shows the results of the command.



x
Canceling a Task

The cancel function removes the named task from the schedule of iSM. The task, if currently processing, completes its processing cycle prior to being canceled.

Canceling a task only removes it from the current instance of the schedule. When iSM is recycled, the task (if persisted in the repository of Service Manager) will be rescheduled.

The general command line format is:

schedule cancel -name task

Parameter

Description

-name

Name of the task to cancel. The named task will be canceled and removed from the Service Managers schedule.

In the image that follows, the iWay Service Manager task ClearTempLog has been canceled.

If the task that is canceled has a dependent task configured, the dependent task is canceled from the Service Managers schedule.



x
Suspending a Task

The suspend function suspends the scheduling of the next invocation of the task by the scheduler of iSM. The task, if currently processing, completes its processing cycle but will not be rescheduled.

The general command line format is:

schedule suspend [-name task]

Parameter

Description

-name

Optional name of the task to suspend. The named task execution will be suspended. The task will remain on the Schedule list of iSM with a status of SUSPENDED.

To restart the task at its next regularly scheduled time, use schedule resume.

Notes:

  1. If -name is not supplied, ALL SCHEDULED tasks will be suspended.
  2. If the suspend command is issued while a task is running, the running task is not interrupted but will complete normally; and will not be rescheduled.
  3. The suspend command only prevents the task (or tasks) from being scheduled in the future.

If the task that is suspended has a dependent task configured, the dependent task is canceled from the Service Managers schedule.



x
Resuming a Task

The resume function resumes the scheduling of a suspended task in the scheduler of iSM. The named task will be scheduled to execute at its next regularly scheduled time.

The general command line format is:

schedule resume [-name task]

Parameter

Description

-name

Optional name of the task to resume scheduling. The named task execution will be scheduled to start at its next regularly scheduled time.

If the -name parameter is missing, all tasks in the Service Manager schedule that are suspended will resume scheduled execution on their next regularly scheduled time.

If the task that is resumed has a dependent task configured, the dependent task is only scheduled by the Service Managers immediately following the start of the configured primary task.


iWay Software