6.3. Global Command Line Qualifiers

6.3.1. Introduction

Global qualifiers are command line qualifiers that are available to all EMBOSS applications. They change the behaviour of the program for which they are set. They are specified in the same way as other qualifiers: the flag (qualifier name) is given on the command line after the application name and other parameters. For example:

All the global qualifiers are boolean qualifiers and, as such, can be set by naming them on the command line and specifically unset by prefixing the qualifier with no. For example:

seqret -nohelp

will ensure that usage information for the seqret application is not given.

Most global qualifiers default to FALSE unless a corresponding environment variable is set to TRUE (see Section 2.8, “Maintenance”).

6.3.2. Description of Global Qualifiers

Table 6.1. Global Qualifiers

Qualifier

Description

Default value

-auto Y/N

Turn off prompts

"N"

-stdout Y/N

Write first file to standard output

"N"

-filter Y/N

Read first file from standard input, write first file to standard output

"N"

-options Y/N

Prompt for standard and additional values

"N"

-debug Y/N

Write debug output to program.dbg

"N"

-verbose Y/N

Report some/full command line options

"N"

-help Y/N

Report command line options and exit. More information on associated and general qualifiers can be found with -help -verbose

"N"

-warning Y/N

Report warnings

"Y"

-error Y/N

Report errors

"Y"

-fatal Y/N

Report fatal errors

"Y"

-die Y/N

Report dying program messages

"Y"

-version Y/N

Report version number and exit

"N"

6.3.2.1. -auto

The -auto qualifier turns off any prompting of the user. The program will run with the default settings that are defined in the ACD file. If a parameter does not have a default value but a value is required, the program will terminate with an error message.

The first example below shows seqret being run without the -auto qualifier. The program prompts the user for an output filename as the output sequence is a mandatory parameter. It presents the user with a prompt and a default output filename constructed from the name of the first sequence in the input file plus the name of the output format (pdnirsecf.fasta in this example).

In the second example, seqret is run with the -auto qualifier. The user is not queried for the output filename and it will use the default filename (pdnirsecf.fasta) for the output file.

6.3.2.2. -debug

Turns on logging of debugging messages generated by the application. A debug file is written to the current directory, containing a complete trace of the actions of the program reported by calls to the AJAX function ajDebug(). The file will be called ApplicationName.dbg where ApplicationName is the name of the application.

Consider the following command lines:

seqret sequence.seq -debug

seqret sequence.seq -nodebug

In the first command seqret is called using sequence.seq as the first (and only) parameter and -debug instructs the program to turn debugging on. In the second command seqret is run with the same parameter but the -debug qualifier is prefixed with no, thereby instructing the program to turn debugging off. The latter could be useful if debugging was turned on by default in the EMBOSS configuration files or by an environment variable (see Section 2.8, “Maintenance”).

The example below shows the application seqret being run with the -debug and -auto qualifiers. After completion of the program, a file called seqret.dbg is created in the current directory which contains the debug information:

6.3.2.3. -filter

Makes a program behave like a filter, reading its (first) input file from the standard input, and writing its (first) output file to the standard output. The -filter qualifier will also invoke the -auto qualifier, so missing values are never prompted for.

The example below shows seqret being run with the -filter qualifier. The input file is piped into the program using the Unix command cat and the output is piped directly to the Unix program lpr, which will print it on the printer.

%cat sequence.seq | seqret -filter | lpr

6.3.2.4. -help

You can get help on how to use a program by specifying the -help qualifier. The help text displayed is taken from information in the ACD file. It will list all the application-specific options and any built-in qualifiers (Section 6.4, “Datatype-specific Command Line Qualifiers”) that are associated with the ACD datatypes. It will show the names of the parameters, their type and a brief informative comment, extracted from the help: ACD attribute (see the EMBOSS Developers Guide).

A second qualifier -verbose may be added alongside the -help qualifier and will give further information. For example, it will list global qualifiers.

6.3.2.5. -options

Forces the program to prompt for a value for all application options. By default, EMBOSS will prompt for any options that are defined as parameter: or standard: in the ACD file if a value is not given on the command line. -options turns prompting on for options that are defined as additional:; these are not normally prompted for regardless of what's given on the command line.

In the first example seqdemo is run without any parameters and since the asequence is defined as parameter: Y in the ACD file, it queries the user for the input filename. It also queries the user for the output sequence, since that parameter is labelled as being required (standard: Y). It will not ask for a value for the integer variable outputlength, since it is neither labelled as parameter: Y or standard: Y.

In the second example the integer is asked for, since the -options qualifier forces the program to query for those options that are labelled with the additional: attribute.

Note

Any option that is not defined as a parameter (with the parameter: attribute), as required (by the standard: attribute) or as optional (by the additional: attribute) can still be used on the command line, but the user will never be queried for them. These parameters are considered an 'advanced feature' and can only be used on the command line.

6.3.2.6. -stdout

Changes the default output file to be stdout (normally a terminal on-screen). All the application parameters are still prompted for as normal. This typically includes the output filename, so there is still the option of writing to a file instead.

In the example below the -stdout qualifier changes the default output to be to standard output (the terminal) instead of a file. The output is prompted for, so there is a chance to enter a filename instead. With -auto on the command line, the program would instead write to the terminal without asking:

-stdout makes the first output file default to stdout. Output files include the outfile, outseq, report, align and a few other ACD datatypes (see the EMBOSS Developers Guide).

Note

The -stdout option does not apply to graphics output; X11 output for example does not get written to file. The plplot graphics library used by EMBOSS creates its own output filenames. Currently if you use -goutfile stdout you'd get a file called stdout.ps created.

6.3.2.7. -warning, -error, -fatal

These qualifiers force the application to generate informative messages, if necessary, to the file stderr (normally the terminal). The messages are of three types: warnings, errors and fatal errors (which are generated when the application must terminate).

In contrast to all other global qualifiers, these qualifiers default to TRUE unless they are unset on the command line or a corresponding environment variable is set to FALSE (see below).

6.3.3. Global Qualifiers and Environment Variables

Table 6.2. Environment variables associated with global qualifiers.

Environment Variable

Description

Type

Default value

EMBOSS_ERROR

Print error messages to standard error

boolean

Y

EMBOSS_FATAL

Print fatal error messages to standard error

boolean

Y

EMBOSS_WARNING

Print warning messages to standard error

boolean

Y

The actions of all the global qualifiers, and so the default behaviour of the applications, can be changed by using environment variables. The variable names consist of the word EMBOSS and the name of the qualifier (uppercase) separated by the underscore character (_).

Most global qualifiers default to FALSE unless an appropriate environment variable is set. The exceptions are the message level qualifiers -warning, -error and -fatal.

Environment variables are set with YES, Y, TRUE, T, or 1. Both lowercase and uppercase are accepted. If for example you use the csh shell then the following commands would all have the same effect:

setenv EMBOSS_QUALIFIER TRUE

setenv EMBOSS_QUALIFIER true

setenv EMBOSS_QUALIFIER T

setenv EMBOSS_QUALIFIER t

setenv EMBOSS_QUALIFIER YES

setenv EMBOSS_QUALIFIER yes

setenv EMBOSS_QUALIFIER Y

setenv EMBOSS_QUALIFIER y

setenv EMBOSS_QUALIFIER 1

If you use the sh or bash shell then all that differs is the style of command e.g.:

export EMBOSS_QUALIFIER=YES

where QUALIFIER is the name of the global qualifier.

Environment variables can be set, as above, on the command line, but can also be set in the EMBOSS configuration files, which include the global emboss.default file and the user's .embosssrc file (see Section 2.8, “Maintenance”).

6.3.3.1. Negation

When an environment variable is set, its effect can be cancelled by using the negating action of prefixing no to the corresponding boolean qualifier name Consider the following ACD file:

The first example shows the behaviour without the EMBOSS_OPTIONS environment variable being set. The program seqdemo behaves in the standard way, and only asks for the outputlength parameter when the -options qualifier is used. In the second example the environment variable EMBOSS_OPTIONS is set at the command line and the effect is that it now asks for the outputlength parameter without the -options qualifier being used. The effect of the environment variable is cancelled by using the negating effect of adding the prefix no to the qualifier -options (giving -nooptions).