NAME

       Schedule::At - OS independent interface to the Unix 'at' command

SYNOPSIS

        require Schedule::At;

        Schedule::At::add(TIME => $string, COMMAND => $string [, TAG =>$string]);
        Schedule::At::add(TIME => $string, COMMAND => \@array [, TAG =>$string]);
        Schedule::At::add(TIME => $string, FILE => $string)

        %jobs = Schedule::At::getJobs();
        %jobs = Schedule::At::getJobs(JOBID => $string);
        %jobs = Schedule::At::getJobs(TAG => $string);

        Schedule::At::readJobs(JOBID => $string);
        Schedule::At::readJobs(TAG => $string);

        Schedule::At::remove(JOBID => $string);
        Schedule::At::remove(TAG => $string);

DESCRIPTION

       This modules provides an OS independent interface to 'at', the Unix command that allows
       you to execute commands at a specified time.

       Schedule::At::add
           Adds a new job to the at queue.

           You have to specify a TIME and a command to execute. The TIME has a common format:
           YYYYMMDDHHmm where YYYY is the year (4 digits), MM the month (01-12), DD is the day
           (01-31), HH the hour (00-23) and mm the minutes.

           The command is passed with the COMMAND or the FILE parameter.  COMMAND can be used to
           pass the command as an string, or an array of commands, and FILE to read the commands
           from a file.

           The optional parameter TAG serves as an application specific way to identify a job or
           a set of jobs.

           Returns 0 on success or a value != 0 if an error occurred.

       Schedule::At::readJobs
           Read the job content identified by the JOBID or TAG parameters.

           Returns a hash of JOBID => $string where $string is the the job content. As the
           operating systems usually add a few environment settings, the content is longer than
           the command provided when adding the job.

       Schedule::At::remove
           Remove an at job.

           You identify the job to be deleted using the JOBID parameter (an opaque string
           returned by the getJobs subroutine). You can also specify a job or a set of jobs to
           delete with the TAG parameter, removing all the jobs that have the same tag (as
           specified with the add subroutine).

           Used with JOBID, returns 0 on success or a value != 0 if an error occurred.  Used with
           TAG, returns a hash reference where the keys are the JOBID of the jobs found and the
           values indicate the success of the remove operation.

       Schedule::At::getJobs
           Called with no params returns a hash with all the current jobs or dies if an error has
           occurred.  It's possible to specify the TAG or JOBID parameters so only matching jobs
           are returned.  For each job the key is a JOBID (an OS dependent string that shouldn't
           be interpreted), and the value is a hash reference.

           This hash reference points to a hash with the keys:

           TIME
               An OS dependent string specifying the time to execute the command

           TAG The tag specified in the Schedule::At::add subroutine

Configuration Variables

       •   $Schedule::At::SHELL

           This variable can be used to specify shell for execution of the scheduled command.
           Can be useful for example when scheduling from CGI script and the account of the user
           under which httpd runs is locked by using '/bin/false' or similar as a shell.

EXAMPLES

        use Schedule::At;

        # 1
        Schedule::At::add (TIME => '199801181530', COMMAND => 'ls',
               TAG => 'ScheduleAt');
        # 2
        @cmdlist = ("ls", "echo hello world");

        Schedule::At::add (TIME => '199801181630', COMMAND => \@cmdlist,
               TAG => 'ScheduleAt');
        # 3
        Schedule::At::add (TIME => '199801181730', COMMAND => 'df');

        # This will remove #1 and #2 but no #3
        Schedule::At::remove (TAG => 'ScheduleAt');

        my %atJobs = Schedule::At::getJobs();
        foreach my $job (values %atJobs) {
               print "\t", $job->{JOBID}, "\t", $job->{TIME}, ' ',
                       ($job->{TAG} || ''), "\n";
        }

AUTHOR

       Jose A. Rodriguez (jose AT rodriguez.jp)