========
Schedule
========

.. sidebar:: Contents

  .. contents::
      :depth: 3
      :local:


This chapter covers the ``system schedule`` feature, which allows you to program the 
activation and deactivation of alarms in order to control the behaviour of multiple
OSDx subsystems at specific points in time.


Schedule elements
==================

The only parameter a schedule requires is an ``alarm``, which will be activated or
deactivated according to the configured times.

Two timers can be configured for a schedule, one to **activate** the alarm and another to
**deactivate** it.

The ``enable`` option configures a timer to **activate** the alarm whenever the timer expires.
This option is mandatory, and it is created by default.

The ``disable`` option configures a timer to **deactivate** the alarm whenever the timer expires.
This option is optional.

For each timer, the following fields can be configured:

  * ``year``: Year when the timer expires. Optional
  * ``month``: Month when the timer expires. Optional
  * ``day``: Day when the timer expires. Optional
  * ``weekday``: Weekday(s) when the timer expires. Optional
  * ``hour``: Hour when the timer expires. Optional
  * ``minute``: Minute when the timer expires. Optional
  * ``second``: Second when the timer expires. Mandatory, 0 by default.


Types of schedule
=================

Depending on the fields configured for a timer, it will expire only once or periodically.

One-shot timer
--------------

If all timer fields are configured (except ``weekday``, which is optional), an exact
date and time are established and the timer only expires once.

Periodic timer
--------------

If any timer field is not configured (except ``weekday``, which is optional), the timer
will expire according to any given value in that field (i.e, periodically).
For example, if only ``hour``, ``minute`` and ``second`` are configured, the timer will expire every day
at that time.


Configuration
=============

This is the syntax to configure schedules in OSDx:

.. code-block:: none

  set system schedule [ ... ]


Example
=======

The following simple schedule will activate and deactivate an alarm every minute:

.. code-block:: none

  set system alarm ALARM
  set system schedule SCHED1 alarm ALARM
  set system schedule SCHED1 disable second 30
  set system schedule SCHED1 enable second 0

The current status of the configured schedule can be monitored with the corresponding
operational command:

.. code-block:: none

  admin@osdx$ system schedule SCHED1 show

  ----------------------------------------------------------------------------------------------
  Schedule  State    Next                         Left      Last                         Passed 
  ----------------------------------------------------------------------------------------------
  SCHED1    enable   Tue 2025-04-08 14:01:00 UTC  14s left  Tue 2025-04-08 14:00:00 UTC  44s ago
  SCHED1    disable  Tue 2025-04-08 14:01:30 UTC  44s left  Tue 2025-04-08 14:00:30 UTC  14s ago


:doc:`Here </examples/system/schedule/schedule>`, you can find more examples.


.. osdx:cmdtree:: cfg

  system schedule

.. osdx:cmdtree:: op

  system schedule