vtk_transition

Usage:         
vtk_transition_add dir envName resources cmd inputList outputList

Description:   
This procedure is controlled by make(ctrl,action), which can be one of 'trace', 'script', or 'echo'. 

If make(ctrl,action) is 'trace', this procedure is simply an interface to vtk_transition_add_to_trace, which takes the same arguments. This procedure tries to add the specified transition to the trace. If an identical transition already exists, its resources will be augmented, if necessary. At least all the files specified in `inNameList' and `outNameList' will have arcs to/from this transition. 

If make(ctrl,action) is 'script', the procedure prints on stdout an executable script valid for the architecture make(arch). 

If make(ctrl,action) is 'echo', the transition is echoed on stdout. 

The expected duration of the new transition is set to make(xdur). 
The autoforget flag is controlled with make(autoforget). 
The autokill is not a flag anymore but a time interval, and is controlled with make(autokill). 
The preemptable flag is controlled with make(preemptable). 
The jobclass is make(jobclass). 
The jobname is make(jobname) 
Old transitions with output arcs to files in `outNameList' are deleted. 

Side Effects: 
make(transId) is set.

Returns:       
make(transId)  or 0 if the transition could not be created.

Usage:         
vtk_transition_add_to_trace [OPTIONS] directory environment resources command inputFiles outputFiles

Description:   

Option:  
* -xdur time                 -- Set the expected duration of the job. 
* -autoflow bool             -- Set the autoflow flag. 
* -autoforget bool           -- Set the autoforget flag. 
* -autokill time             -- Set the autokill time 
* -jobclass name             -- Set the job class 
* -jobname name              -- Set the name of the job 
* -jobproj name              -- Set the project of the job, used for accouting purposes 
* -alreadycanonical bool     -- Assume that the directory is already canonical 
* -preemptable bool          -- The job is preemptable 
* -migratable bool           -- The job is migratable 
* -sticky bool               -- The I/Os declared are sticky 
* -nonexec bool              -- The job is non-executable 
* -jpp jpp                   -- Specify a job placement policy 
* -runmode runmode           -- Specify the run mode: normal, xterm_open, xterm_icon, xterm_none 
* -uniqueid bool             -- Force job to have a unique id by changing the environment, if required 
* -usesid  bool              -- Use sessionid of processes to determine the processes that belong to a job 
* -fstokens tokens           -- Set fstokens for the job (default 1) 
* -scheddate UnixTimestamp   -- Do not start tool before given timestamp (default 0) 
* -start      integer        -- Job array start index
* -finish     integer        -- Job array finish index
* -incr       integer        -- Job array increment
* -snapshot   string         -- Job environment snapshot property
* -origargs   bool           -- Save job original arguments
* -logfile    string         -- Name of the place

The -logoptions can be:
* -shared, if the output is shared among many jobs; all jobs must declare the output as shared
* -force,  if output conflicts are to be ignored (this is the default)
* -normal, resets all previous options

All nodes referenced in this procedure are added to the set with name make(setname). 
Input conflicts are ignored, output conflicts are forced, cycle conflicts are serious errors.

Create a job array. Place all created jobs in new set 'JobArray:setId'
For each job, the index is incremented from 'start' to  'finish' by 'increment'.
The procedure fails if the total number of jobs is greater than the allowed limit.

Returns:       
The id of the transition that has been added.
The id and name of the set containing the array jobs

Note:          
This procedure is normally accessed by means of vtk_transition_add which is a Tcl wrapper.
And nc run tcl proc submitArrayJobs

Usage:         
vtk_transition_array setid refjobid start finish increment

Description:   
Create a job array. Place all created jobs in the given set. For each job, the index is incremented from 'start' to 'finish' by 'increment'. The procedure fails if the total number of jobs is greater than the allowed limit.

Usage:         
vtk_transition_chown_to_me jobId

Description:   
Change owner (user) of the given job to the caller. 

Example: 
vtk_transition_chown_to_me 00123456

Usage:         
vtk_transition_color_control ACTION, ...

Description:   
Control the color used to display VALID/FAILED jobs depending on the exit status. ACTION may be one of RESET_VALID, GET_VALID, SET_VALID, RESET_FAILED, GET_FAILED, SET_FAILED Used only in the project.swd/gui.tcl configuration file. To be effective, it must be present in gui.tcl before vovconsole starts. 

Examples:
vtk_transition_color_control RESET_VALID
vtk_transition_color_control GET_VALID a; parray a
vtk_transition_color_control SET_VALID 10 pink
vtk_transition_color_control RESET_FAILED
vtk_transition_color_control GET_FAILED a; parray a
vtk_transition_color_control SET_FAILED 1 blue

Usage:         
vtk_transition_create_resumerjob jobToResumeId

Description:   
Create the resumer job for a suspended one. For internal use only. Used by vovpreemptd.

Returns:       
resumer job Id.

Usage:         
vtk_transition_dispatch jobId taskerId

Description:   
Manually force a dispatch of a job to the given tasker. If option -delayed is used, then only the tasker is chosen as the tasker for the job, but the job will be dispatched only when all resource constraints have been satisfied. RETURN: Ok or {Illegal Id} or {Non exec job} or Unauthorized

Usage:         
vtk_transition_failcode_pp mask

Description:   
Given a bit mask representing the failure modes for a job, this procedure returns a tab separated list of descriptive strings. 

Example:
vtk_transition_failcode_pp 0x101
"Preempted by owner\tBad exit status\t"

Usage:         
vtk_transition_find environment directory command

Description:   

Returns: 
The ID of the transition, or 0 if not found.

Usage:         
vtk_transition_fire jobId

Description:   
Fire a transition given its job id. Then wait for it to complete. 
The global variable fireCode is modified and can be used in case of error. 
It is assumed that we are already in the correct environment. 
This procedure uses the same code used by vovtasker to fire the transition. 
It is recommended that you use this procedure instead of trying to escape the 
command line in a way suitable for use by either 'exec' or /bin/sh.

Note:          
We now use fireCode instead of errorCode. 
We do not use errorCode because that is a Tcl variable and we do 
not seem to have control of it.

It is assumed that we are already  in the correct environment.
This procedure uses the same code used by vovtasker to fire the transition.
It is recommended that you use this procedure instead of 
trying to escape the command line in a way suitable for use by
either 'exec' or /bin/sh. 

Usage:         
vtk_transition_get transitionId [array]

Description:   
Returns information about a transition (i.e. a job). If the transitionId doesn't exist, an error is returned. If the transitionId refers to a job that has been retraced, the new id for the job is automatically used. 

The command has two forms, with and without an array specification. The form without the array specification is deprecated because it provides much less information and in a list that is difficult to parse. We recommend you use only the form with the array argument. 

Deprecated form: If array is not specified, a list of the following elements is returned: 
1. node status 
2. BARRIER or NORMAL (always normal) 
3. environment 
4. working directory 
5. command line 
6. resources 
7. legal exits 
8. user 
9. host 
10 exit status 
11. start date 
12. end date 
13. duration 
14. expected duration 


Preferred form: if array is specified, it is filled with information about the transition. Below is an example of usage of this form. 

vtk_transition_get 12345 jobInfo
parray jobInfo
jobInfo(autoflow)       = 0
jobInfo(autoforget)     = 0
jobInfo(autokill)       = 0
jobInfo(barrier)        = NORMAL
jobInfo(barrierinvalid) = 0
jobInfo(cmd)            = clevercopy -m 644 FTaux.pdf ../doc/html/pdf
jobInfo(cputime)        = 0
jobInfo(dir)            = ${BUILD_TOP}/src/doc/html
jobInfo(duration)       = 1
jobInfo(end)            = 1049580600
jobInfo(env)            = BASE+SUPPORT
jobInfo(exit)           = 0
jobInfo(group)          = users
jobInfo(host)           = alpaca
jobInfo(legalexit)      = 0
jobInfo(maxram)         = 0
jobInfo(nodets)         = 1049580600
jobInfo(priority)       = 0
jobInfo(qtime)          = 0
jobInfo(res)            = htmldoc linux
jobInfo(retracingid)    = 00000000
jobInfo(scheduled)      = 0
jobInfo(taskerid)        = 00000000
jobInfo(start)          = 1049580599
jobInfo(status)         = VALID
jobInfo(tool)           = clevercopy
jobInfo(unsafe)         = 0
jobInfo(user)           = casotto
jobInfo(userxdur)       = -1
jobInfo(xdur)           = 1

Usage:         
vtk_transition_get_io_names jobid  mask regexp

Description:   
For the given transition, give the list of input and outputs that match the given regular expression. 

Examples: 
vtk_transition_get_io_names 12345 I {csh$} 
vtk_transition_get_io_names 12345 IO chip 
vtk_transition_get_io_names 12345 O std

Usage:         
vtk_transition_get_or_create env cwd command resources

Description:   
Also called vtk_transition_find_or_create, where 
* env is the environment 
* cwd is the working directory (need not be canonical) 
* command is the complete command line 
* resource is the resource list

Usage:         
vtk_transition_operation jobId operation_method_or_plan

Description:   
Operation the job with the specified method. 

Example: 
vtk_transition_operation {$jobId} saveProfile

Usage:         
vtk_transition_preempt jobId [-noop] [-method METHOD_OR_PLAN] [-manualresume] [-resumeres RESLIST]

Description:   
Preempt the job with the specified method. 

Example:
vtk_transition_preempt $jobId -method SUSPEND -resumeres "License:abc" -manualresume
vtk_transition_preempt $jobId -method "BEGIN:RETRACING:EXT,USR1,vovsh 10:SUSPENDED:LMREMOVE 20:LMREMOVED:DONE"

Usage:         
vtk_transition_set transitionId array

Description   
Modify fields of a transition (job). 
Uses an array of the same format used in vtk_transition_get. 
Typically called after calling that function and modifying something in the array. 

For example: 
vtk_transition_get 12345 jobInfo 
set jobInfo(legalexit) "0 1" 
set jobInfo(res) "htmldoc linux"}
vtk_transition_set 12345 jobInfo 

There are limitations on what can be changed and when. 
Also, some changes have consequences including invalidating the job, 
marking the job unsafe, and moving the job to the correct fairshare bucket 
(taking the changes into account). Many fields can't be changed while a job is running. 

The following fields can be changed any time, including when the job is running. 

* autokill 		(duration job runs before being killed automatically) 
* fstokens 		(fairshare {tokens;} when changed, moves the job to the proper fairshare bucket) 
* iscohort 		(can only be changed by job's owner) 
* isdistributed (can only be changed by job's owner) 
* jobname 		(can only be changed by job's owner) 
* jpp 			(job placement policy) 
* numa 			(job placement non-uniform memory access {policy;} linux only) 
* legalexit 	(if the job is not running, the exit status is checked again 
				 with the new legal {values;} if it does not match, the job is invalidated) 
* preemptable 	(flag indicating the job can be preempted) 
* priority 		(schedule priority) 
* runmode 		(for example, xterm_iconic) 
* schedfirst 	(schedule first flag) 
* statuslogging (logging of node status {changes;} NONE|ALL|INVALID|DOWNCONE) 
* subjob 		(flag that indicates it is a sub job; not normally modified this way) 
* systemjob 	(flag that indicates it is a system job; not normally modified this way) 
* xdur 			(expected duration) 
* xpriority 	(execution priority) 

The following fields cannot be changed while the job is running. They can be changed by the job's owner or a project admin: 

* autoflow (flag that indicates a job should be {skipped;} if changed, job is moved to proper bucket) 
* end (end date/time of {job;} can only be changed for non-executable {jobs;} marks job unsafe) 
* ephemeral (flag that indicates the job is temporary and will go away after running)
* exit (exit status {code;} can only be changed for non-executable {jobs;} marks job unsafe) 
* host (execution host) 
* nojournal (flag that turns off journal entries for the job) 
* profile (flag that turns on profiling for the job) 
* qtime (time job spent queued) 
* res {(resources;} if changed for a scheduled job, the job is moved to the proper bucket) 
* scheddate (date/time job was scheduled) 
* start (start date/time of {job;} can only be changed for non-executable {jobs;} marks job unsafe) 

The following fields cannot be changed while the job is running. They can only be changed by the job's owner (not a project admin):

* autoforget 	(flag that indicates the job will be forgotten after completion) 
* cmd 			(command line of job; job is invalidated if changed) 
* deadline 		(the desired date/time the job should be completed) 
* dir 			(filesystem path where job runs; job is invalidated if changed) 
* env 			(named environment of job; job is invalidated if changed) 
* group 		(fairshare group; if changed for a scheduled job, the job is moved to the proper bucket) 
* jobclass 		(resource group) 
* jobproj 		(project associated with job) 
* osgroup 		(operating system group; can only be changed for non-executable jobs) 
* res,aux 		(aux resources; if changed for a scheduled job, the job is moved to the proper bucket) 
* submithost 	(host from which job is submitted) 
* tool 			(name of tool associated with command) 
* user 			(operating system user; can only be changed for non-executable jobs)

The following field can only be changed while the job is RETRACING (not RUNNING): 

* transfer 		(flag that indicates the job is in transfer to a tasker; causes smart sets to be recomputed)

Returns:       
0 if change was made or no changes were needed; 1 if there was an error; also one of the following messages: Job modified, Cannot modify, Not authorized, No change to be applied, Bad group name

Usage:         
vtk_transition_set_failcode jobId mask_or_long_char_code

Description:   
Add the specified codes specified in 'mask' to the specified job. 

Example:
vtk_transition_set_failcode $jobId 0x101
vtk_transition_set_failcode $jobId "no outputs"

Usage:         
vtk_transition_update_stats transitionId stat1 value1 ... ...

Description:
WHERE stat? is one of MAXVSIZE MAXRSS CURRSS MAXPGFLT TOTCPUTIME IS_SUSPENDED PID value is a 32-bit integer quantity Also supported are these values for "stat", which are followed by 64-bit values: READCNT WRITECNT TOTCPUTIME64. TOTCPUTIME and TOTCPUTIME64 are expressed in milliseconds. MAXRSS CURRSS MAXVSIZE are in MB. READCNT WRITECNT are in bytes.  

Also supported are these values for "stat", which are followed by 64-bit values: READCNT WRITECNT TOTCPUTIME64.
TOTCPUTIME and TOTCPUTIME64 are expressed in milliseconds. MAXRSS CURRSS MAXVSIZE are in MB. READCNT WRITECNT are in bytes.