The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Sys-Manage-1.01
River stage zero No dependents
++
/ Sys::Manage::Schedule

NAME

Sys::Manage::Schedule - Scriptic schedule trunk

SYNOPSIS

Script ('atSched.pl')
  use Sys::Manage::Schedule;
  my $s =Sys::Manage::Schedule->new([@ARGV], -option=>value,..);

  if ($s->at('-a')) {   # at any other item execution
        ...
  }
  if ($s->at('-'        # at system scheduler arguments given
        ,'17:20','/interactive','/every:M,T,W,Th,F,S,Su') {
        ...
  }
  if ($s->at('-'        # ... automatically filling arguments repeating
        ,['17:23','/interactive','/every:M,T,W,Th,F,S,Su']
        ,['17:24'])) {
        ...
  }
  if ($s->at('-s',0)) { # at operating system startup, if automatic MSWin32 service
        ...
  }
  if ($s->at('-d0')) {  # at the beginning of the day
        ...
  }
  if ($s->at('-d2s')) { # at the end of the day, switching user
        ...
  }
  if($s->at('-'         # at perl atSched.pl -run test
        ,'test')) {
        ...
  }
  if($s->at('-s'        # at perl atSched.pl -surun test
        ,'test')) {
        ...
  }
  if ($s->at('-s'
        ,'smrmt')) {    # at perl atSched.pl -surun-l smrmt command-line
        $s->run('smrmt.bat', $s->qclad(@ARGV[2..$#ARGV]))
  }
Command line
  perl atSched.pl -runmod atarg

  -set          (default) add/replace scriptic schedule into system schedule
  -setdel       clear scriptic schedule from system schedule
  -run  atarg   run 'atarg' entry from system scheduler
  -surun atarg  run 'atarg' entry switching user
  -surun-l ...          displaying output even from MSWin32 service
  -surun-seconds...     calling soon('-', seconds, 'self', '-run',...)
  -svcinst      install scriptic schedule as MSWin32 service to switch user
  -svcinst user password
  -svcdel       remove scriptic schedule MSWin32 sevice
  -logask       filter and display log file

  -run  name    arg...  running as named command line,
  -surun        name    arg...          user may be switched
'at' call options
  -a            run at any '-run'/'-runsu'
  -s            run switching user
  -s    => 0    ... at automatic MSWin32 service startup
  -w            redirect stdout and stderr into log file
  -d0 -d1 -d2   at day   begin, middle, end
  -n0 -n1 -n2   at night begin, middle, end

DESCRIPTION

The purpose of this module is to implement a scriptic schedules or scripts for scheduling and executing Perl codes inside.

A benefit of this module is preliminary for MSWin32 platform with 'at' commands and impersonations, then for UNIX where 'crontab':

* Keeping persistent or significant scheduled commands in a file (at, -set).

* Automatically filling repeating scheduler arguments (at).

* Running impersonated (switched user, -s).

* Logging of execution (-dirv, -w, runlog, vfname).

* Scheduling relative at day or night begin/middle/end (-d0,-d1,-d2,-n0,-n1,-n2).

* Scheduling cyclic tasks (soon)

* Scheduling at operating system startup (-s,0).

This module is implemented and tested with Perl 5.6/5.8 on MSWin32 2000/2003.

SLOTS

SLOTS

Usually no options need to be mentioned in a scriptic schedule.

-d0
        =>8
-d1
        =>12
-d2
        =19

Day begin, middle, end hour. See also AT OPTIONS, -n0, -n1, -n2.

-dirb
        => base directory

Base directory of script execution, filled automatically using $0.

-dirm
        => directory marker sign

Directory marker, '/' or '\', filled automatically using $0 or $^O.

-dirv
        => variables directory

Directory for log and flag files. Default is existing '-dirb/var' subdirectory, or -prgcn will be created. Log file automatic truncation implemented, see -logmax.

-logmax
        => about 1024*1024 | false

Maximum size of log file, bytes. Used for automatic truncation.

-n0
        =>22
-n1
        =>0
-n2
        =5

Night begin, middle, end hour. See also AT OPTIONS, -d0, -d1, -d2.

-prgcn
        => f($0)

Common name of script, used also in -dirv subdirectory, filled automatically using $0.

-prgfn
        => f($0)

Full file name of script, filled automatically using $0.

-prgsn
        => f($0)

Short file name of script, used also as MSWin32 service name (-svcinst), filled automatically using $0.

-runmod
        => run mode

Run mode of script. To be obtained from command line.

See also RUN MODES.

-runarg
        => schedule arguments escaped

Schedule entry to be executed while some -runmod (-run, -runsu). To be obtained from command line.

-time
        => time()
-timel
        => localtime()

Time and localtime when script started

METHODS

METHODS

The main methods are new and at.

at (?-options, scheduler arguments,..) -> allow execution
at (?-options, [scheduler arguments],..) -> allow execution
at (?-options, entryName) -> allow execution
at (?-options) -> allow execution
at (?-options, ..., ?sub{}(self)) -> execute sub{} and allow execution

Header of scriptic schedule entry. Or scriptic schedule entry itself, if sub{} given. Allows execution of entry if -run or -runsu. Or sets corresponding system scheduler entries if -set.

Special entryName '0' is intended for operating system startup event (may be implemented, i.e., as a result of -svcinst).

See also AT OPTIONS, soon.

chpswd (user, password, additional host || [host, service],..) -> success

Changes MSWin32 user and service password. Service name estimated is -prgsn. Default user is -prgcn. Default password is autogenerated. Additional computers and/or services will be processed after local, treating empty computer as local and empty service as -prgsn.

Implemented for MSWin32 only, Windows Resource Kit used.

cmdfile (? script file || false, command file, ? history file || false, ? redirect log file || false)
cmdfile (sub{}(command row, redirect log file),...)
cmdfck (script file, command file, ? history file || false, ? redirect log file || false)
cmdfck (sub{}(commands file, ? history file, ? redirect log file),...)

This is an utility methods from Sys::Manage::CmdFile may be useful sometimes.

cmdfile proceeds text file interpreting rows as commands for script or sub{} and moving rows proceeded to history file if given.

cmdfck checks commands file for command rows present. If commands found, executes script or sub{} given once, for file names.

Examples with Sys::Manage::Cmd script:

        $s->runlog('perl', './bin/smcmv.pl', '-vct', '-gx', 'cmdfile'
                , './var-cmd/cmd-night-do.txt', 'cmd-night-done.txt','cmd-log.txt');
        $s->cmdfile(sub{$s->runlcl("perl ./bin/smcmv.pl -vt $_") ||die $?>>8}
                , './var-cmd/cmd-night-do.txt', 'cmd-night-done.txt','cmd-log.txt');
        $s->cmdfck(sub{$s->runlcl("perl ./bin/smcmv.pl -vct -gx cmdfile $_")}
                , './var-cmd/cmd-night-do.txt', 'cmd-night-done.txt','cmd-log.txt');
        $s->cmdfck(sub{$s->runlog("perl ./bin/smcmv.pl -vct -gx cmdfile", @_)}
                , './var-cmd/cmd-night-do.txt', 'cmd-night-done.txt','cmd-log.txt');

        $s->runlog('perl', './bin/smcmv.pl', '-vct', '-gx', 'cmdfile'
                , './var-cmd/cmd-night-assign.txt', '""', 'cmd-log.txt');
        $s->runlog('perl', './bin/smcmv.pl', '-vct', '-gx', 'cmdfile'
                , './var-cmd/cmd-night-sched.txt', '""', 'cmd-log.txt');
daemonize ()

Suppresses STDIN, STDOUT, STDERR and calls setsid. See perlipc.

ftruncate (file name) -> success

Truncates file to -logmax, if greater then.

fread (file name) -> content

Reads file and returns content as a string.

fwrite (file name, string,...) -> success
fwrite (>>file name, string,...) -> success

Writes file or appends to it.

hostdomain() -> DNS domain name
hostname() -> full DNS host name
hostnode() -> node name

DNS domain, host, node name of this computer.

logask (?-opts, ?-fLogFile, ?-dDateFormat, ?start, ?end, condition)

Filter log file.

Options: 'v'erbose output (default), 's'tring return (for function call); '>=' or '<=' start and end conditions (default), '>' or '<' conditions.

Log file: file path and name, w32:eventLogName, default is log of this script.

Date format: any of /([ymdhs]+\W)+/, default is 'yyyy-mm-dd hh:mm:ss'

Start and End: 'yyyy-dd-mm...' row sample; /-[\d]+[dhm]/ - days, hours, minutes ago.

Query: 'all' (default), 'pid's running, 'err'ors, 'warn'ings and errors, expression.

Iterator marker switch may be within 'Options' or ending 'Start': '-mm' - move next, '-ma' - move next for 'All' only, '-mu' - use current.

new ('class', -option=>value,..) -> new object
new ('class', [command line arguments], -option=>value,..) -> new object

Creates new Sys::Manage::Schedule object. See also set syntax.

printflush (print arguments) -> print result

Prints STDOUT with $|=1. May be useful where output redirections.

run (OS command, arg,..) -> !($?>>8)
runopen (OS command, arg,..) -> IO::Handle
runlist (OS command, arg,..) -> output strings list
runlcl (OS command, arg,..) -> !($?>>8)
runlog (OS command, arg,..) -> !($?>>8)

Executes operating system command alike system(). Using runlcl, only command line and exit code will be logged. For runlog redirection, IPC::Open3 used, instead of immediate STDOUT/STDERR redirection in -w.

set () -> (slot names of the object)
set (-option) -> value of the option given
set (-option=>value,..) -> self object
set ([command line arguments], -option=>value,..) -> self object

Retrieves and sets values of the SLOTS. $s->{-option} direct access may be used also, but set smartly processes some options.

soon (?-options, seconds, entryName, sub{}) -> result

Cyclic entry in scriptic schedule. Sub{} will be executed after seconds given since its previous execution. The first sub{} execution depends on the script executions.

Implemented for MSWin32 only.

See also at, -i, -s, -w.

soon (?-options, seconds, command line) -> at
soon (?-options, seconds, program, ?arg,...) -> at
soon (?-options, seconds, 'self', -runmod, -runarg, ?arg,...) -> at

Schedules command line given with delay, -i option is available. Alike 'soon' utility in Windows Resource Kit.

Implemented for MSWin32 only.

startup ()

Initialises execution of the schedule script. Called by the first at if not yet.

vfname (partial file name) -> full file name

File name, based on -dirv, -dirm, -prgcn. Log file name is vfname('log.txt'); lock file name is vfname('lck.txt'); Additional lock file name is vfname('lcs.txt'); -d0 flag file name is vfname('d0.txt'). This method may be useful forming names of additional log files.

AT OPTIONS

AT OPTIONS

at call options considered as a first argument beginning with '-' sign. Several options may be catenated into options string without additional '-' signs.

-a

Execute at any -run ('-a') or -runsu ('-as').

-d0
-d1
-d2
-n0
-n1
-n2

Execute daily at the beginning/middle/end of the day, or nightly at the beginning/middle/end of the night. Only one of this options may be included in each at.

-i

Execute interactivelly, Only for soon and -d0 etc.

-s
(-s,0)

Execute switching user (-runsu).

On MSWin32 user may be switched using impersonated service (installed via -svcinst), or via WMI (-susr and -spsw required).

On other platforms 'su' is called by 'root', 'sudo' otherwise.

Special at('-s',0) form means automatic MSWin32 service startup at operating system startup.

-w

Write (redirect) STDOUT/STDERR into log file. See better runlog, instead of -w, which may not work sometimes.

RUN MODES

RUN MODES

Usually operator need not deal with any run mode, because -set is default, when empty arguments.

The mainly used run modes are -set, -setdel, -run, -surun/-runsu.

Supplemental run modes are -logask, -svcinst, -svcdel.

-runmod-e

Additional '-e' option of the run mode (-run-e, -runsu-e, -surun-e, -surun-seconds-e, -surun-l-e) is to consider additional to -runarg command-line arguments (@ARGV[2..$#ARGV]) as escaped and unescape it.

-logask

Filter and display log file, see logask.

-run

Run -runarg entry.

-runsu

Run -runarg entry with at(-s) option after user is switched.

-surun schedule script execution starts -runsu schedule script execution using -susr/-spsw or -prgsn MSWin32 service installed with -svcinst.

-set

Remove existing scriptic schedule entries (recognized using -prgfn) from the system schedule ('at' or 'crontab'). Add actual scriptic schedule using at method calls resulting in 'at' or 'crontab' calls.

-setdel

Remove existing scriptic schedule entries (recognized using -prgfn) from the system schedule ('at' or 'crontab').

-svcdel

Remove -prgsn MSWin32 service.

See also -svcinst.

-svcinst

Create -prgsn MSWin32 service using 'instsrv' and 'srvany' from Windows Resource Kit. Additional command line arguments are user name and password.

Service may be needed to switch user (-s, -runsu).

Service may be deleted using -svcdel.

Settings of service created should be checked.

-surun

Switch user and execute -runsu -runarg. Additional command line arguments specified after -runarg will be transferred to -runsu.

-surun schedule script execution starts -runsu schedule script execution using -susr/-spsw or -prgsn MSWin32 service installed with -svcinst.

See also -s.

-surun-l

Additional '-l' option of -surun, is to display output of -runsu. This is useful on MSWin32 where -surun does not do this, see -s.

-surun-seconds

Adding digits to -surun execute soon('-', seconds, 'self', '-run',...) and display it's output.

LIMITATIONS, BUGS, PROBLEMS

Limitations, Bugs, Problems

Implemented and tested with Perl 5.6.0 and 5.8.8 on Windows 2000/2003.

Some functioning is for MSWin32 only.

See at the top of the source code.

VERSION

'2009-10-10'

New -surun-l, -surun-seconds, -runmod-e. Output of any named command in the schedule script may be achieved simply.

Corrected some error() calls.

'2009-10-03'

File locks rearranged. Serialised startup of -surun and -runsu, execution of soon and chpswd.

'2009-09-05'

logask can now convert digital date-times reading log file.

'2009-08-30'

runlog can now distinguish STDERR and log this as errors.

'2009-08-26'

Introduced iterator marker switch for logask.

Several corrections in logask, run, runopen.

'2009-06-24'

Named command lines implemented: perl atSched.pl -run|-surun name arg... -surun additional command line arguments specified after -runarg will be transferred to -runsu.

soon extended to accept program arguments as list.

So, schedule script may be used also to log some unforeseen commands.

'2008-12-18'

Changed format of log file and messages.

-logpid removed - use logask command instead.

'2007-11-08'

New fread, hostdomain, hostname, hostnode methods.

'2007-08-13'

Behaviour of -logpid files improved, content changed, cleanup implemented.

'2007-08-10'

$ENV{SMSECS} may be used for cmdfile and cmdfck.

'2007-03-07'

New -logpid to create runtime pid file for monitoring and diagnostics during runtime.

'2005-12-14'

New cmdfck method.

'2005-11-25'

Published 0.50 version.

'2005-09-15'

Started

LICENSE

This is free software; you can use redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Andrew V Makarow <makarow at mail.com>, for tav