.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::AnalysisI 3pm"
.TH Bio::AnalysisI 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::AnalysisI \- An interface to any (local or remote) analysis tool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
This is an interface module \- you do not instantiate it.
Use \f(CW\*(C`Bio::Tools::Run::Analysis\*(C'\fR module:
.PP
.Vb 2
\& use Bio::Tools::Run::Analysis;
\& my $tool = Bio::Tools::Run::Analysis\->new(@args);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This interface contains all public methods for accessing and
controlling local and remote analysis tools. It is meant to be used on
the client side.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list. Your participation is much appreciated.
.PP
.Vb 2
\& bioperl\-l@bioperl.org \- General discussion
\& http://bioperl.org/wiki/Mailing_lists \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and
reponsive experts will be able look at the problem and quickly
address it. Please include a thorough description of the problem
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via the
web:
.PP
.Vb 1
\& https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Martin Senger (martin.senger@gmail.com)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2003, Martin Senger and EMBL-EBI.
All Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
This software is provided \*(L"as is\*(R" without warranty of any kind.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
http://www.ebi.ac.uk/Tools/webservices/soaplab/guide
.SH "APPENDIX"
.IX Header "APPENDIX"
This is actually the main documentation...
.PP
If you try to call any of these methods directly on this
\&\f(CW\*(C`Bio::AnalysisI\*(C'\fR object you will get a \fInot implemented\fR error
message. You need to call them on a \f(CW\*(C`Bio::Tools::Run::Analysis\*(C'\fR object instead.
.SS "analysis_name"
.IX Subsection "analysis_name"
.Vb 3
\& Usage : $tool\->analysis_name;
\& Returns : a name of this analysis
\& Args : none
.Ve
.SS "analysis_spec"
.IX Subsection "analysis_spec"
.Vb 3
\& Usage : $tool\->analysis_spec;
\& Returns : a hash reference describing this analysis
\& Args : none
.Ve
.PP
The returned hash reference uses the following keys (not all of them always
present, perhaps others present as well): \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`type\*(C'\fR, \f(CW\*(C`version\*(C'\fR,
\&\f(CW\*(C`supplier\*(C'\fR, \f(CW\*(C`installation\*(C'\fR, \f(CW\*(C`description\*(C'\fR.
.PP
Here is an example output:
.PP
.Vb 7
\& Analysis \*(Aqedit.seqret\*(Aq:
\& installation => EMBL\-EBI
\& description => Reads and writes (returns) sequences
\& supplier => EMBOSS
\& version => 2.6.0
\& type => edit
\& name => seqret
.Ve
.SS "describe"
.IX Subsection "describe"
.Vb 3
\& Usage : $tool\->analysis_spec;
\& Returns : an XML detailed description of this analysis
\& Args : none
.Ve
.PP
The returned \s-1XML\s0 string contains metadata describing this analysis
service. It includes also metadata returned (and easier used) by
method \f(CW\*(C`analysis_spec\*(C'\fR, \f(CW\*(C`input_spec\*(C'\fR and \f(CW\*(C`result_spec\*(C'\fR.
.PP
The \s-1DTD\s0 used for returned metadata is based on the adopted standard
(\s-1BSA\s0 specification for analysis engine):
.PP
.Vb 1
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
.Ve
.PP
But the \s-1DTD\s0 may be extended by provider-specific metadata. For
example, the \s-1EBI\s0 experimental SOAP-based service on top of \s-1EMBOSS\s0 uses
\&\s-1DTD\s0 explained at \f(CW\*(C`http://www.ebi.ac.uk/~senger/applab\*(C'\fR.
.SS "input_spec"
.IX Subsection "input_spec"
.Vb 3
\& Usage : $tool\->input_spec;
\& Returns : an array reference with hashes as elements
\& Args : none
.Ve
.PP
The analysis input data are named, and can be also associated with a
default value, with allowed values and with few other attributes. The
names are important for feeding the service with the input data (the
inputs are given to methods \f(CW\*(C`create_job\*(C'\fR, \f(CW\*(C`Bio::AnalysisI|run\*(C'\fR, and/or
\&\f(CW\*(C`Bio::AnalysisI|wait_for\*(C'\fR as name/value pairs).
.PP
Here is a (slightly shortened) example of an input specification:
.PP
.Vb 10
\& $input_spec = [
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsequence_usa\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsequence_direct_data\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqallowed_values\*(Aq => [
\& \*(Aqgcg\*(Aq,
\& \*(Aqgcg8\*(Aq,
\& ...
\& \*(Aqraw\*(Aq
\& ],
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsformat\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsbegin\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsend\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsprotein\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsnucleotide\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsreverse\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqslower\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqsupper\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqdefault\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqfirstonly\*(Aq
\& },
\& {
\& \*(Aqmandatory\*(Aq => \*(Aqfalse\*(Aq,
\& \*(Aqdefault\*(Aq => \*(Aqfasta\*(Aq,
\& \*(Aqallowed_values\*(Aq => [
\& \*(Aqgcg\*(Aq,
\& \*(Aqgcg8\*(Aq,
\& \*(Aqembl\*(Aq,
\& ...
\& \*(Aqraw\*(Aq
\& ],
\& \*(Aqtype\*(Aq => \*(AqString\*(Aq,
\& \*(Aqname\*(Aq => \*(Aqosformat\*(Aq
\& }
\& ];
.Ve
.SS "result_spec"
.IX Subsection "result_spec"
.Vb 4
\& Usage : $tool\->result_spec;
\& Returns : a hash reference with result names as keys
\& and result types as values
\& Args : none
.Ve
.PP
The analysis results are named and can be retrieved using their names
by methods \f(CW\*(C`results\*(C'\fR and \f(CW\*(C`result\*(C'\fR.
.PP
Here is an example of the result specification (again for the service
\&\fIedit.seqret\fR):
.PP
.Vb 5
\& $result_spec = {
\& \*(Aqoutseq\*(Aq => \*(AqString\*(Aq,
\& \*(Aqreport\*(Aq => \*(AqString\*(Aq,
\& \*(Aqdetailed_status\*(Aq => \*(AqString\*(Aq
\& };
.Ve
.SS "create_job"
.IX Subsection "create_job"
.Vb 4
\& Usage : $tool\->create_job ( {\*(Aqsequence\*(Aq=>\*(Aqtatat\*(Aq} )
\& Returns : Bio::Tools::Run::Analysis::Job
\& Args : data and parameters for this execution
\& (in various formats)
.Ve
.PP
Create an object representing a single execution of this analysis
tool.
.PP
Call this method if you wish to \*(L"stage the scene\*(R" \- to create a job
with all input data but without actually running it. This method is
called automatically from other methods (\f(CW\*(C`Bio::AnalysisI|run\*(C'\fR and
\&\f(CW\*(C`Bio::AnalysisI|wait_for\*(C'\fR) so usually you do not need to call it directly.
.PP
The input data and prameters for this execution can be specified in
various ways:
.IP "array reference" 4
.IX Item "array reference"
The array has scalar elements of the form
.Sp
.Vb 1
\& name = [[@]value]
.Ve
.Sp
where \f(CW\*(C`name\*(C'\fR is the name of an input data or input parameter (see
method \f(CW\*(C`input_spec\*(C'\fR for finding what names are recognized by this
analysis) and \f(CW\*(C`value\*(C'\fR is a value for this data/parameter. If \f(CW\*(C`value\*(C'\fR
is missing a 1 is assumed (which is convenient for the boolean
options). If \f(CW\*(C`value\*(C'\fR starts with \f(CW\*(C`@\*(C'\fR it is treated as a local
filename, and its contents is used as the data/parameter value.
.IP "hash reference" 4
.IX Item "hash reference"
The same as with the array reference but now there is no need to use
an equal sign. The hash keys are input names and hash values their
data. The values can again start with a \f(CW\*(C`@\*(C'\fR sign indicating a local
filename.
.IP "scalar" 4
.IX Item "scalar"
In this case, the parameter represents a job \s-1ID\s0 obtained in some
previous invocation \- such job already exists on the server side, and
we are just re-creating it here using the same job \s-1ID.\s0
.Sp
\&\fI\s-1TBD:\s0 here we should allow the same by using a reference to the
Bio::Tools::Run::Analysis::Job object.\fR
.IP "undef" 4
.IX Item "undef"
Finally, if the parameter is undefined, ask server to create an empty
job. The input data may be added later using \f(CW\*(C`set_data...\*(C'\fR
method(s) \- see scripts/papplmaker.PLS for details.
.SS "run"
.IX Subsection "run"
.Vb 4
\& Usage : $tool\->run ( [\*(Aqsequence=@my.seq\*(Aq, \*(Aqosformat=embl\*(Aq] )
\& Returns : Bio::Tools::Run::Analysis::Job,
\& representing started job (an execution)
\& Args : the same as for create_job
.Ve
.PP
Create a job and start it, but do not wait for its completion.
.SS "wait_for"
.IX Subsection "wait_for"
.Vb 4
\& Usage : $tool\->wait_for ( { \*(Aqsequence\*(Aq => \*(Aq@my,file\*(Aq } )
\& Returns : Bio::Tools::Run::Analysis::Job,
\& representing finished job
\& Args : the same as for create_job
.Ve
.PP
Create a job, start it and wait for its completion.
.PP
Note that this is a blocking method. It returns only after the
executed job finishes, either normally or by an error.
.PP
Usually, after this call, you ask for results of the finished job:
.PP
.Vb 1
\& $analysis\->wait_for (...)\->results;
.Ve
.SH "Module Bio::AnalysisI::JobI"
.IX Header "Module Bio::AnalysisI::JobI"
An interface to the public methods provided by \f(CW\*(C`Bio::Tools::Run::Analysis::Job\*(C'\fR
objects.
.PP
The \f(CW\*(C`Bio::Tools::Run::Analysis::Job\*(C'\fR objects represent a created,
running, or finished execution of an analysis tool.
.PP
The factory for these objects is module \f(CW\*(C`Bio::Tools::Run::Analysis\*(C'\fR
where the following methods return an
\&\f(CW\*(C`Bio::Tools::Run::Analysis::Job\*(C'\fR object:
.PP
.Vb 3
\& create_job (returning a prepared job)
\& run (returning a running job)
\& wait_for (returning a finished job)
.Ve
.SS "id"
.IX Subsection "id"
.Vb 3
\& Usage : $job\->id;
\& Returns : this job ID
\& Args : none
.Ve
.PP
Each job (an execution) is identifiable by this unique \s-1ID\s0 which can be
used later to re-create the same job (in other words: to re-connect to
the same job). It is useful in cases when a job takes long time to
finish and your client program does not want to wait for it within the
same session.
.SS "Bio::AnalysisI::JobI::run"
.IX Subsection "Bio::AnalysisI::JobI::run"
.Vb 3
\& Usage : $job\->run
\& Returns : itself
\& Args : none
.Ve
.PP
It starts previously created job. The job already must have all input
data filled-in. This differs from the method of the same name of the
\&\f(CW\*(C`Bio::Tools::Run::Analysis\*(C'\fR object where the \f(CW\*(C`Bio::AnalysisI::JobI::run\*(C'\fR method
creates also a new job allowing to set input data.
.SS "Bio::AnalysisI::JobI::wait_for"
.IX Subsection "Bio::AnalysisI::JobI::wait_for"
.Vb 3
\& Usage : $job\->wait_for
\& Returns : itself
\& Args : none
.Ve
.PP
It waits until a previously started execution of this job finishes.
.SS "terminate"
.IX Subsection "terminate"
.Vb 3
\& Usage : $job\->terminate
\& Returns : itself
\& Args : none
.Ve
.PP
Stop the currently running job (represented by this object). This is a
definitive stop, there is no way to resume it later.
.SS "last_event"
.IX Subsection "last_event"
.Vb 3
\& Usage : $job\->last_event
\& Returns : an XML string
\& Args : none
.Ve
.PP
It returns a short \s-1XML\s0 document showing what happened last with this
job. This is the used \s-1DTD:\s0
.PP
.Vb 2
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
\&
.Ve
.PP
Here is an example what is returned after a job was created and
started, but before it finishes (note that the example uses an
analysis 'showdb' which does not need any input data):
.PP
.Vb 4
\& use Bio::Tools::Run::Analysis;
\& print new Bio::Tools::Run::Analysis (\-name => \*(Aqdisplay.showdb\*(Aq)
\& \->run
\& \->last_event;
.Ve
.PP
It prints:
.PP
.Vb 5
\&
\&
\& Mar 3, 2003 5:14:46 PM (Europe/London)
\&
\&
.Ve
.PP
The same example but now after it finishes:
.PP
.Vb 4
\& use Bio::Tools::Run::Analysis;
\& print new Bio::Tools::Run::Analysis (\-name => \*(Aqdisplay.showdb\*(Aq)
\& \->wait_for
\& \->last_event;
\&
\&
\&
\& Mar 3, 2003 5:17:14 PM (Europe/London)
\&
\&
.Ve
.SS "status"
.IX Subsection "status"
.Vb 3
\& Usage : $job\->status
\& Returns : string describing the job status
\& Args : none
.Ve
.PP
It returns one of the following strings (and perhaps more if a server
implementation extended possible job states):
.PP
.Vb 5
\& CREATED
\& RUNNING
\& COMPLETED
\& TERMINATED_BY_REQUEST
\& TERMINATED_BY_ERROR
.Ve
.SS "created"
.IX Subsection "created"
.Vb 3
\& Usage : $job\->created (1)
\& Returns : time when this job was created
\& Args : optional
.Ve
.PP
Without any argument it returns a time of creation of this job in
seconds, counting from the beginning of the \s-1UNIX\s0 epoch
(1.1.1970). With a true argument it returns a formatted time, using
rules described in \f(CW\*(C`Bio::Tools::Run::Analysis::Utils::format_time\*(C'\fR.
.SS "started"
.IX Subsection "started"
.Vb 3
\& Usage : $job\->started (1)
\& Returns : time when this job was started
\& Args : optional
.Ve
.PP
See \f(CW\*(C`created\*(C'\fR.
.SS "ended"
.IX Subsection "ended"
.Vb 3
\& Usage : $job\->ended (1)
\& Returns : time when this job was terminated
\& Args : optional
.Ve
.PP
See \f(CW\*(C`created\*(C'\fR.
.SS "elapsed"
.IX Subsection "elapsed"
.Vb 4
\& Usage : $job\->elapsed
\& Returns : elapsed time of the execution of the given job
\& (in milliseconds), or 0 of job was not yet started
\& Args : none
.Ve
.PP
Note that some server implementations cannot count in millisecond \- so
the returned time may be rounded to seconds.
.SS "times"
.IX Subsection "times"
.Vb 3
\& Usage : $job\->times (\*(Aqformatted\*(Aq)
\& Returns : a hash reference with all time characteristics
\& Args : optional
.Ve
.PP
It is a convenient method returning a hash reference with the following
keys:
.PP
.Vb 4
\& created
\& started
\& ended
\& elapsed
.Ve
.PP
See \f(CW\*(C`create\*(C'\fR for remarks on time formatting.
.PP
An example \- both for unformatted and formatted times:
.PP
.Vb 10
\& use Data::Dumper;
\& use Bio::Tools::Run::Analysis;
\& my $rh = Bio::Tools::Run::Analysis\->new(\-name => \*(Aqnucleic_cpg_islands.cpgplot\*(Aq)
\& \->wait_for ( { \*(Aqsequence_usa\*(Aq => \*(Aqembl:hsu52852\*(Aq } )
\& \->times (1);
\& print Data::Dumper\->Dump ( [$rh], [\*(AqTimes\*(Aq]);
\& $rh = Bio::Tools::Run::Analysis\->new(\-name => \*(Aqnucleic_cpg_islands.cpgplot\*(Aq)
\& \->wait_for ( { \*(Aqsequence_usa\*(Aq => \*(Aqembl:AL499624\*(Aq } )
\& \->times;
\& print Data::Dumper\->Dump ( [$rh], [\*(AqTimes\*(Aq]);
\&
\& $Times = {
\& \*(Aqended\*(Aq => \*(AqMon Mar 3 17:52:06 2003\*(Aq,
\& \*(Aqstarted\*(Aq => \*(AqMon Mar 3 17:52:05 2003\*(Aq,
\& \*(Aqelapsed\*(Aq => \*(Aq1000\*(Aq,
\& \*(Aqcreated\*(Aq => \*(AqMon Mar 3 17:52:05 2003\*(Aq
\& };
\& $Times = {
\& \*(Aqended\*(Aq => \*(Aq1046713961\*(Aq,
\& \*(Aqstarted\*(Aq => \*(Aq1046713926\*(Aq,
\& \*(Aqelapsed\*(Aq => \*(Aq35000\*(Aq,
\& \*(Aqcreated\*(Aq => \*(Aq1046713926\*(Aq
\& };
.Ve
.SS "results"
.IX Subsection "results"
.Vb 3
\& Usage : $job\->results (...)
\& Returns : one or more results created by this job
\& Args : various, see belou
.Ve
.PP
This is a complex method trying to make sense for all kinds of
results. Especially it tries to help to put binary results (such as
images) into local files. Generally it deals with fhe following facts:
.IP "\(bu" 4
Each analysis tool may produce more results.
.IP "\(bu" 4
Some results may contain binary data not suitable for printing into a
terminal window.
.IP "\(bu" 4
Some results may be split into variable number of parts (this is
mainly true for the image results that can consist of more *.png
files).
.PP
Note also that results have names to distinguish if there are more of
them. The names can be obtained by method \f(CW\*(C`result_spec\*(C'\fR.
.PP
Here are the rules how the method works:
.PP
.Vb 3
\& Retrieving NAMED results:
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& results (\*(Aqname1\*(Aq, ...) => return results as they are, no storing into files
\&
\& results ( { \*(Aqname1\*(Aq => \*(Aqfilename\*(Aq, ... } ) => store into \*(Aqfilename\*(Aq, return \*(Aqfilename\*(Aq
\& results ( \*(Aqname1=filename\*(Aq, ...) => ditto
\&
\& results ( { \*(Aqname1\*(Aq => \*(Aq\-\*(Aq, ... } ) => send result to the STDOUT, do not return anything
\& results ( \*(Aqname1=\-\*(Aq, ...) => ditto
\&
\& results ( { \*(Aqname1\*(Aq => \*(Aq@\*(Aq, ... } ) => store into file whose name is invented by
\& this method, perhaps using RESULT_NAME_TEMPLATE env
\& results ( \*(Aqname1=@\*(Aq, ...) => ditto
\&
\& results ( { \*(Aqname1\*(Aq => \*(Aq?\*(Aq, ... } ) => find of what type is this result and then use
\& {\*(Aqname1\*(Aq=>\*(Aq@\*(Aq for binary files, and a regular
\& return for non\-binary files
\& results ( \*(Aqname=?\*(Aq, ...) => ditto
\&
\& Retrieving ALL results:
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& results() => return all results as they are, no storing into files
\&
\& results (\*(Aq@\*(Aq) => return all results, as if each of them given
\& as {\*(Aqname\*(Aq => \*(Aq@\*(Aq} (see above)
\&
\& results (\*(Aq?\*(Aq) => return all results, as if each of them given
\& as {\*(Aqname\*(Aq => \*(Aq?\*(Aq} (see above)
\&
\& Misc:
\& \-\-\-\-\-
\& * any result can be returned as a scalar value, or as an array reference
\& (the latter is used for results consisting of more parts, such images);
\& this applies regardless whether the returned result is the result itself
\& or a filename created for the result
\&
\& * look in the documentation of the C script for examples
\& (especially how to use various templates for inventing file names)
.Ve
.SS "result"
.IX Subsection "result"
.Vb 3
\& Usage : $job\->result (...)
\& Returns : the first result
\& Args : see \*(Aqresults\*(Aq
.Ve
.SS "remove"
.IX Subsection "remove"
.Vb 3
\& Usage : $job\->remove
\& Returns : 1
\& Args : none
.Ve
.PP
The job object is not actually removed in this time but it is marked
(setting 1 to \f(CW\*(C`_destroy_on_exit\*(C'\fR attribute) as ready for deletion when
the client program ends (including a request to server to forget the job
mirror object on the server side).