Dispatcher::Tool - base class for tools.
# examples here use Dispatcher::Tool;
$Id: Tool.pm.html,v 1.1.1.1 2005/08/18 13:18:25 hunter Exp $
Copyright (c) European Bioinformatics Institute 2002
Ville Silventoinen <vsi@ebi.ac.uk>
Description: Constructor allocates an anonymous hash, which is tied to the class. Arguments: - Returns: $self object
Description: Returns tool name. Arguments: - Returns: Tool name.
Description: Sets tool name. Arguments: $name Tool name. Returns: -
Description: Returns tool input parameter value. Arguments: $key Parameter key. Returns: Value or empty string if key has no value.
Description: Sets tool input parameter value. Arguments: $key Parameter key. $value Parameter value. Returns: -
Description: Removes tool input parameter. Arguments: $key Parameter key. Returns: -
Description: Returns tool's input parameters. Arguments: - Returns: Reference to a hash.
Description: Sets tool parameters. Arguments: $params Reference to a hash. Returns: -
Description: Returns tool configuration value. Arguments: $key Configuration key. Returns: Value or empty string if key has no value.
Description: Sets tool configuration value. Arguments: $key Configuration key. $value Parameter value. Returns: -
Description: Removes tool configuration key-value pair. Arguments: $key Configuration key. Returns: -
Description: Returns tool configuration. Arguments: - Returns: Reference to Dispatcher::Config object
Description: Sets tool configuration. Arguments: $config Reference to Dispatcher::Config object. Returns: -
Description: Returns parameter description. NOTE: this method uses param2desc hash reference inside the object. Each tool that wishes to support descriptions should set it in the object constructor. Arguments: $key Parameter key. Returns: Description or empty string.
Description: Parses tool configuration and sets it inside the tool object. This is a convenience method for all tools derived from Dispatcher::Tool. It sets the YYYY, MM, DD, hh, mm and ss tags automatically by parsing the jobid. Arguments: Same as Dispatcher::Config::parse, excluding the first argument. Returns: 1, '' on success 0, msg on failure
Description: Validates tool name. Arguments: $name Tool name. Returns: 1 on success 0 on failure
Description: Creates an HTML job confirmation page.
NOTE 1: HTTP headers must be added by the caller, because it is impossible to know when they should be added (caller may have started the page and this call finishes it).
Arguments: $in Input sequence (optional). $out Output (default: stdout). $top Page top (default: getHtmlTop). $bottom Page bottom (default: getHtmlBottom).
Returns: 1, '' on success 0, msg on failure
Description: Creates error HTML page to stdout or file. NOTE 1: HTTP headers must be sent by the caller. NOTE 2: This method does not return errors, it is "best effort".
Arguments: $out Output (default: stdout). $emsg Error message string (optional). $efile Error file or file handle (optional). $top Page top (default: getHtmlTop). $bottom Page bottom (default: getHtmlBottom).
Returns: -
Description: Creates HTML page that polls the result page. Arguments: $url URL to be polled. $out Output (default: stdout). Returns: 1, '' on success 0, msg on failure
Description: Creates confirmation mail to stdout or file. Arguments: $in Input sequence (optional). $out Output (default: stdout). Returns: 1, '' on success 0, msg on failure
Description: Checks whether remote host is allowed to access the tool or more specifically the group that the tool belongs to (like EPO tools). Host name is retrieved from environment variables REMOTE_HOST or REMOTE_ADDR. Arguments: $group Group name (optional). Returns: 1, host on access allowed 0, msg on access denied
Description: Reads the request parameters to a hash table. Parameters must be given as a CGI query object. Uploaded files are written to disk with the configured paths uploadfile.1, uploadfile.2, etc. Arguments: $query CGI query object. $check 1: check parameters 0: no check Returns: 1, '' on success 0, msg on failure
Description: Reads parameters from file (handle) and creates a hash. Arguments: $in Input parameters. $params Reference to a hash. Returns: 1, '' on success 0, msg on failure
Description: Writes submission parameters to a file (handle). Arguments: $out Output parameters file. $params Parameter hash. Returns: 1, path on success 0, msg on failure
Description: Returns current date. Arguments: - Returns: yyyy, mm, dd
Description: Returns date extracted from job ID. Arguments: $jobid Job identifier containing "-YYYYMMDD-", Returns: yyyy, mm, dd
Description: Returns date in format YYYYMMDD (numerical). Arguments: $date Date in format in of the following formats: DD-MMM-YYYY (01-Oct-2003) DD-MMM-YY (01-Oct-03) DD-MM-YYYY (01-10-2003) DD-MM-YY (01-10-03) MM/DD/YYYY (10/01/2003) MM/DD/YY (10/01/03)
Returns: YYYYMMDD
Description: Replaces unsafe characters in a string. Arguments: $s String. Returns: string
Description: Removes < > " ' characters from string. Arguments: $s String. Returns: string
Description: Execute a command as a system call (see Programming Perl system function for details).
Arguments: $cmd Command (with args) to execute.
Returns: 1, '' on success 0, msg on error
Description: Sends mail message. If both message body string and file are given, string is set first, then file. Arguments: $to To field. $subject Subject field. $bodys Body passed in a string (optional). $bodyf Body passed in a file or file handle (optional). $from From field (optional). $errorsTo Errors-To field (optional). $chunk Split file to N line chunks (optional). This adds " (part N)" strings also to subject lines. Returns: 1, '' on success 0, msg on failure
Description: Checks if given directory exists and tries to create it. Arguments: $dir Directory. $mode Numeric mode (optional). Returns: 1, '' on success 0, msg on failure
Description: Generates new job identifier. Arguments: $group Tool group, e.g., 'fasta' for all fastas. Returns: jobid in format "toolgroup-YYYYMMDD-rand"
Description: Checks if given job ID is in correct format. Arguments: $jobid Job identifier. Returns: 1, '' on success 0, msg on failure
Description: Trims leading and trailing whitespace. Arguments: $s String. Returns: trimmed string
Description: Reports errors and exits. Arguments: $error Error message, OR $efile Error file. $html 1: create HTML error page 0: email error to user Returns: -
Description: Sends HTTP 403 Forbidden. NOTE! Does not exit! Arguments: $error Error message (optional). Returns: -
Description: Tries to find a file. This is a convenience method for situations when job files can be in different directories. At the moment following work directories set in the tool configuration are searched: workdir, aworkdir and sworkdir. Arguments: $file filename, path or key in tool configuration. Returns: Full path or $file.
Description: Reads from a file handle and writes to another file handle. Checks the number of bytes written and stops writing if the given limit is exceeded. NOTE! Caller is responsible for closing the file handles! Arguments: $readFH Read file handle. $writeFH Write file handle. $limit Limit in bytes (optional). Returns: 1, '' on success 0, msg on failure
Description: Generates unique identifier. Arguments: - Returns: id string
Description: Returns information about sequence. The sequence must be passed in raw or fasta format.
Arguments: $in Input sequence file or file handle.
Returns: 1, dna|rna|protein, length 0, msg
Description: Checks boolean. Arguments: $value Value string (optional). $default Default value (optional). Returns: value
Description: Checks integer. Arguments: $value Value string (optional). $default Default value (optional). $lower Lower limit (optional). $upper Upper limit (optional). Returns: 1, value on success 0, msg on failure
Description: Checks decimal. Arguments: $value Value string (optional). $default Default value (optional). $lower Lower limit (optional). $upper Upper limit (optional). Returns: value
Description: Checks range. Arguments: $value Value string (optional). $default Default value (optional). $lower Lower limit (optional). $upper Upper limit (optional). Returns: value
Description: Checks string value. Arguments: $value Value string (optional). $default Default value (optional). $values Allowed values as array reference (optional). Returns: value
Description: Checks input parameters. Each tool must override this method. Arguments: - Returns: 1, '' on success 0, msg on failure
Description: Checks whether parameter is a file handle. Arguments: $fh File handle. Returns: 1 for FileHandle reference or FileHandle glob. 0 otherwise
Description: Returns reference to a file handle for reading. The caller must close the file handle if close flag is 1. Examples:
# pass file as string, caller must close file handle my ($res, $close, $fh) = $self->getReadHandle('file');
# pass a file handle glob my ($res, $close, $fh) = $self->getReadHandle(\*STDIN);
# pass reference to a FileHandle object my $input = new FileHandle("< file"); my ($res, $close, $fh) = $self->getReadHandle($input);
Arguments: $file Path, FileHandle reference or Filehandle glob. Returns: 1, close flag, file handle on success 0, 0, message on failure
Description: Returns reference to a file handle for writing. The caller must close the file handle if close flag is 1. Examples:
# pass file as string, caller must close file handle my ($res, $close, $fh) = $self->getWriteHandle('file');
# pass a file handle glob my ($res, $close, $fh) = $self->getWriteHandle(\*STDOUT);
# pass reference to a FileHandle object my $input = new FileHandle("> file"); my ($res, $close, $fh) = $self->getWriteHandle($input);
Arguments: $file Path, FileHandle reference or Filehandle glob. Returns: 1, close flag, file handle on success 0, 0, message on failure