Work Unit or Result Template

From Unofficial BOINC Wiki

[edit] Work Unit and Result Template Files

A Work Unit Template File has the form:

<file_info>
    <number>0</number>
    [ <sticky/>, other attributes]
</file_info>
[ ... ]
<workunit>
    <file_ref>
        <file_number>0</file_number>
        <open_name>NAME</open_name>
    </file_ref>
    [ ... ]
    [ <command_line>-flags xyz</command_line> ]
    [ <rsc_fpops_est>x</rsc_fpops_est> ]
    [ <rsc_fpops_bound>x</rsc_fpops_bound> ]
    [ <rsc_memory_bound>x</rsc_memory_bounds> ]
    [ <rsc_disk_bound>x</rsc_disk_bounds> ]
    [ <delay_bound>x</delay_bound> ]
    [ <min_quorum>x</min_quorum> ]
    [ <target_nresults>x</target_nresults> ]
    [ <max_error_results>x</max_error_results> ]
    [ <max_total_results>x</max_total_results> ]
    [ <max_success_results>x</max_success_results> ]
</workunit>

The components are:

When a workunit is created, the template file is processed as follows:

• Within a <file_info> element, <number>x</number> identifies the order of the file. It is replaced with elements giving the filename, download URL, MD5 checksum, and size.
• Within a <file_ref> element, <file_number>x</file_number> is replaced with an element giving the filename.

A Result Template File has the form:

<file_info>
    <name><OUTFILE_0/></name>
    <generated_locally/>
    <upload_when_present/>
    <max_nbytes>32768</max_nbytes>
    <url><UPLOAD_URL/></url>
</file_info>
<result>
    <file_ref>
        <file_name><OUTFILE_0/></file_name>
        <open_name>result.sah</open_name>
    </file_ref>
</result>

The result file template is macro-substituted as follows:

• <OUTFILE_n> is replaced with a string of the form 'wuname_resultnum_n' where wuname is the workunit name and resultnum is the ordinal number of the result (0, 1, ...).
• <UPLOAD_URL/> is replaced with the upload URL.

[edit] Moving input files to the download directory

If you're a flat download directory, just put input files in that directory. If you're using Hierarchical Upload/Download Directories, you must put each input file in the appropriate directory; the directory is determined by the file's name. To find this directory, call the C++ function

dir_hier_path(
    const char* filename,
    const char* root,       // root of download directory
    int fanout,             // from config.xml
    bool new_hash,          // use true here
    char* result            // path of file in hierarchy
);

If you're using scripts, you can invoke the program

dir_hier_path filename

It prints the full pathname. Run this in the project's root directory. For example:

cp test_workunits/12ja04aa `bin/dir_hier_path 12ja04aa`

copies an input file from the test_workunits directory to the download directory hierarchy. Creating Work Unit Records

Work Units can be created using either a script (using the create_work program) or a program (using the create_work() function). The input files must already be in the download directory.

The utility program is

create_work
    -appname name                       // application name
    -wu_name name                       // workunit name
    -wu_template filename               // WU template filename
                                        // relative to project root
    -result_template filename           // result template filename
                                        // relative to project root
    [ -batch n ]
    [ -priority n ]

    // The following are normally supplied in the WU template:
    [ -rsc_fpops_est x ]
    [ -rsc_fpops_bound x ]
    [ -rsc_memory_bound x ]
    [ -rsc_disk_bound x ]
    [ -delay_bound x ]
    [ -min_quorum x ]
    [ -target_nresults x ]
    [ -max_error_results x ]
    [ -max_total_results x ]
    [ -max_success_results x ]

    infile_1 ... infile_m           // input files

See the Work Unit Attributes for details about the parameters. The program must be run in the project root directory.

The C++ library (crypt.C, backend_lib.C,h) provides the functions:

int read_key_file(char* path, R_RSA_PRIVATE_KEY& key);

int create_work(
    DB_WORKUNIT&,
    const char* wu_template,                  // contents, not path
    const char* result_template_filename,     // relative to project root
    const char* result_template_filepath,    // absolute,
        // or relative to current dir
    const char* infile_dir,                   // where input files are
    const char** infiles,                     // array of input file names
    int ninfiles
    R_RSA_PRIVATE_KEY& key,             // upload authentication key
    SCHED_CONFIG&
);

The read_key_file() function reads a private key from a file. Use this to read the file upload authentication key.

The create_work() function creates a Work Unit and one or more Results. The arguments are similar to those of the utility program; some of the information is passed in the WORKUNIT structure, namely the following fields:

name appid batch rsc_fpops rsc_iops rsc_memory rsc_disk delay_bound

All other fields should be zeroed.