export SCHEDULE_JOBS. -j accepts relative addresses. --command-text

ChangeLog

@@ -1,5 +1,12 @@
 # ChangeLog for schedule
 
+*schedule-v7.6.0:
+	Martin Väth <martin at mvath.de>:
+	- export SCHEDULE_JOB to queued jobs
+	- allow (relative) job address for -j
+	- new option --command-text
+	- manpage: explain side effects of remove and insert more verbosely
+
 *schedule-v7.5.4:
 	Martin Väth <martin at mvath.de>:
 	- Use state instead of static closures

bin/schedule

@@ -3,7 +3,7 @@
 # This is part of the schedule project.
 
 BEGIN { require 5.012 }
-package Schedule v7.5.3;
+package Schedule v7.6.0;
 
 use strict;
 use warnings;
@@ -48,6 +48,7 @@ my $nouser = '';
 my $nohost = '';
 my $nodir = '';
 my $nocommand = '';
+my @commandtext = ();
 my $keepdir = '';
 my $destjob = 0;
 my $tests = [[], [], []];
@@ -67,7 +68,7 @@ sub cmd_queue {
 	require Schedule::Client::Cmd::Queue;
 	&Schedule::Client::Cmd::Queue::queue(@_,
 		$destjob, $cancel, $ignore, $immediate, $keepdir, $tests,
-		$status, $title, $text)
+		$status, $title, $text, @commandtext)
 }
 
 sub cmd_run {
@@ -153,6 +154,7 @@ eval 'END { $s->did_alpha() || $s->exec_alpha() }';
 
 $s->get_options(
 	'exit|e=i', \$cancel,
+	'command-text|C=s', \@commandtext,
 	'no-user|nouser|u', \$nouser,
 	'no-host|nohost|H', \$nohost,
 	'no-dir|nodir|D', \$nodir,
@@ -170,7 +172,7 @@ $s->get_options(
 	'no-stime|nostime', sub { $stime = '' },
 	'no-etime|noetime', sub { $etime = '' },
 	'no-time|notime|n', sub { $qtime = $stime = $etime = '' },
-	'job|j=i', \$destjob,
+	'job|j=s', \$destjob,
 	'ok|o=s', $tests->[0],
 	'finished|x=s', $tests->[1],
 	'started|s=s', $tests->[2]

share/schedule/Schedule/Client/Cmd/Queue.pm

@@ -4,7 +4,7 @@
 # This is part of the schedule project.
 
 BEGIN { require 5.012 }
-package Schedule::Client::Cmd::Queue v7.5.4;
+package Schedule::Client::Cmd::Queue v7.6.0;
 
 use strict;
 use warnings;
@@ -44,7 +44,8 @@ sub queue_init {
 sub queue {
 	&queue_init();
 	(my $runmode, $destjob, $cancel, my $ignore, my $immediate,
-		my $keepdir, my $tests, $status, $title, $text) = @_;
+		my $keepdir, my $tests, $status, $title, $text,
+		my @commandtext) = @_;
 	$s->fatal("illegal --ignore $ignore") if(defined($ignore) &&
 		!(&is_nonnegative($ignore) && $ignore <= 0xFF));
 	$s->fatal("illegal --immediate $immediate") if(defined($immediate) &&
@@ -77,7 +78,8 @@ sub queue {
 	($user, $host, $hosttext, $cwd) =
 		(&my_user(), &my_hostname, &my_hosttext, &my_cwd($keepdir));
 	my $success = &client_send(join("\c@", $runmode, $destjob, $user,
-		$host, $hosttext, $cwd, @ARGV));
+		$host, $hosttext, $cwd,
+		((@commandtext) ? (@commandtext) : (@ARGV))));
 	$success = '' unless(&client_recv($unique));
 	if($query) {
 		$unique =~ m{^([^\c@]*)\c@(.*)};
@@ -118,6 +120,11 @@ sub queue {
 		&signals()
 	}
 	&statusbar('running');
+	if ($job ne '') {
+		$ENV{'SCHEDULE_JOB'} = $job
+	} else {
+		delete($ENV{'SCHEDULE_JOB'})
+	}
 	my $sys = system(@ARGV);
 	if($sys < 0) {
 		$s->error($jobtext . ' could not be executed') unless($s->quiet());

share/schedule/Schedule/Client/Scheduleman.pm

@@ -4,7 +4,7 @@
 # This is part of the schedule project.
 
 BEGIN { require 5.012 }
-package Schedule::Client::Scheduleman v7.5.0;
+package Schedule::Client::Scheduleman v7.6.0;
 
 use strict;
 use warnings;
@@ -136,8 +136,20 @@ When both are succesfully finished, B<shutdown -h now> is executed.
 Queue I<cmd> I<arg> ... I<arg> for execution.
 The command will be executed using perl's system(I<cmd>, I<arg>, ..., I<arg>).
 
-The following environment variables are used for later output with
-B<schedule list>:
+The queued job will receive the environment variable B<SCHEDULE_JOB>
+which contains the address of the job.
+If the job wants to know the (current) job number, it might use
+
+B<schedule number $SCHEDULE_JOB>
+
+but this result is subject to races (of reordering of the queue).
+It is better to use B<$SCHEDULE_JOB> (with possibly a relative offset)
+instead if possible, see the section B<SPECIFYING JOBS> for more details.
+
+When a new job is queued also the output for B<schedule list> is stored.
+The content of the command in this output can be modified during queueing
+with the B<--command-text> option, and the following environment variables
+are used to modify some other details.
 
 =over 16
 
@@ -285,15 +297,20 @@ the command acts as if the argument B<:> is given for I<jobs>.
 If the exit status is nonzero, it is the maximum of B<1> and of all exit values
 of jobs specified through B<--ok>.
 
-=item B<remove> I<jobs>
+=item B<remove> I<jobs> or B<delete> I<jobs>
 
 Remove I<jobs> from the list of B<queued> jobs and let them exit (with the
 exit status specified by B<--exit> if that value is nonzero).
 
 Note that if the job is already started it is not stopped, but its exit status
 cannot be queried through B<schedule> anymore.
 
-=item B<insert> I<jobs>
+Be aware that removing a job renumbers all subsequent jobs in the queue.
+It is intentional that commands like B<schedule run> are not informed about
+this renumbering so that B<remove> and B<insert> can be used to modify the
+order of the running queue.
+
+=item B<insert> I<jobs> or B<move> I<jobs>
 
 The list of queued jobs is ordered differently by shifting all specified I<jobs>
 to to the location specified with B<--job>. Thus, if B<--job=1>,
@@ -303,6 +320,13 @@ means to shift to the end of the list, and negative numbers count from the
 end of the list. For instance B<schedule --job=-1 insert :2> will shift the
 first two jobs one command before the end of the list.
 
+Be aware that this command can renumber many commands in the queue.
+For instance, when moving the first job to the end, all commands obtain
+different numbers.
+It is intentional that commands like B<schedule run> are not informed about
+this renumbering so that B<remove> and B<insert> can be used to modify the
+order of the running queue.
+
 =item B<cancel> I<jobs>
 
 All of the I<jobs> which are not yet started, they will exit
@@ -395,6 +419,8 @@ This means e.g. that B<schedule queue> will by default queue new jobs after
 the end of the queue while e.g. B<schedule insert> will shift the selected
 jobs (in their order of selection) to the end of the queue.
 
+I<jobnr> can either be a number or a (relative) job address.
+
 =item B<--ok=>I<jobs> or B<-o> I<jobs>
 
 This option can be used repeatedly; all arguments are collected.
@@ -476,7 +502,7 @@ and discards all subsequent standard input/output.
 
 This is like B<--daemon>, but fully detaches from terminal, discarding also
 error output. To use this option, your perl must have a functioning POSIX.
-To avoid unexpected issues with relatice paths, the current working directory
+To avoid unexpected issues with relative paths, the current working directory
 is kept (and thus remains occupied). Therefore you might want to change to the
 root directory before using this option.
 
@@ -577,6 +603,15 @@ The following substitutions are made in I<format>:
 
 The default I<format> is: B<%a(%s)%u@%h%H:%c>
 
+=item B<--command-text=>I<text> or B<-C> I<text>
+
+When queuing or starting a command, instruct the server to lie about the
+actual command: Let it act as if I<text> was the specified command.
+If this option is used several times, the subsequent I<text> is treated
+as argument to the given command.
+The intention is to allow scripts queuing commands to give useful "comments"
+(e.g. if they just schedule a dummy command like "true").
+
 =item B<--exit=>I<exitstatus> or B<-e> I<exitstatus>
 
 For B<queue>, B<start>, or B<start-or-queue>: If the command is canceled by
@@ -702,11 +737,12 @@ If you specify the number 0 or a negative number, the counting is backwards
 from the queue.
 
 Note that the association of a number to the job can change when you rearrange
-the queue (by the B<insert> or B<delete> command or by queuing new jobs
+the queue (by the B<insert> or B<remove> command or by queuing new jobs
 not at the end of the queue).
 For this reason, there is also a possibility to specify jobs by their
 addresses. A job address has the form B<@>I<number> and can be seen by
-the output of the B<list> or B<address> command.
+the output of the B<list> or B<address> command and is also exported in
+the B<SCHEDULE_JOB> environment variable to the corresponding job.
 Such a job address does never change. However, it can become invalid:
 If the job is removed from the queue, the address becomes invalid.
 

share/schedule/Schedule/Connect.pm

@@ -7,7 +7,7 @@
 # common parts of schedule and schedule-server which are always needed
 
 BEGIN { require 5.012 }
-package Schedule::Connect v7.5.4;
+package Schedule::Connect v7.6.0;
 
 use strict;
 use warnings;
@@ -51,13 +51,15 @@ my $serversupallowed = '';
 # If "undefined", no corresponding restriction is required.
 
 my $version753 = version->declare('v7.5.3');
-my $version754 = $VERSION;
+my $version754 = version->declare('v7.5.3');
+my $version760 = $VERSION;
 my %minversion = (
 # temporary:
-	'Schedule' => $version753,
+	'Schedule' => $version760,
 	'ScheduleServer' => $version753,
 	'Schedule::Client::Clientfuncs' => $version754,
-	'Schedule::Client::Cmd::Queue' => $version754,
+	'Schedule::Client::Cmd::Queue' => $version760,
+	'Schedule::Client::Scheduleman' => $version760,
 	'Schedule::Helpers' => $version754,
 	'Schedule::Log' => $version754,
 

zsh/_schedule

@@ -55,6 +55,7 @@ case $service in
 	service_opts+=(
 {'(--exit)-e+','(-e)--exit='}'[set specified exitstatus]:exitstatus:(0)'
 {'(--job)-j+','(-j)--job='}'[JOB (set jobnumber)]:jobnumber:(0)'
+{'(--command-text)-C+','(-C)--command-text='}'[specify command text (accumulative)]:command text:()'
 '(--immediate -I '{'--ignore)-i+','-i)--ignore='}'[force specified exitstatus]:exitstatus:(0)'
 '(--ignore -i '{'--immediate)-I+','-I)--immediate='}'[report immediately specified status)]:exitstatus:(0)'
 '(--no-host --nohost -H '{'--no-user --nouser)-u','--nouser -u)--no-user','--no-user -u)--nouser'}'[Suppress output of user]'