.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "At 3pm"
.TH At 3pm "2021-01-03" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Schedule::At \- OS independent interface to the Unix 'at' command
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& require Schedule::At;
\&
\& Schedule::At::add(TIME => $string, COMMAND => $string [, TAG =>$string]);
\& Schedule::At::add(TIME => $string, COMMAND => \e@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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This modules provides an \s-1OS\s0 independent interface to 'at', the Unix 
command that allows you to execute commands at a specified time.
.IP "Schedule::At::add" 4
.IX Item "Schedule::At::add"
Adds a new job to the at queue.
.Sp
You have to specify a \fB\s-1TIME\s0\fR and a command to execute. The \fB\s-1TIME\s0\fR has
a common format: YYYYMMDDHHmm where \fB\s-1YYYY\s0\fR is the year (4 digits), \fB\s-1MM\s0\fR
the month (01\-12), \fB\s-1DD\s0\fR is the day (01\-31), \fB\s-1HH\s0\fR the hour (00\-23) and
\&\fBmm\fR the minutes.
.Sp
The command is passed with the \fB\s-1COMMAND\s0\fR or the \fB\s-1FILE\s0\fR parameter.
\&\fB\s-1COMMAND\s0\fR can be used to pass the command as an string, or an array of
commands, and \fB\s-1FILE\s0\fR to read the commands from a file.
.Sp
The optional parameter \fB\s-1TAG\s0\fR serves as an application specific way to 
identify a job or a set of jobs.
.Sp
Returns 0 on success or a value != 0 if an error occurred.
.IP "Schedule::At::readJobs" 4
.IX Item "Schedule::At::readJobs"
Read the job content identified by the \fB\s-1JOBID\s0\fR or \fB\s-1TAG\s0\fR parameters.
.Sp
Returns a hash of \s-1JOBID\s0 => \f(CW$string\fR where \f(CW$string\fR 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.
.IP "Schedule::At::remove" 4
.IX Item "Schedule::At::remove"
Remove an at job.
.Sp
You identify the job to be deleted using the \fB\s-1JOBID\s0\fR parameter (an 
opaque string returned by the getJobs subroutine). You can also specify
a job or a set of jobs to delete with the \fB\s-1TAG\s0\fR parameter, removing
all the jobs that have the same tag (as specified with the add subroutine).
.Sp
Used with \s-1JOBID,\s0 returns 0 on success or a value != 0 if an error occurred.
Used with \s-1TAG,\s0 returns a hash reference where the keys are the \s-1JOBID\s0 of
the jobs found and the values indicate the success of the remove operation.
.IP "Schedule::At::getJobs" 4
.IX Item "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 \fB\s-1TAG\s0\fR or \fB\s-1JOBID\s0\fR parameters so only matching
jobs are returned.
For each job the key is a \s-1JOBID\s0 (an \s-1OS\s0 dependent string that shouldn't be 
interpreted), and the value is a hash reference.
.Sp
This hash reference points to a hash with the keys:
.RS 4
.IP "\s-1TIME\s0" 4
.IX Item "TIME"
An \s-1OS\s0 dependent string specifying the time to execute the command
.IP "\s-1TAG\s0" 4
.IX Item "TAG"
The tag specified in the Schedule::At::add subroutine
.RE
.RS 4
.RE
.SH "Configuration Variables"
.IX Header "Configuration Variables"
.IP "\(bu" 4
\&\f(CW$Schedule::At::SHELL\fR
.Sp
This variable can be used to specify shell for execution of the scheduled command.
Can be useful for example when scheduling from \s-1CGI\s0 script and the account of the user under which httpd runs
is locked by using '/bin/false' or similar as a shell.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.Vb 1
\& use Schedule::At;
\&
\& # 1
\& Schedule::At::add (TIME => \*(Aq199801181530\*(Aq, COMMAND => \*(Aqls\*(Aq, 
\&        TAG => \*(AqScheduleAt\*(Aq);
\& # 2
\& @cmdlist = ("ls", "echo hello world");
\&
\& Schedule::At::add (TIME => \*(Aq199801181630\*(Aq, COMMAND => \e@cmdlist, 
\&        TAG => \*(AqScheduleAt\*(Aq);
\& # 3
\& Schedule::At::add (TIME => \*(Aq199801181730\*(Aq, COMMAND => \*(Aqdf\*(Aq);
\&
\& # This will remove #1 and #2 but no #3
\& Schedule::At::remove (TAG => \*(AqScheduleAt\*(Aq);
\&
\& my %atJobs = Schedule::At::getJobs();
\& foreach my $job (values %atJobs) {
\&        print "\et", $job\->{JOBID}, "\et", $job\->{TIME}, \*(Aq \*(Aq, 
\&                ($job\->{TAG} || \*(Aq\*(Aq), "\en";
\& }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Jose A. Rodriguez (jose \s-1AT\s0 rodriguez.jp)