Include files are used where same piece of code can be inserted into multiple files. This allows all files using that include file to be easily changed. A group of files may have their own include file; e.g. all the tasks in an archiving family, could include one common file for the variable definitions needed. This makes the maintenance of the tasks much easier.
In the same way as the C-pre-processor, ecFlow include files do nest. There is no limit within ecFlow on how many times they nest beyond system limitations.
In the simplest case an ecFlow file would have at least two include statements. One include at the beginning and one at the end of the file. An example is given below. There are two extra lines apart from the lines needed for the task itself. This helps to understand the script since only lines needed for this task are visible. The extra ecFlow code is not visible.
Example of using include statements in ecFlow file:
%include <head.h> do the steps for the task %include <end.h>
When ecFlow needs to read an include-file it tries to locate them from the directory pointed to by variable ECF_INCLUDE (unless full path name was given.) Typically this variable is set in the suite definition file at the same time as ECF_FILES.
The start of the definition for a suite will normally be something like:
suite my_suite edit ECF_FILES /home/ma/map/def/$SUITE/ECFfiles edit ECF_INCLUDE /home/ma/map/def/$SUITE/include edit ECF_HOME /tmp/map/ECF ...
You need to declare the ECF-variables needed. In the start of an ecFlow script you need to make sure that any command failing will be trapped and calls:
ecflow_client--abort="<Reason>"
You also need to tell ecFlow that the task is active by using:
ecflow_client - -init <process id>
In a large suite, with hundreds of tasks, you would need to execute the same commands in each of them. Editing just a single (header) file is somewhat easier than editing them all.
E.g. file head.h
#!/bin/ksh
ECF_NAME=%ECF_NAME%
ECF_NODE=%ECF_NODE%
ECF_PASS=%ECF_PASS%
ECF_PORT=%ECF_PORT%
ECF_TRYNO=%ECF_TRYNO%
ECF_RID=$$
export ECF_NAME ECF_NODE ECF_PASS ECF_TRYNO ECF_PORT ECF_RID
ERROR() { echo ERROR ; ecflow_client --abort=trap; exit 1 ; }
trap ERROR 0
trap '{ echo "Killed by a signal"; ERROR ; }' 1 2 3 4 5 6 7 8 10 12 13 15 # list using kill -l or man kill
set -e
ecflow_client --init=$$
The same applies to the end of the task. You want to tell the ecFlow that the task is complete by using ecflow_client --complete(CLI) and un-trap the shell.
e.g. file tail.h
ecflow_client --complete
trap 0
exit
Generally you would have more than just a single include file at the beginning of an ecFlow file, e.g. one to have common options for your queuing system, then a few lines for the queuing options unique to that job. There may be an include file to specify options for an experimental suite, and so on. There are around ten different include files used in the ECMWF operational suite.