Introduction

This part of the Rose user guide walks you through manipulating date/time information within a suite using utilities such as rose date and environment variables like $ROSE_DATAC.

This allows you to specify offsets in time from the current cycle time of a task - for example, retrieving data from a previous cycle, 12 hours ago. You can also translate times into different formats for use in your tasks.

Example

Our example suite will control a minor airport

Create a new suite (or just a new directory somewhere - e.g. in your homespace) containing a blank rose-suite.conf and a suite.rc file that looks like this.

Runtime

This is a skeleton suite that handles the departure and arrival of a single aircraft, twice a day.

You can see we already have runtime information for two tasks, wait_return and assign_gate. There are a few empty tasks as well.

Runtime

wait_return is a fancy 'sleep' task that uses cylc task message to communicate back to cylc, which can be seen in a cylc gui view for easy human monitoring.

assign_gate gets a random gate number and writes it to a file (flight_gates). It uses the Rose environment variable ROSE_DATAC provided by rose task-env in the env-script runtime section. This points to a data directory for this particular cycle time, where the file will be written.

Startup

We need a run-once (R1) task (startup). This sets our initial gate number - add this to your [[startup]] runtime section of the suite.rc file:

    [[startup]]
        env-script = eval $(rose task-env --cycle-offset=PT12H)
        script = """
            GATE="A"$((RANDOM%3))
            echo "GATE=$GATE" > $ROSE_DATACPT12H/flight_gate
            cylc task message "Starting gate: $GATE"
            sleep 5
         """

Startup Explanation

This flight_gate file will be sourceable by tasks that need the GATE number.

Boarding

We'd like to tell passengers which gate to board at in the boarding task. The gate was output to a file by startup, for the first cycle, and by assign_gate thereafter.

This means that this task has to read the flight_gates file from the last cycle's data directory.

rose task-env --cycle-offset

Rose will give us the environment variable for the last cycle's data directory, if we ask for it.

We need to use the same env-script option, but with a --cycle-offset=PT12H option - add this to your [[boarding]] runtime section:

    [[boarding]]
        env-script = eval $(rose task-env --cycle-offset=PT12H)

ROSE_DATAC???

This exports an extra environment variable called $ROSE_DATACPT12H.

We can now refer to this in boarding's script - add:

        script = """
            . $ROSE_DATACPT12H/flight_gate
            cylc task message "Now boarding at Gate $GATE"
            sleep 5
        """

This will report the correct gate.

rose date

We can also process the cylc environment variable $CYLC_TASK_CYCLE_POINT in our tasks, using the date manipulation utility rose date.

This takes date strings and transmutes them into different formats and/or with offsets in time.

Using rose date

Replace the boarding script triple-quoted block with:

        script = """
            . $ROSE_DATACPT12H/flight_gate
            FLIGHT_TIME=$(rose date --print-format="%H:%M" $CYLC_TASK_CYCLE_POINT)
            cylc task message "Flight $FLIGHT_TIME now boarding at Gate $GATE"
            sleep 5
            cylc task message "Last call for Flight $FLIGHT_TIME at Gate $GATE"
            sleep 5
        """

Using rose date: explanation

We've used the --print-format option to rose date to change the format of the date and time into something simple.

Running the suite

Try running the suite. It should run correctly over the cycle times, and if you have the correct cylc gui view open, you'll see the cylc task messages appear.

rose date --offset

rose date can be used to add or remove increments of time, as well as change the output format.

If you add the following lines to your [[departure]] runtime section, you can see how you can use different offset units (days, hours) and quite complicated formats:

Example

    [[departure]]
        script = """
            NOW=$(rose date --print-format="%H:%M %p on %A %d %B" $CYLC_TASK_CYCLE_POINT)
            ETA=$(rose date --offset=-P1D --offset=PT2H --print-format="%H:%M %p on %A %d %B" $CYLC_TASK_CYCLE_POINT)
            echo "Welcome to the aircraft. The current time and date is $NOW."
            echo "Since we're crossing the International Date Line, our ETA is $ETA."
        """

Try running the suite again and looking at the departure output using rose suite-log.

Further Reading

For more information, see:

• ROSE_DATAC
• ROSE_DATAC???
• rose date
• the cylc User Guide.