Cron Service User's Guide

Version 3.1.0

Last updated: September 19, 2005


Table of Contents

Overview

Installation and Configuration

Request Syntax

  • REGISTER
  • UNREGISTER
  • LIST
  • VERSION
  • HELP
  • Service Logging

    Registration GUI

    Appendix A: Licenses and Acknowledgements


    Overview

    The Cron service allows you to register STAF commands that will be executed at a specified time interval(s).

    Note that Cron registration information is persistent data. This means that if you register with the Cron Service, if you shutdown STAF and restart it (even if you reboot the machine), the prior registration information will still be active. When STAF starts, it reads in the previous Cron registration information, and will execute the registered STAF commands at the specified time interval(s).

    Note that the Cron service uses its machine's Operating System date/time information to determine the current date/time in relation to the registered requests.  Users of the Cron service must ensure that the machine on which the Cron service is running has the correct Operating System date/time (and that it correctly updates the current date/time relative to Daylight Savings Time).


    Installation and Configuration

    Install Java 1.2 or later.

    Install STAF Version 3.1.0 or later by following the installation instructions in the STAF documentation.

    Install the Cron V3.1.0 service:

             Download the CronV310.zip/tar file from Get STAF Services into a local directory (e.g. C:/STAF/services or /usr/local/staf/services) and extract it.

    Configure the Cron service:


    Request Syntax

    The STAX service provides the following requests:

    REGISTER

    REGISTER registers a STAF command to be executed at a specified time interval.

    Syntax

    REGISTER   MACHINE <machine> | PYTHONMACHINE <machine>
               SERVICE <service> | PYTHONSERVICE <service>
               REQUEST <request> | PYTHONREQUEST <request>
               [PREPARE <script>]
               [MINUTE <minute>] [HOUR <hour>]
               [DAY <day>] [MONTH <month>]
               [WEEKDAY <weekday>]

    MACHINE specifies the name of the machine where the command will be executed.  This option will resolve STAF variables.  When the specified time interval occurs, the value of MACHINE will not be evaluated as a python string.

    PYTHONMACHINE specifies the name of the machine where the command will be executed.  This option will not resolve STAF variables.  When the specified time interval occurs, the value of PYTHONMACHINE will be evaluated as a python string.

    SERVICE specifies the name of the service to be executed.  This option will resolve STAF variables.  When the specified time interval occurs, the value of SERVICE will not be evaluated as a python string.

    PYTHONSERVICE specifies the name of the service to be executed.  This option will not resolve STAF variables.  When the specified time interval occurs, the value of PYTHONSERVICE will be evaluated as a python string.

    REQUEST specifies the request to be executed.  This option will resolve STAF variables.  When the specified time interval occurs, the value of REQUEST will not be evaluated as a python string. This option will handle private data.

    PYTHONREQUEST specifies the request to be executed.  This option will not resolve STAF variables.  When the specified time interval occurs, the value of PYTHONREQUEST will be evaluated as a python string. This option will handle private data.

    PREPARE specifies Python code which will be executed when the specified time interval occurs.  This code will be executed prior to the PYTHONMACHINE, PYTHONSERVICE, and PYTHONREQUEST options being evaluated as python strings. This option will not resolve STAF variables.  If the Python code sets the variable
    STAFCronSubmit to any string other than 'true', then the request will not be submitted.

    MINUTE specifies the exact minute(s) that the request executes.  The valid values are 0 - 59.  You can specify either * (an asterisk) or ANY, meaning all valid values, or a list of elements separated by commas.  An element is either a number or an inclusive range, indicated by two numbers separated by a minus sign (such as 1-15).

    HOUR specifies the exact hour(s) that the request executes.  The valid values are 0 - 23.  You can specify either * (an asterisk) or ANY, meaning all valid values, or a list of elements separated by commas.  An element is either a number or an inclusive range, indicated by two numbers separated by a minus sign (such as 8-17).

    DAY specifies the exact day(s) that the request executes.  The valid values are 1 - 31.  You can specify either * (an asterisk) or ANY, meaning all valid values, or a list of elements separated by commas.  An element is either a number or an inclusive range, indicated by two numbers separated by a minus sign (such as 1-2).

    MONTH specifies the exact month(s) that the request executes.  The valid values are 1 - 12.  You can specify either * (an asterisk) or ANY, meaning all valid values, or a list of elements separated by commas.  An element is either a number or an inclusive range, indicated by two numbers separated by a minus sign (such as 5-6).

    WEEKDAY specifies the exact weekday(s) that the request executes.  The valid values are 0 - 6  (Sunday = 0, ....).  You can also specify the textual weekday ("Sunday", etc.).  You can specify either * (an asterisk) or ANY, meaning all valid values, or a list of elements separated by commas.  An element is either a number or an inclusive range, indicated by two numbers separated by a minus sign (such as 1-15).

    Note: At least one of the time interval options (MINUTE, HOUR, DAY, MONTH, WEEKDAY) must be specified in a REGISTER request.

    Security

    This request requires at least trust level 5.

    Results

    Upon successful return, the result buffer contains the Cron ID.

    Examples

    UNREGISTER

    UNREGISTER unregisters a STAF command with the Cron Service.

    Syntax

    UNREGISTER ID <registrationID>

    ID specifies the Cron ID which is to be unregistered.

    Security

    This request requires at least trust level 4.

    Results

    Upon successful return, the result buffer will be empty.

    LIST

    LIST lists information about the commands registered with the Cron service.

    Syntax

    LIST [MACHINE <machine>] [LONG]

    MACHINE specifies the machine for which Cron requests should be listed.

    LONG specifies to list more detailed information about each Cron request.

    Security

    This request requires at least trust level 2.

    Results

    Upon successful return:

    Examples

    VERSION

    VERSION displays the version level of the Cron service or the version level of Jython packaged with the Cron service.

    Syntax

    VERSION [JYTHON]

    VERSION specifies to display the version level of the Cron service or the version level of Jython packaged with the Cron service.

    JYTHON specifies to display the version level of Jython packaged with the Cron service.

    Security

    This request requires at least trust level 1.

    Results

    The result buffer contains the version level of the Cron service if option JYTHON is not specified. If option JYTHON is specified, the result buffer contains the version level of Jython packaged with the Cron service.

    Examples

    HELP

    HELP displays the request options and how to use them.

    Syntax

    HELP

    Security

    This request requires at least trust level 1.

    Results

    The result buffer contains the Help messages for the request options for the Cron service.


    Service Logging

    The Cron service maintains a machine log where it writes an entry when the following occurs:

    The logname for the Cron service is the name under which the service is registered.

    Here is an example of what a Cron service log on the local machine with machine nickname client1 could look like (shown via a request from the command line in the table format:

    C:\>STAF local LOG QUERY MACHINE client1 LOGNAME Cron
    Response
    --------
    Date-Time Level Message
    --------- ----- -------------------------------------------------------------
    20041021- Info  Register ID=1 originMachine=tcp://client1.austin.ibm.com@6500
    00:05:45        machine=client1 pythonMachine=false service=stax pythonServic
                    e=false request=version pythonRequest=false prepare= minute=[
                    ANY] hour=[] day=[31] month=[] weekday=[]
    20041021- Info  Register ID=2 originMachine=tcp://client1.austin.ibm.com@6500
    00:06:00        machine=client1 pythonMachine=false service=event pythonServi
                    ce=false request=blah pythonRequest=false prepare= minute=[AN
                    Y] hour=[] day=[31] month=[1] weekday=[]
    20041021- Info  Submitted request #120 ID=2 triggers=minute[6],day[31],month[
    00:06:08        1] machine=client1 service=event request=blah
    20041021- Info  Submitted request #124 ID=1 triggers=minute[6],day[31] machin
    00:06:08        e=client1 service=stax request=version
    20041021- Error Request #120: RC=7, Result=blah, Request submitted: machine=c
    00:06:08        lient1 service=event request=blah
    20041021- Info  Request #124: RC=0, Result=1.5.0, Request submitted: machine=
    00:06:08        client1 service=stax request=version
    20041021- Info  Submitted request #142 ID=2 triggers=minute[7],day[31],month[
    00:07:08        1] machine=client1 service=event request=blah
    20041021- Info  Submitted request #146 ID=1 triggers=minute[7],day[31] machin
    00:07:08        e=client1 service=stax request=version
    20041021- Error Request #142: RC=7, Result=blah, Request submitted: machine=c
    00:07:08        lient1 service=event request=blah
    20041021- Info  Request #146: RC=0, Result=1.5.0, Request submitted: machine=
    00:07:08        client1 service=stax request=version
    20041021- Info  Unregister ID=1
    00:07:44
    20041021- Info  Unregister ID=2
    00:07:45
    


    Registration GUI

    The Cron Service provides a GUI to simplify the Cron Registration.  To use this GUI, after installing and configuring the Cron Service, from a command prompt enter the following command (note that to run this command, the STAFCron.jar file must be in your CLASSPATH):

        java com.ibm.staf.service.cron.CronRegister

    A GUI will be displayed which allows you to enter the Cron Registration options.

    Cron Registration

    The "Cron Service Machine" default is the local machine. The "Cron Service Name" default is "Cron".

    Fill in the required values for "Target Machine", "Target Service", and "Target Request". Optionally, you may specify Python code in the "Prepare Script" field.

    Fill in one or more values for "Minute", "Hour", "Day", "Month", and "Weekday".

    This example shows the options you would specify to execute a STAX job at 6:00am every day.


    Appendix A: Licenses and Acknowledgements

    Jython

    Jython is an implementation of the high-level, dynamic, object-oriented language Python written in 100% Pure Java, and seamlessly integrated with the Java platform. It thus allows you to run Python on any Java platform.

    Acknowledgement

    This product includes software developed by the Jython Developers (http://www.jython.org/).

    Licence

    Jython Software License
    =======================
    
    Copyright (c) 2000, Jython Developers
    All rights reserved.
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
    
     - Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    
     - Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in
       the documentation and/or other materials provided with the distribution.
    
     - Neither the name of the Jython Developers nor the names of
       its contributors may be used to endorse or promote products
       derived from this software without specific prior written permission.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.