Cron Service User's Guide

Version 3.4.0

Last updated: May 26, 2011


Table of Contents

Overview

Installation and Configuration

Request Syntax

  • REGISTER
  • UNREGISTER
  • LIST
  • TRIGGER
  • ENABLE
  • DISABLE
  • VERSION
  • HELP
  • Persistent Registration Data

    Service Logging

    Using Python

    Cron Python Variables

    Cron User Interface (CronUI)

  • Using the CronUI
  • Submit a New Registration
  • Registration Example using Python and Prepare Script
  • Edit a Registration
  • Copy a Registration
  • Trigger a Registration
  • View the Service Log
  • Delete the Service Log
  • Cron Error Codes

    Appendix A: References

    Appendix B: Jython and CPython Differences

    Appendix C: Licenses and Acknowledgements


    Overview

    The Cron service allows you to register STAF commands that will be executed at a specified time interval(s). The Cron service also provides a User Interface to simplify interaction with the Cron service

    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

    1. Install Java 1.5 (aka 5.0) or later.

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

    3. Install the Cron service by downloading the CronV340.zip/tar file from Get STAF Services into a local directory (e.g. C:/STAF/services or /usr/local/staf/services) and extracting it.

    4. Configure the Cron service by adding the following statement to your STAF configuration file:
      SERVICE <Name> LIBRARY JSTAF EXECUTE <Cron Jar File Name>
                     [OPTION <Name[=Value]>]... 
                     [PARMS OLDVARRESOLUTION]
      

      where:

      Examples:

      SERVICE Cron LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/cron/STAFCron.jar

      SERVICE Cron LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/cron/STAFCron.jar \
                           OPTION JVMName=Cron OPTION JVM=C:\j2sdk1.5.0\bin\java

      SERVICE Cron LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/cron/STAFCron.jar PARMS OLDVARRESOLUTION


    Request Syntax

    The CRON 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>
               [DESCRIPTION <description>]
               [PREPARE <script>]
               [MINUTE <minute>] [HOUR <hour>]
               [DAY <day>] [MONTH <month>]
               [WEEKDAY <weekday>]
               [ONCE]
               [ENABLED | DISABLED]

    MACHINE specifies the name of the machine where the command will be executed. This option will not resolve STAF variables (unless the OLDVARRESOLUTION parameter is specified when registering the Cron service). 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 (unless the OLDVARRESOLUTION parameter is specified when registering the Cron service). 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 not resolve STAF variables (unless the OLDVARRESOLUTION parameter is specified when registering the Cron service). 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 not resolve STAF variables (unless the OLDVARRESOLUTION parameter is specified when registering the Cron service). 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.

    DESCRIPTION specifies a description of the registration. It is for informational purposes only. This option will resolve STAF variables.

    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).

    ONCE indicates that the STAF command should only be executed one time. After the specified time interval has occurred and the STAF command has been submitted, the ID for this request will be unregistered.

    ENABLED specifies that the command will be enabled when it is registered. This means that the command will be submitted when the specified time triggers occur. This is the default if the ENABLED or DISABLED options are not specified.

    DISABLED specifies that the command will be disabled when it is registered. This means that the command will not be submitted when the specified time triggers occur.

    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 | SHORT]

    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

    TRIGGER

    TRIGGER submits a registered STAF command. It is useful for testing the STAF command at any given time (without matching the registered time triggers).

    Syntax

    TRIGGER ID <registrationID> [SCRIPT ]...

    ID specifies the Cron ID which is to be triggered.

    SCRIPT defines Python code to be executed. You may specify any number of SCRIPT options. They will be executed in the order specified, and will be executed prior to the registration's PREPARE, PYTHONMACHINE, PYTHONSERVICE, AND PYTHONREQUEST values are evaluated.

    Security

    This request requires trust level 5.

    Results

    If the STAF command was successfully submitted, the return code will be zero. This does not mean that the STAF command was successful, however; it only indicates that the STAF command was successfully submitted. You will need to check the Cron service log to determine the RC and result that the STAF command returned.

    Upon successful return:

    Examples

    ENABLE

    ENABLE enables a STAF command. This means that the command will be submitted when the specified time triggers occur.

    Syntax

    ENABLE ID <registrationID>

    ID specifies the Cron ID which is to be enabled.

    Security

    This request requires at least trust level 4.

    Results

    Upon successful return, the result buffer will be empty. Note that an error will not be returned if the Cron ID is already enabled.

    DISABLE

    DISABLE disables a STAF command. This means that the command will not be submitted when the specified time triggers occur.

    Syntax

    DISABLE ID <registrationID>

    ID specifies the Cron ID which is to be disabled.

    Security

    This request requires at least trust level 4.

    Results

    Upon successful return, the result buffer will be empty. Note that an error will not be returned if the Cron ID is already disabled.

    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.


    Persistent Registration Data

    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).

    In Cron V3.2.0, the format of this data was modified. Persistent registration data for versions prior to Cron V3.2.0 will automatically be migrated to the new format. Note that the new format can not be used with versions of Cron prior to V3.2.0.


    Service Logging

    The Cron service maintains a machine log where it writes information about the STAF commands that it has submitted. It is important to check the log to determine the results of STAF commands submitted by the Cron service. The Cron service will log an entry when the following occurs:

    The [ID=<xx>] and [ID=<xx>] [<machine>:<requestNumber>] tags in the log entries can be useful when querying the log. They can be used with the CONTAINS option of the log service's QUERY request.

    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 could look like (shown via a request from the command line in the table format):

    C:\>STAF local log QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME cron
    Response
    --------
    Date-Time         Level Message
    ----------------- ----- -------------------------------------------------------
    20060808-16:08:29 Info  [ID=1] [local://local, STAF/Client] Registered a STAF c
                            ommand. Register request: REGISTER DESCRIPTION :20:Get
                            the STAF version MACHINE local SERVICE misc REQUEST ver
                            sion MINUTE 9 ONCE
    20060808-16:08:29 Info  [ID=2] [local://local, STAF/Client] Registered a STAF c
                            ommand. Register request: REGISTER DESCRIPTION :17:Run
                            java -version MACHINE local SERVICE process REQUEST :61
                            :start command java parms -version returnstdout stderrt
                            ostdout MINUTE 10
    20060808-16:08:29 Info  [ID=3] [local://local, STAF/Client] Registered a STAF c
                            ommand. Register request: REGISTER DESCRIPTION :20:Pyth
                            on runtime error MACHINE local SERVICE misc REQUEST ver
                            sion PREPARE a=b MINUTE 11
    20060808-16:09:01 Info  [ID=1] [dave2268.austin.ibm.com:2664] Submitted a STAF
                            command. Triggers: minute[9] Submitted STAF command: ST
                            AF local misc version
    20060808-16:09:01 Info  [ID=1] [local://local, STAF/SERVICE/cron] Unregistered
                            a STAF command.
    20060808-16:09:01 Pass  [ID=1] [dave2268.austin.ibm.com:2664] Completed a STAF
                            command. RC=0, Result=3.1.4.1
    20060808-16:10:01 Info  [ID=2] [dave2268.austin.ibm.com:2681] Submitted a STAF
                            command. Triggers: minute[10] Submitted STAF command: S
                            TAF local process start command java parms -version ret
                            urnstdout stderrtostdout
    20060808-16:10:01 Pass  [ID=2] [dave2268.austin.ibm.com:2681] Completed a STAF
                            command. RC=0, Result=134
    20060808-16:10:01 Pass  [ID=2] [dave2268.austin.ibm.com:2681] Process completed
                            . Process info: {key=, handle=134, rc=0, endTimestamp=2
                            0060808-16:10:01, fileList=[{rc=0, data=java version "1
                            .5.0"  Java(TM) 2 Runtime Environment, Standard Edition
                             (build 1.5.0-b64)  Java HotSpot(TM) Client VM (build 1
                            .5.0-b64, mixed mode)  }]}
    20060808-16:11:01 Error [ID=3] Python error in the PREPARE value.  PREPARE: a=b
                              PyException: Traceback (innermost last):    File "<st
                            ring>", line 1, in ?  NameError: b   Processing registr
                            ation:   ID: 3   machine: local   service: misc   reque
                            st: version   prepare: a=b
    20060808-16:11:25 Info  [ID=2] [local://local, STAF/Client] Unregistered a STAF
                             command.
    20060808-16:11:27 Info  [ID=3] [local://local, STAF/Client] Unregistered a STAF
                             command.
    

    Here is an example of only displaying the log records for a particular registration ID:

    C:\>STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME cron CONTAINS [ID=2]
    Response
    --------
    Date-Time         Level Message
    ----------------- ----- -------------------------------------------------------
    20060808-16:08:29 Info  [ID=2] [local://local, STAF/Client] Registered a STAF c
                            ommand. Register request: REGISTER DESCRIPTION :17:Run
                            java -version MACHINE local SERVICE process REQUEST :61
                            :start command java parms -version returnstdout stderrt
                            ostdout MINUTE 10
    20060808-16:10:01 Info  [ID=2] [dave2268.austin.ibm.com:2681] Submitted a STAF
                            command. Triggers: minute[10] Submitted STAF command: S
                            TAF local process start command java parms -version ret
                            urnstdout stderrtostdout
    20060808-16:10:01 Info  [ID=2] [dave2268.austin.ibm.com:2681] Completed a STAF
                            command. RC=0, Result=134
    20060808-16:10:01 Info  [ID=2] [dave2268.austin.ibm.com:2681] Process completed
                            . Process info: {key=, handle=134, rc=0, endTimestamp=2
                            0060808-16:10:01, fileList=[{rc=0, data=java version "1
                            .5.0"  Java(TM) 2 Runtime Environment, Standard Edition
                             (build 1.5.0-b64)  Java HotSpot(TM) Client VM (build 1
                            .5.0-b64, mixed mode)  }]}
    20060808-16:11:25 Info  [ID=2] [local://local, STAF/Client] Unregistered a STAF
                             command.
    

    Here is an example of only displaying the log records for a particular registration ID, machine, and STAF request number:

    C:\>STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME cron CONTAINS "[ID=1] [dave2268.austin.ibm.com:2664]"
    Response
    --------
    Date-Time         Level Message
    ----------------- ----- -------------------------------------------------------
    20060808-16:09:01 Info  [ID=1] [dave2268.austin.ibm.com:2664] Submitted a STAF
                            command. Triggers: minute[9] Submitted STAF command: ST
                            AF local misc version
    20060808-16:09:01 Info  [ID=1] [dave2268.austin.ibm.com:2664] Completed a STAF
                            command. RC=0, Result=3.1.4.1
    

    Here is an example of only displaying the error log records, and using the -verbose option so that the error output is more readable:

    C:\>STAF -verbose local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME cron LEVELMASK error
    Response
    --------
    [
      {
        Date-Time: 20060808-16:11:01
        Level    : Error
        Message  : [ID=3] Python error in the PREPARE value.
    
    PREPARE:
    a=b
    
    PyException:
    Traceback (innermost last):
      File "<string>", line 1, in ?
    NameError: b
    
    Processing registration:
      ID: 3
      machine: local
      service: misc
      request: version
      prepare: a=b
      }
    ]
    


    Using Python

    The Cron service lets uses the Python scripting language for variable and expression evaluation for the following REGISTER and TRIGGER request options:

    This allows the Cron service to take advantage of the powerful and easy-to-use features of Python. The Cron service uses Jython 2.5.2 to execute Python code. Jython is a version of Python written entirely in Java that runs under any compliant Java Virtual Machine (JVM).

    Python variable names must follow the Python variable naming conventions. In Python, variable names come into existence when you assign values to them, but there are a few rules to follow when picking names for variables.

    Python string constants can be enclosed in single or double quotes, which allows embedded quotes of the opposite flavor.

    For example, the following two lines of Python code do exactly the same thing. They assign a string constant (literal) "CoolTest" to the value of a variable named testName.

    testName = "CoolTest1"
    testName = 'CoolTest1'
    
    However, the following line is not the same. It assigns the value of a variable named CoolTest1 to the value of a variable named testName. If this was not what you intended and a variable named CoolTest1 does not exist, a PythonException will be raised and logged in the service log.
    testName = CoolTest1
    

    Say, you wanted to use a Python variable named machName in a STAF service request string. Your Python code could look like:

    request = 'RELEASE POOL MachinePool ENTRY %s' % (machName)
    
    where the %s indicates a String format (and can also be used for decimal format, etc.), and where the value of the machName variable would replace the %s marker.

    So, if the value of variable machName is 'client1.company.com', after being evaluated by Python, the request variable's value would be:

    'RELEASE POOL MachinePool ENTRY client1.company.com'
    

    Here are a couple of examples of how you might use Python code in the PREPARE and PYTHONREQUEST options when submitting a REGISTER request to the Cron service:

    Actually, it's usually easier to register more complex requests like these that use Python code via the Cron User Interface (CronUI) instead of the command line because then you don't have to bother so much with escaping quotes and you can have multiple lines of Python code. See the Registration Example using Python and Prepare Script section for an example of how to register a STAF command via the CronUI.

    Refer to the "References" section for where to get more information about Jython and Python.

    If you are already a CPython programmer, or are hoping to use CPython code under Jython, refer to the "Jython and CPython Differences" section for information about differences in the two implementations of Python.
     


    Cron Python Variables

    The following variables are set in Python by the Cron service when a registration is triggered. These Python variables can be referenced by Python code in the PREPARE, PYTHONREQUEST, PYTHONMACHINE, and PYTHONSERVICE options for the REGISTER request and in the SCRIPT option for the TRIGGER request.

     


    Cron User Interface (CronUI)

    The Cron service provides a User Interface (CronUI) to simplify interaction with the Cron service. The CronUI is especially useful when registering complex STAF commands with Python code because it helps avoid some issues that you have when registering via the command line by reducing the need for escaping quotes and allows you to easily enter multiple lines of Python code via a text box for the PREPARE option, The CronUI also allows you to modify existing registrations (without having to unregister and the re-register the updated STAF command), and view the Cron service's log.

    Note that when viewing the Cron service's log, the Cron User Inteface utilizes the STAFLogViewer class to display the logs. For more information on how to use the STAFLogViewer, refer to section "3.11 Class STAFLogViewer" of the STAF Java User's Guide ( http://staf.sourceforge.net/current/STAFJava.htm).

    Using the CronUI

    To use the Cron User Interface, after installing and configuring the Cron Service, from a command prompt enter one of the following commands:

    A User Interface will be displayed which allows you to interact with the Cron service.

    CronUI

    The main CronUI window displays a table of all of the currently registered STAF commands. The screen capture above shows what the table would look like if there are no registrations. The window is comprised of the following components (from to to bottom):

    1. Menu bar
    2. Service configuration options
    3. Registration table
    4. Status bar

    Menu bar

    The File menu bar contains the following menu items:

    The View menu bar contains the following menu items:

    The Selected menu bar will only be enabled if there is a row currently selected in the registration table, and contains the following menu items:

    Note that all of the "Selected" menu items are also available in a pop-up menu when you right click on a row in the registration table, and they perform the exact same functions as the "Selected" menu bar items.

    The Help menu bar contains the following menu items:

    Service configuration options

    The "Service Machine" text field allows you to specify the hostname of the machine where the Cron service is running. The default is "local".

    The "Service Name" text field allows you to specify the service name for which the Cron service was configured. The default is "Cron".

    After changing either of these values, you can press the "Enter" key to refresh the table, or click on "View" in the menu bar, and then select "Refresh".

    Registration table

    The registration table displays the current registrations for the Cron service you specified in the service configuration fields (for Service Machine and Service Name). It is refreshed every time you click on "View" in the menu bar and selecte "Refresh", as well as when you change the Service Machine or Service Name fields and press "Enter".

    It is also refreshed whenever you add a new registration, unregister a registration, edit a registration, or copy an existing registration to a new registration.

    The registration table has the following columns:

    Status bar

    The status bar shows informational messages. Here are the possible messages:

    Submit a New Registration

    To submit a new registration, click on "File" in the menu bar and then select "New Registration...". You will see the following window:

    CronUI

    This window allows you to specify the data for the registration:

    Note that at least one of the time interval options (Minute, Hour, Day, Month, Weekday) must be specified.

    To get help on any of these options while using CronUI, mover the cursor over the text field or checkbox and a tool tip will be displayed.

    Fill in the appropriate information for the STAF command you wish to have executed. For example, to have a STAX job executed at 1:00AM every day:

    CronUI

    Click on the "Register" button and you will see that the STAF command has been assigned a unique registration ID, and that it is listed in the registration table.

    CronUI

    Registration Example using Python and Prepare Script

    To register a more complex STAF command, you may find it easier to use the CronUI instead of submitting a REGISTER request to the Cron service via the command line. This is especially true for STAF commands that use Python. Also, if you select to specify the request using Python and use the "Prepare Script" field, you usually don't have to escape as many quotes.

    This section shows an example of registering a more complex STAF command using the CronUI. It will use the same example that was discussed in the REGISTER section that registered a STAF command via the command line to execute STAX job /tests/TestA.xml via the STAX service on machine server1 every day at midnight and passed the following argument map to the STAX job: {'machine': 'client1', 'testDir': '/tests'}

    Remember that a STAF variable reference is denoted by surrounding the variable in curly braces, e.g. {MyVar}. So, since the request contains a "{" which is not being used to denote a STAF variable reference, this example selects "Python" for the target request so that STAF variable resolution will not be performed. If "Python" was not selected for the target request, then the "{" would need to be escaped with a caret, "^", so that no STAF variable resolution would be performed. This example also uses the "Prepare Script" field to construct the STAX EXECUTE request using Python.

    The following is an example of how you could register the following STAX EXECUTE command to run every day at midnight:

    STAF server1 STAX EXECUTE FILE "/tests/TestA.xml" ARGS "{'machine': 'client1', 'testDir': '/tests'}"

    Registration Example Using Python

    Edit a Registration

    To edit a registration, double click on its row in the registration table, click on "Selected" in the menu bar and select "Edit", or right-click on its row in the registration table, and select "Edit" in the popup menu.

    For example, if we wanted to change the registration ID 1 to only execute at 1:00AM Monday-Friday:

    CronUI

    Click on the "Register" button to unregister the existing ID, and register the updated registration data:

    CronUI

    Click on yes, and you will see that the updated registration data has been saved. In this scenario, since we only had one existing registration, the ID for the updated registration is still 1. If there are already existing registration IDs, then the assigned registration id would be the next sequential ID.

    Copy a Registration

    To copy the information from an existing registration to a new registration, click on "Selected" in the menu bar and select "Copy to new registration", or right-click on its row in the registration table, and select "Copy to new registration" in the popup menu.

    Update the information for the new registration:

    CronUI

    Click on the "Register" button to register.

    CronUI

    Unregister a Registration

    To unregister a registration, click on "Selected" in the menu bar and select "Unregister", or right-click on its row in the registration table, and select "Unregister" in the popup menu. You will get a confirmation popup:

    CronUI

    Click on "Yes" and the ID will be unregistered.

    Next, let's register to have the command "java -version" executed at the beginning of every month. In the menu bar click on "File" and then "New Registration..." and fill in the data:

    CronUI

    Click on the "Register" button and we will see that it has been assigned a unique registration ID:

    CronUI

    Trigger a Registration

    Suppose we want to test the STAF command that we just registered, and we don't want to wait until the next time the month changes. To do this, click on "Selected" in the menu bar and select "Trigger", or right-click on its row in the registration table, and select "Trigger" in the popup menu.

    The STAF command will be submitted and a STAFLogViewer window will open to display the service log entries for that STAF command:

    CronUI

    In this case, since the process returned the version immediately, the log query shows that the process has completed, and includes the information it returned.

    View the Service Log

    To view the service log's entries for a particular registration ID, click on "View" in the menu bar and then select "Service Log for ID...". In the popup dialog, enter ID "3" and click on OK. A STAFLogViewer window will open with all of the log entries for ID 3:

    CronUI

    To view the last 100 entries in the service log, click on "View" in the menu bar and then select "Service Log last 100 records". A STAFLogViewer window will open with the last 100 entries:

    CronUI

    To view the log entries for a particular submitted STAF command, click on "View" in the menu bar and then select "Service log for submitted STAF command...". A new dialog will be displayed showing a list of all of the submitted STAF commands:

    CronUI

    Select the submitted STAF command, and click on "OK". A STAFLogViewer window will open with all of the log entries for that submitted STAF command:

    CronUI

    To view the entire service log, click on "View" in the menu bar and then select "Entire Service Log". A STAFLogViewer window will open with all of the log entries:

    CronUI

    Delete the Service Log

    To delete the service log, click on "View" in the menu bar and then select "Delete Service Log". You will receive a confirmation popup:

    CronUI


    Cron Error Codes

    In addition to the common STAF return codes, the following Cron return codes are defined:

    Table 1. Cron Service Return Codes

    Error Code Meaning Comment
    4001 Python error A Python error during a TRIGGER command occurred while evaluating the request to be submitted. The result buffer will include details about the Python error.
    4002 Request not submitted The request for a TRIGGER command was not submitted because the value of STAFCronSubmit was not set to true. The result buffer will include the value of STAFCronSubmit.


    Appendix A: References


    Appendix B: Jython and CPython Differences

    Although in most cases Jython behavior is identical to the C-language implementation of Python (CPython), there are still cases where the two implementations differ. If you are already a CPython programmer, or are hoping to use CPython code under Jython, you need to be aware of these differences. Also, there is a time lag between a new CPython release and the corresponding Jython release. The Cron service uses Jython 2.5.2 which implements the same set of language features as CPython 2.5. Jython 2.5.2 cannot execute Python code that uses functions that were provided in later versions of Python, such as Python 2.6.

    Most Python modules that are written in Python work fine in Jython. A few types of modules will not run under Jython such as:

    See the "Jython Essentials" book, written by Samuele Pedroni and Noel Rappin, for more information about the differences between Jython and CPython.


    Appendix C: 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

    PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
    --------------------------------------------
    
    1. This LICENSE AGREEMENT is between the Python Software Foundation
    ("PSF"), and the Individual or Organization ("Licensee") accessing and
    otherwise using this software ("Jython") in source or binary form and
    its associated documentation.
    
    2. Subject to the terms and conditions of this License Agreement, PSF
    hereby grants Licensee a nonexclusive, royalty-free, world-wide
    license to reproduce, analyze, test, perform and/or display publicly,
    prepare derivative works, distribute, and otherwise use Jython alone
    or in any derivative version, provided, however, that PSF's License
    Agreement and PSF's notice of copyright, i.e., "Copyright (c) 2007
    Python Software Foundation; All Rights Reserved" are retained in
    Jython alone or in any derivative version prepared by Licensee.
    
    3. In the event Licensee prepares a derivative work that is based on
    or incorporates Jython or any part thereof, and wants to make
    the derivative work available to others as provided herein, then
    Licensee hereby agrees to include in any such work a brief summary of
    the changes made to Jython.
    
    4. PSF is making Jython available to Licensee on an "AS IS"
    basis.  PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
    IMPLIED.  BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
    DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
    FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF JYTHON WILL NOT
    INFRINGE ANY THIRD PARTY RIGHTS.
    
    5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF JYTHON
    FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
    A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING JYTHON,
    OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
    
    6. This License Agreement will automatically terminate upon a material
    breach of its terms and conditions.
    
    7. Nothing in this License Agreement shall be deemed to create any
    relationship of agency, partnership, or joint venture between PSF and
    Licensee.  This License Agreement does not grant permission to use PSF
    trademarks or trade name in a trademark sense to endorse or promote
    products or services of Licensee, or any third party.
    
    8. By copying, installing or otherwise using Jython, Licensee
    agrees to be bound by the terms and conditions of this License
    Agreement.
     
    Jython 2.0, 2.1 License
    ================================
    
    Copyright (c) 2000-2009 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.