mirror of https://github.com/BOINC/boinc.git
Update XmlFormat.md file
Signed-off-by: Vitalii Koshura <lestat.de.lionkur@gmail.com>
Vitalii Koshura
parent
db7b887d7f
commit
25c3dd9237
194
XmlFormat.md
194
XmlFormat.md
|
|
@ -1,3 +1,5 @@
|
|||
# XML formats
|
||||
|
||||
BOINC uses XML to describe various entities. These XML elements appear in:
|
||||
|
||||
* Workunit and result templates
|
||||
|
|
@ -6,115 +8,115 @@ BOINC uses XML to describe various entities. These XML elements appear in:
|
|||
* The client state file
|
||||
* GUI RPCs
|
||||
|
||||
Generally, these XML elements are generated by BOINC. Some of these XML elements are described here (not all fields are present in all contexts).
|
||||
Generally, these XML elements are generated by BOINC. Some of these XML elements are described here (not all fields are present in all contexts).
|
||||
|
||||
# Files #file_info
|
||||
# Files
|
||||
|
||||
A [file](BoincFiles) is described by an element of the form:
|
||||
|
||||
|
||||
<file_info>
|
||||
<name>foobar</name> *
|
||||
<url>http://a.b.c/foobar</url>
|
||||
<url>http://x.y.z/foobar</url>
|
||||
...
|
||||
<md5_cksum>123123123123</md5_cksum>
|
||||
<nbytes>134423</nbytes>
|
||||
<max_nbytes>200000</max_nbytes> *
|
||||
<status>1</status>
|
||||
[ <generated_locally/> ]
|
||||
[ <executable/> ]
|
||||
[ <upload_when_present/> ]
|
||||
[ <sticky/> * ]
|
||||
[ <signature_required/> ]
|
||||
[ <no_delete/> * ]
|
||||
[ <report_on_rpc/> * ]
|
||||
[ <gzip_when_done/> * ]
|
||||
</file_info>
|
||||
|
||||
```
|
||||
<file_info>
|
||||
<name>foobar</name> *
|
||||
<url>http://a.b.c/foobar</url>
|
||||
<url>http://x.y.z/foobar</url>
|
||||
...
|
||||
<md5_cksum>123123123123</md5_cksum>
|
||||
<nbytes>134423</nbytes>
|
||||
<max_nbytes>200000</max_nbytes> *
|
||||
<status>1</status>
|
||||
[ <generated_locally/> ]
|
||||
[ <executable/> ]
|
||||
[ <upload_when_present/> ]
|
||||
[ <sticky/> * ]
|
||||
[ <signature_required/> ]
|
||||
[ <no_delete/> * ]
|
||||
[ <report_on_rpc/> * ]
|
||||
[ <gzip_when_done/> * ]
|
||||
</file_info>
|
||||
```
|
||||
|
||||
The elements marked with an asterisk are specified by the project; the others are generated automatically by BOINC. The elements are as follows:
|
||||
|
||||
name::
|
||||
The file's name, which must be unique within the project. If you want to use participant hosts on which filenames are case-insensitive (e.g. Windows) this uniqueness is case-insensitive.
|
||||
url::
|
||||
a URL where the file is (or will be) located on a data server.
|
||||
md5_cksum::
|
||||
The MD5 checksum of the file.
|
||||
nbytes::
|
||||
the size of the file in bytes.
|
||||
max_nbytes::
|
||||
For output files, the maximum allowable size of the file in bytes (as a double; may be greater than 2^32^). This is used to prevent flooding data servers with bogus data.
|
||||
status::
|
||||
On the client: 0 if the file is not present; 1 if the file is present; a negative error code if there was a problem in downloading or generating the file.
|
||||
generated_locally::
|
||||
If present, indicates that the file will be generated on the client, rather than downloaded.
|
||||
executable::
|
||||
If present, indicates that the file protections should be set to allow execution.
|
||||
upload_when_present::
|
||||
If present, indicates that the file should be uploaded when the application finishes. The file is uploaded even if the application doesn't finish successfully. API functions are available for [uploading files prior to finishing computation](IntermediateUpload).
|
||||
sticky::
|
||||
If present, indicates that the file should be retained on the client after its initial use.
|
||||
signature_required::
|
||||
If present, indicates that the file should be verified with an RSA signature. This generally only applies to executable files.
|
||||
no_delete::
|
||||
If present for an input (workunit) file, indicates that the file should not be removed from the data server's download directory when the workunit is completed. Use this if a file is used by more than one workunit, or will be used by future workunits.
|
||||
|
||||
If present for an output (result) file, indicates that the file should not be removed from the data server's upload directory, even when the corresponding workunit is completed and assimilated. Use with caution - this may cause your upload directory to overflow.
|
||||
report_on_rpc::
|
||||
Include a description of this file in scheduler RPC requests, so that the scheduler may send appropriate work using [locality scheduling](LocalityScheduling).
|
||||
gzip_when_done::
|
||||
Used for output files only. When the file is complete, the core client compresses it using gzip. Note: the file name does not change (i.e. '.gz' is not appended).
|
||||
### name
|
||||
The file's name, which must be unique within the project. If you want to use participant hosts on which filenames are case-insensitive (e.g. Windows) this uniqueness is case-insensitive.
|
||||
### url
|
||||
a URL where the file is (or will be) located on a data server.
|
||||
### md5_cksum
|
||||
The MD5 checksum of the file.
|
||||
### nbytes
|
||||
the size of the file in bytes.
|
||||
### max_nbytes
|
||||
For output files, the maximum allowable size of the file in bytes (as a double; may be greater than 2^32^). This is used to prevent flooding data servers with bogus data.
|
||||
### status
|
||||
On the client: 0 if the file is not present; 1 if the file is present; a negative error code if there was a problem in downloading or generating the file.
|
||||
### generated_locally
|
||||
If present, indicates that the file will be generated on the client, rather than downloaded.
|
||||
### executable
|
||||
If present, indicates that the file protections should be set to allow execution.
|
||||
### upload_when_present
|
||||
If present, indicates that the file should be uploaded when the application finishes. The file is uploaded even if the application doesn't finish successfully. API functions are available for [uploading files prior to finishing computation](IntermediateUpload).
|
||||
### sticky
|
||||
If present, indicates that the file should be retained on the client after its initial use.
|
||||
### signature_required
|
||||
If present, indicates that the file should be verified with an RSA signature. This generally only applies to executable files.
|
||||
### no_delete
|
||||
If present for an input (workunit) file, indicates that the file should not be removed from the data server's download directory when the workunit is completed. Use this if a file is used by more than one workunit, or will be used by future workunits.
|
||||
|
||||
# File references #file_ref
|
||||
If present for an output (result) file, indicates that the file should not be removed from the data server's upload directory, even when the corresponding workunit is completed and assimilated. Use with caution - this may cause your upload directory to overflow.
|
||||
### report_on_rpc
|
||||
Include a description of this file in scheduler RPC requests, so that the scheduler may send appropriate work using [locality scheduling](LocalityScheduling).
|
||||
### gzip_when_done
|
||||
Used for output files only. When the file is complete, the core client compresses it using gzip. Note: the file name does not change (i.e. '.gz' is not appended).
|
||||
|
||||
# File references
|
||||
|
||||
Files may be associated with [workunits, results](JobIn) or [application versions](AppVersion).
|
||||
Each such association is represented by an XML element of the form:
|
||||
|
||||
|
||||
<file_ref>
|
||||
<file_name>foobar</file_name>
|
||||
[ <open_name>input</open_name> ]
|
||||
[ <main_program/> ]
|
||||
[ <copy_file/> ]
|
||||
[ <optional/> ]
|
||||
</file_ref>
|
||||
|
||||
```
|
||||
<file_ref>
|
||||
<file_name>foobar</file_name>
|
||||
[ <open_name>input</open_name> ]
|
||||
[ <main_program/> ]
|
||||
[ <copy_file/> ]
|
||||
[ <optional/> ]
|
||||
</file_ref>
|
||||
```
|
||||
|
||||
file_name::
|
||||
Specifies a file.
|
||||
open_name::
|
||||
The name by which the application will refer to the file. Applications access files using [the following functions](BasicApi):
|
||||
|
||||
char physical_name[256];
|
||||
boinc_resolve_filename("input", physical_name, 256);
|
||||
fp = boinc_fopen(physical_name, "r")
|
||||
|
||||
In this example, `open_name` is 'input'. It is mapped, at runtime, to a path that includes the filename ('foobar' in the example above).
|
||||
main_program::
|
||||
Relevant only for files associated with application versions. It indicates that this file is the application's main program.
|
||||
copy_file::
|
||||
Use this if your application doesn't use `boinc_resolve_filename()` to make logical to physical filenames (for example, executables without source code). If present on an input file, BOINC will copy the file to the slot directory before starting the application. If present on an output file, BOINC will move the file from the slot directory to the project directory after the application has finished.
|
||||
optional::
|
||||
Use this for output files that may not be created by the application. Otherwise, missing output files are treated as an error.
|
||||
### file_name
|
||||
Specifies a file.
|
||||
### open_name
|
||||
The name by which the application will refer to the file. Applications access files using [the following functions](BasicApi):
|
||||
```
|
||||
char physical_name[256];
|
||||
boinc_resolve_filename("input", physical_name, 256);
|
||||
fp = boinc_fopen(physical_name, "r")
|
||||
```
|
||||
In this example, `open_name` is 'input'. It is mapped, at runtime, to a path that includes the filename ('foobar' in the example above).
|
||||
### main_program
|
||||
Relevant only for files associated with application versions. It indicates that this file is the application's main program.
|
||||
### copy_file
|
||||
Use this if your application doesn't use `boinc_resolve_filename()` to make logical to physical filenames (for example, executables without source code). If present on an input file, BOINC will copy the file to the slot directory before starting the application. If present on an output file, BOINC will move the file from the slot directory to the project directory after the application has finished.
|
||||
### optional
|
||||
Use this for output files that may not be created by the application. Otherwise, missing output files are treated as an error.
|
||||
|
||||
|
||||
# App versions #app_version
|
||||
# App versions
|
||||
Each entry in the `app_version` table includes an XML document describing the files that make up the application version:
|
||||
|
||||
<file_info>
|
||||
...
|
||||
</file_info>
|
||||
[ ... ]
|
||||
<app_version>
|
||||
<app_name>foobar</app_name>
|
||||
<version_num>4</version_num>
|
||||
<file_ref>
|
||||
<file_name>program_1</file_name>
|
||||
<main_program/>
|
||||
</file_ref>
|
||||
<file_ref>
|
||||
<file_name>library_12</file_name>
|
||||
</file_ref>
|
||||
</app_version>
|
||||
|
||||
```
|
||||
<file_info>
|
||||
...
|
||||
</file_info>
|
||||
[ ... ]
|
||||
<app_version>
|
||||
<app_name>foobar</app_name>
|
||||
<version_num>4</version_num>
|
||||
<file_ref>
|
||||
<file_name>program_1</file_name>
|
||||
<main_program/>
|
||||
</file_ref>
|
||||
<file_ref>
|
||||
<file_name>library_12</file_name>
|
||||
</file_ref>
|
||||
</app_version>
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue