FDL Procedures Reference

Procedure Args Description
A note checkFlag Adds Annotations to the most recently declared node, be it an input, an output, or a job. If checkFlag is true, the procedure checks the list of existing annotations in order to avoid duplicates. Examples: 
J vw sim $block.v $block.sti
A "Run the simulation on block $block"
I $block.sti
A "The stimulus file"

# The binary 'clevercopy' does not need a wrapper
J clevercopy $file $goldDir
A "Publish $file"
AD id1 id2 barrier Creates an artificial dependency between a job (id1) and another job or set (id2). Useful if no natural file dependency exists between them. Makes id2 dependent on id1. barrier defaults to 0 (off). Examples: 
AD $id1 $id2   ; # id2 is dependent on id1
AD $id1 $id2 1 ; # id2 is dependent on id1 with a barrier on $id2.
CAPSULE [options] script Define a Capsule on the Fly.
Option
Description
-vars list_of_vars
Allows the passing of specified variables for use inside the CAPSULE.
Examples: 
J vw mycopy aa bb
CAPSULE {
    I [shift]
    O [shift]
}
J vw mycopy aa bb
CAPSULE { I aa; O bb }
J vw vsyn -cell $cell -corner $corner
CAPSULE -vars [list cell corner] { 
    I $cell.$corner.in
    O $cell.$corner.out 
}
D database Sets the Databases for all subsequent files. The default database is "FILE". Examples: 
D FILE
D FILEX
D GLOB
D JOBSTATUS
D LINK
D PHANTOM
D VOVSETS
D ZIP
E environment OPTIONAL_SCRIPT The default environment is "BASE". The procedure E sets the environment for all subsequent jobs. If the optional script is specified, the value of the current environment is reset after evaluation of the script.

The environment for vovbuild itself is not affected (use ves if you want to change the environment of vovbuild itself).

The command vel will list the known environments in your installation, Normally the following locations are searched for environment information :
  • $SWD/environments
  • $VOVDIR/local/environments
  • $VOVDIR/etc/environments
Examples:
E BASE
E BASE+SUNCC
E EPIC(5.3)
E BASE+GNU {
    J vw cp aa bb
}
FLAGS job-flag ... The procedure FLAGS sets flags for the most recent job. It is to be used after a T or a J. The flags that can be set are: autoflow, autoforget, preemptable, doprofile, nojournal, schedfirst, and skip. (Note: autoflow and skip are the same flag) 
J vw cp aa bb
FLAGS skip

J vw date
FLAGS preemptable doprofile autoforget
I [options] FILE FILE ... This is an input declaration. Its argument is a list of file names. Each file is declared as an input of the job created with the most recent J or T command. It is an error to call I without having called J or T first. Defining cyclic dependencies generates an error.
Option
Description
-db name
Sets the database name. The default is "FILE".
-sticky
Specify that the file is an input, even if it's not actually a true input at runtime.
-consumed
Specify that the input disappears if the tool completes successfully (e.g. the tool gzip consumes its input).
-normal
This option undoes the other options.
-quote
Use the input name as given, instead of mapping it to the corresponding logical canonical name.
-trigger,run
If the input changes, automatically run the downcone
-trigger,stop
If the input changes, automatically stop all jobs in the downcone
-noop
Ignored
-normal
Ignored
-links
Ignored in this context
Examples:
I $inFile
I -consumed xx.tar
I -db PHANTOM net.h
indir [options] directory script Executes Tcl script in the given directory.
Option
Description
-create
Create directory if it does not exist.
-onerror script
Execute "script" if the directory does not exist.
Example: 
indir -create Subdir {
    E BASE {
        J vw cp aa bb
        J vw cp bb cc
    }
}
indir -onerror {
    VovMessage "Skip directory Subdir because it does not exist" 
} Subdir {
    E BASE {
        J vw cp aa bb
        J vw cp bb cc
    }
}
INSTRUMENTED command Add a job that is implemented by a properly instrumented script, that is a script that outputs FDL if called with the VOV Instrumentation Library environment variable defined. Example: 
INSTRUMENTED ./mycopy aa bb
J args Mnemonic for 'Job'

Declares a job where the associated capsule (if it exists) is used at build time. This procedure is identical to T, except that T does NOT search for corresponding capsule. The arguments form the command line for a new job to be added to the trace. Environment and working directory for the job are taken from the current settings. If an identical job already exists in the trace, nothing happens. The procedure returns the VovId of the job. The status of a newly created job is always INVALID.

If the procedure is passed multiple arguments, each argument is quoted if necessary. If the procedure is passed a single list, all elements in the list are "join'ed" together with spaces.

Examples: 
J vw cp aa bb
J vw vdc_shell -f $script
J_FINAL <none> Similar to T_FINAL, J_FINAL indicates that the inputs and outputs declared through I and O commands associated with the last J declaration are the only inputs and outputs for that J. Any inputs and outputs that were associated with this J from a previous vovbuild but not declared again in this vovbuild will be removed.
L legal_exit_spec Set the list of legal exit status values for al subsequent jobs. Examples: 
L "0";       # That is the default.
L "0 1 2";   # Accept as legal the 3 values 0 1 and 2.
L "12-20";   # Accept as legal any value in the range from 12 to 20.
N jobname Set the jobName for all subsequent jobs. The jobName may contain any alphanumeric character, in addition to the space and characters from '-_:.=/'. It is an error to use illegal characters. The name is truncated to 256 characters. Examples: 
N "build"
N "simulation-2"
N "build_tree"

For all products, strict job name checking has been enabled and invalid job name characters will cause an error. For Accelerator and Accelerator Plus, this can be overridden by putting the following in $VOVDIR/local/vncrun.config.tcl: set ::jobname_lexicon legacy or set ::jobname_lexicon replace.

Legacy will use the more lax job naming rules from earlier releases.

Replace will identify invalid characters in the job name, replace them with "_", and issue a warning to the console.

N2 jobname Set the jobName for the most recently described job. This procedure performs no checks on the name, but this may change in the future. Examples: 
J vw cp aa bb
N2 "my_copy"
O [options] FILE FILE ... This is an output declaration. Its argument is a list of file names. Each file is declared as an output of the job created with the most recent J or T command. It is an error to call O without having called J or T first. Defining cyclic dependencies generates an error. All jobs must have at least one output to be consider valid.
Option
Description
-db name
Sets the database name of the output.
-sticky
Specify that the file is an output, even if it's not actually a true output at runtime. Also useful if it is truly an output, but is not instrumented or declared as an output at runtime.
-normal
This option undoes the other options.
-barrier
Output may have a barrier. The barrier, if it exists, is controlled by the job that generates this output.
-force
Force output declaration even with conflict.
-noforce
Fail on output conflict.
-share
The output is shared.
-md5
Output has an automatic barrier consisting of its MD5 sum.
-rcpc
Same as -md5
-ignore_timestamp
Specifies that the timestamp of the file should not be used to determine whether the job has succeeded or failed.
-quote
Use the output name as given, instead of mapping it to the corresponding logical canonical name.
P propertyName propertyValue Attach a property with the specified name and value to the most recently mentioned node. The type of the property is determined automatically from the value, i.e. the type is integer if the value is numeric. If P is called after T or J, the property is attached to the last job. If P is called right after an I or O declaration, the property is attached to the input or output file respectively. 
# Example:
J vw cp aa bb
P TEST "This property will be attached to the job"
I aa
P TEST "This property is attached to file aa"
O bb
P TEST "This property is attached to file bb"
PARALLEL script All of the tasks, jobs, and sets defined in the script are set up to be executed in parallel. Artificial dependencies are created between each task, job, or all the jobs in the set to build the graph in parallel. Can be nested in any order with sets, jobs, tasks, other SERIAL scripts, and other PARALLEL scripts. For examples see the TASK procedure.
PJ [OPTIONS] args Creates a periodic job using J (uses capsule if present). Periodic jobs run with a default period of $period, but will adjust future runs according to how long the job takes to complete. The range of the period is defined by $minperiod and $maxperiod. Examples: 
PJ -period 1h updateSomeFile
PJ -period 1h  -min 40m -max 2h -autokill 2m \
 -resources linux -env BASE updateSomeFile

E BASE
R linux
PJ -P 1m date

set make(jobname)   "$tag"
set make(nojournal) 1
PJ -P 30s -systemjob ftlm_parse_flexlm ...
Option
Description
-period TIMESPEC
Specify target period of job. This is the period with which the job is scheduled. If there are enough resources, it will also be the period with which the job is executed, else the job may have to be queued.
-min TIMESPEC
Allow period to be reduced down to this minimum period. This happens if the job is quick enough.
-max TIMESPEC
Allow period to be increased up to this maximum period. This happens if the job takes a long time to execute. The max period is also used to kill the job if it takes longer than max period.
-P TIMESPEC
Short cut specification of period, min period, max period, and autokill, where, with $P set to the TIMESPEC, min period is set to $P, max period is set to 10*$P and autokill is set to 3*$P.
-autokill TIMESPEC
Kill job if it runs for longer than the specified amount. If this is greater than the maximum period, then the job will be killed if it runs for more than the maximum period.
-resources RESOURCE_SPEC
Override resource specification for the job. By default, this is the empty list.
-env ENV_SPEC
Override environment specification for the job.
-cal CALENDAR_SPEC
Specify when the job is allowed to be executed. A CALENDAR_SPEC consists of two comma-separated lists joined by a colon. The part to the left of the colon expreses the days, and the part to the right specifies the hours, 0..23. Days are numbered 0..7 with 0 for Sunday. A CALENDAR_SPEC format example is: Sun,Mon,Tue:1,2,3,4 which states that the job can be executed on Sunday, Monday, and Tuesday, at the hours of 1AM, 2AM, 2AM 4AM. This option works in conjunction with the period settings describe above. Other CALENDAR_SPEC examples are:0,1,2:* - Sunday, Monday, and Tuesday, all hours.*:15,21 - All days, at 3pm and 9pm.
-systemjob
The job is considered "systemjob" (not keeping server up). If not declared as a systemjob, this job might prevent auto shutdown of an idle project, if the period of the PJ is shorter than the auto shutdown interval. Please note that the setting of make(systemjob) is not used to determine if the PJ is a system job or not. You must use this flag to declare this periodic job to be a system job.
PRIORITY spri xpri Set the priority to be used for subsequent jobs. The priority can be specified numerically ( from 1 to 15) or symbolically (low normal high top). The xpri argument is optional. If missing, it is set to spri. The value of priority for a job can easily be overwritten by a retrace request. Examples: 
PRIORITY 4 4 
PRIORITY normal
J vw cp aa bb
PRIORITY top normal
J vw cp aa bbx
R resourceList OPTIONAL_SCRIPT Sets the resources required by the following jobs, i.e. the R statement should precede T or J. Takes one or two parameters. The first parameter is a list of resource names. The second parameter, if present, is a Tcl script which is executed in the context of the caller of the R procedure. Side effect: sets the value of make(resources), except when the second (script) parameter is given. Examples: 
R "unix"
R "RAM#512"
R "sun5 dc_shell_license"
R "res1 res2 res3"
R "res1 res2" {
    J vw cp aa bb
} 
R {res1 res2} {puts "Resources = '$make(resources)'"}
R2 resourceList Similar to R, but this only applies to the most recently created job. That is, R goes before the T or the J, while R2 goes after the T or J. This procedure is used by the Vil-Tool VovResources when called with VOV_FDL_ONLY.

Takes one parameter, a resource expression. No side effects.

Examples: 
J vw cp aa bb
R2 "res1 res2"
S setname script args Collect all jobs created in the body of the procedure in the specified set. The S procedure can be nested. If the setname at one level begins with a '+' sign or if it has no colons (':'), the full name of the set is the concatenation of the name of the set at the previous level, separated with a colon ':'. If the name contains colons, it is considered to be a complete set name.
As of 2014.*, it is allowed for sets to contain other sets. Because of this, nested S procedures now attach the subset to the superset.
Note: Job I/O nodes are not placed in the set.
Synopsis:
S set_namebody
Example:
S "MySet" {
    J vw cp aa bb
    J vw cp bb cc
}

S "ThisIsAnEmptySet" {}

S "lev1" {
   S "lev2a" {
      ### Jobs here are attached to the set "lev1:lev2a"
      ### The set "lev1:lev2a" is also attached to set "lev1"
   }
   S "lev2b" {
      ### Jobs here are attached to the set "lev1:lev2b"
      ### The set "lev1:lev2b" is also attached to set "lev1".
   }
} -gui_label "Add a label to the set lev1"
S+ setname script Append all jobs created in the body of the procedure to the specified set.
Note:
  • If the specified set does not exist, the set is created.
  • Job I/O nodes are not placed in the set.
  • Must use fully qualified set name when appending to a nested set.
Synopsis:
S+ set_namebody
Example:
S "MySet" {
    J vw cp aa bb
}
S+ "MySet" {
    J vw cp bb cc
}
## MySet now has two jobs attached to it. "J vw cp aa bb" and
## "J vw cp bb cc"

### This does not change MySet (contrast with procedure
### 'S' above which makes the set empty)
S+ "MySet" {};

### Appending jobs to a set that does not exist causes the set to 
###    exist, with the added jobs attached to it.
S+ "MyNewSet" {
    J vw cp cc dd
}

S "a-lev1" {
   S "a-lev2" {
      S "a-lev3" {
         J vw cp aa bb
      }
   }
}
### Intention is now to append a job within the nested "a-lev3"
### Correctly using fully qualified set name
S+ "a-lev1:a-lev2:a-lev3" {
    J vw cp bb cc
}

### Intention is now to append another job within "a-lev3"
### Incorrectly using simple set name
S+ "a-lev3" {
    J vw cp cc dd
}
### Result is the creation of a new un-nested outer-level set
### ("a-lev3") with one job attached.

### Use the fully qualified name even if the append request is inside
### the nested scope.
S "b-lev1" {
   S "b-lev2" {
      S "b-lev3" {
         J vw cp aa bb
      }
      S+ "b-lev1:b-lev2:b-lev3" {  ### Correctly naming specified set 
         J vw cp bb cc
      }
   }
}
### Result is two jobs attached to the nested set having the name
### "b-lev1:b-lev2:b-lev3"
SERIAL script All of the tasks, jobs, and sets defined in the script are set up to be executed serially in the order they appear. Artificial dependencies are created between each task, job, or all the jobs in the set to build the graph serially. Can be nested in any order with sets, jobs, tasks, other SERIAL scripts, and other PARALLEL scripts. For examples see the TASK procedure.
shift <none> Get the next argument from argv. Example: 
while { $argv != {} } {
    set arg [shift]
    switch -glob -- $arg {
        "-h"   { help } 
        "-title" {
            set title [shift]
        }
        default {
            VovError "Unknown argument '$arg'"
        }
    }
}
START list-of-ids Starts a retrace in SAFE mode with NORMAL priority for each object-ID passed in. Ids may be of PLACE, TRANSITION, NODE or NODESET. Ignores invalid object types with a message. It is a fatal error to pass in an invalid vovID.
Synopsis:
START id1 [id2 .. idN]
Example: 
set jid [J vw cp aa bb]
START $jid
STOP list-of-ids Calls vtk_job_control $id STOP for each object-ID passed in. Ids may be of PLACE, TRANSITION, NODE or NODESET. Ignores invalid object types with a message. It is a fatal error to pass in an invalid vovID.
Note: Does not stop jobs in a NODESET, but only produces a message.
Synopsis:
STOP id1 [id2 .. idN]
Example:
set rjobs vtk_set_get_elements [vtk_set_find System:transitionsRunningRetracing] @ID@
STOP $rjobs
T args Mnemonic for 'Tool'

Declares a job where the associated capsule (if it exists) is NOT used at build time. This procedure is identical to J, except that J does search for corresponding capsule. The arguments form the command line for a new job to be added to the trace. Environment and working directory for the job are taken from the current settings. If an identical job already exists in the trace, nothing happens. The procedure returns the VovId of the job. The status of a newly created job is always INVALID.

If the procedure is passed multiple arguments, each argument is quoted if necessary. If the procedure is passed a single list, all elements in the list are "join'ed" together with spaces.

Examples:
set list { aa bb }
T vw cp aa bb;                 # Many arguments
T "vw cp $list";               # One argument
T vw vdc_shell -f adder.dcsh
T vw cat xx.v yy.v zz.v > bigfile.v
T vw echo "ciao bello"
T_FINAL <none> T_FINAL indicates that the inputs and outputs declared through I and O commands associated with the last T declaration are the only inputs and outputs for that T. Any inputs and outputs that were associated with this T from a previous vovbuild but not declared again in this vovbuild will be removed.
TASK args TASK declares a task. This is a wrapper for the procedure T. Its main purpose is to be used with SERIAL and PARALLEL to build simple, intuitive flows.
Examples:
SERIAL {
  TASK make clean
  TASK configure
  TASK make
  TASK make install
}

SERIAL {
  S Run_Three_A_In_Parallel {
    PARALLEL { 
      T vw scriptA1.csh
      T vw scriptA2.csh
      T vw scriptA3.csh
    }
  }
  S Run_Three_B_In_Parallel {
    PARALLEL { 
      T vw scriptB1.csh
      T vw scriptB2.csh
      T vw scriptB3.csh
    }
  }
}

PARALLEL {
  SERIAL {
    TASK date 1920
    TASK date 1921
    TASK date 1922
  }
  PARALLEL {
    SERIAL { 
      TASK date 1923
      TASK date 1924
      TASK date 1925
    }
    SERIAL { 
      TASK date 1926
      TASK date 1927
      TASK date 1928
    }
  }
}
X xdur Set the expected duration for subsequent jobs. It takes one argument, which is a Time Specifications. Examples:
X 120; # Expected duration is 120 seconds.
X 2m ;   
X 3h10m;
Z FILE FILE ... Set the 'zippable' flag in all the mentioned files. The file must be a place in the trace belonging to the database 'FILE'. A file that has the zippable flag will be automatically compressed and decompressed as required by the flow. If all jobs that use the file have been completed successfully, the file will be compressed. If a job that needs the file is scheduled to run, the file will be decompressed.