Using Programs

[Genhelp | Program Manual | User's Guide | Data Files | Databases | Release Notes ]

Table of Contents

Overview

Working with programs

Starting programs

Running programs in the background

Answering program prompts

Stopping programs

Using program parameters

Rules for using command line parameters

Customizing program analysis

Using program parameters

Displaying a summary of program parameters

Using global parameters

Using global switches

Using command line control

Suppressing program prompts

Working with text output files

Redirecting program output to a device

Directing output to a file

Directing output to your screen

Directing otput to a pinter

Using the batch queue

Submitting jobs to the batch queue

Checking if your batch job completed

Deleting a batch job

Troubleshooting a failed batch job

Customizing batch

For advanced users

Redirecting output to another program

Using command line initialization files

Creating a command line initialization file

Using a command line initialization file

Using aliases

Defining aliases

Using aliases

Working with shell scripts

Creating a shell script

Using a shell script

Overview

[ Top | Next ]

This section teaches you the basics of working with Accelrys GCG (GCG) programs. It provides information that you must know to take advantage of and effectively use the many options the package offers. For information about specific programs, refer to the Program Manual or online help.

In this section, you'll learn how to

  1. Start and stop a program.
  2. Specify parameters to customize a program's analysis.
  3. Display, print, or direct text program output to a file (for graphic output, see Section 5, Using Graphics).
  4. Submit jobs to the batch queue to run at a later time and free your terminal for other work.

Working with programs

[ Previous | Top | Next ]

Note: For a list of functionally grouped programs in GCG and their descriptions, see Appendix A, Short Descriptions.

This section teaches you how to

  1. Start programs.
  2. Run programs in the background.
  3. Answer program prompts.
  4. Stop programs.

Starting programs

To run GCG programs:

  1. Make sure you have initialized GCG.

If you have not initialized GCG, or you are not sure if it is initialized, type the following

   % gcg

 

 When fully initialized, a GCG banner scrolls on your screen. For more information, see "Initializing GCG" in Section 1, Getting Started.

  1. Type the name of the program on the command line and press <Return>. The system starts the program, displaying a short summary of its purpose and prompting you for information.

After you become familiar with GCG programs, you may want to customize the analysis performed by a program by adding parameters on the command line after the program name. For more information, see "Using Program Parameters" in this section.

Note: GCG program commands are case sensitive. Therefore, you must type all program names in lowercase.

Running programs in the background

You can run programs in the foreground or background. When you run a program in the foreground, you are not able to use your computer until the program is done running. However, when you run a program in the background, the program runs as normal, but your terminal is free to do other work. You can run any GCG program in the background. For a more general explanation of running programs in the background, see "Controlling Program Execution" in Section 1, Getting Started.

To run programs in the background:

Add an ampersand (&) to the end of a GCG command line. You must use command-line control to suppress the program's interactive prompts. Use the -Default parameter and redirect standard output to a file. For example

 

When the program is done running in the background, you will receive a message telling you so. For example:

[1] Done (set noglob; $GCGUTILDIR/stringsearch ...)

 

If the command line becomes too long or complicated, you may want to type GCG commands into a shell script and run the shell script in the background. For more information, see "Working with Shell Scripts" in the "For Advanced Users" topic of this section.

 

Answering program prompts for plus (+) programs in GCG

Note: Plus programs in GCG include several enhanced versions of corresponding non-plus programs. Several completely new programs such as ClustalW+, SeqConv+, and SeqManip+ also follow the same prompting scheme.

Plus programs prompt you for information: they usually require a sequence for input, a name for an output file, the beginning and ending positions of the portion of sequence you want to use, and other pieces of information particular to individual programs.

You can answer most program prompts with a yes or no, a number, a letter, or a filename. Some prompts display several alternatives for you to choose from. The following example displays some of the various types of prompts.

 

Entire sequence range is considered as default
 

 
Program Defaults (changes, when compared to Wisconsin Package 10.3 program defaults)

When appropriate, GCG programs supply default answers for program prompts. You can accept the default answer or type a different response. The default answer is always displayed between parentheses and asterisks. In the example above, default answers are provided for many of the prompts, for example, Begin (* 1 *), End (* -1*) is the default notation in GCG plus (+) programs for choosing the entire sequence range of the input file and (* <sequence_name.map+> *) is the default notation for naming the output file with <sequence name.program name>. If multiple input files are used, then GCG (+) applications, name the output file as <program name.out>

To answer program prompts:

Choose from the following.

  1. Accept the default answer, if available, by pressing <Return>.
  2. Type an appropriate answer to override the default answer and press <Return>.

Note: If you press <Return> without typing an answer in response to a prompt which does not have a default, the program will stop.

Answering program prompts for non plus programs in GCG

Non plus programs also prompt you for information as in Wisconsin Package 10.3 version: they usually require a sequence for input, a name for an output file, the beginning and ending positions of the portion of sequence you want to use, and other pieces of information particular to individual programs.

You can answer most program prompts with a yes or no, a number, a letter, or a filename. Some prompts display several alternatives for you to choose from. The following example displays some of the various types of prompts.

Program defaults

When appropriate, GCG programs supply default answers for program prompts. You can accept the default answer or type a different response. The default answer is always displayed between parentheses and asterisks. In the example above, default answers are provided for many of the prompts, for example Begin (* 1 *), End (* 11375 *), Enzyme (* * *), (* t *), and (* gamma.map *).

To answer program prompts:

Choose from the following.

    1. Accept the default answer, if available, by pressing <Return>.
    2. Type an appropriate answer to override the default answer and press <Return>.

Note: If you press <Return> without typing an answer in response to a prompt which does not have a default, the program will stop.

 

Stopping programs

To stop a program:

Choose from the following.

  1. Press <Ctrl>c to quit a program prematurely.
  2. Press <Ctrl>z to suspend a program you want to work on later.

To bring the suspended job to the foreground where you can work with it again, type % fg %job_number, for example % fg %6. If you cannot remember what programs you suspended, type % jobs to list the jobs and job numbers.

Using program parameters

[ Previous | Top | Next ]

So far in this section you've learned how to start programs and interactively answer their prompts. This section teaches you how to use program parameters, or modifiers of the program command. Using parameters, you can bypass interactive prompts or use additional optional parameters to change the way programs analyze your data or display the analysis results.

This section teaches you

  1. The rules for using command-line parameters.
  2. How to customize your analysis.
  3. How to use command-line control.

 

Rules for using command line parameters

You let the computer know what parameters you want to use by typing them on the command line after the program name. The command line is what you type after the system prompt (%) to run a program or command. You have a number of options for running programs from the command line. If you are a new user, you may want to type just the program name, without any parameters, and respond to the program prompts. Once you become more familiar with GCG, you will probably also type one or more required or optional parameters to customize your analysis. Or you might want to bypass the program's prompts by just typing the program's minimal syntax.

You do not need to use parameters; each program performs a standard analysis if you simply type the program name and answer the program prompts. Using parameters, however, gives you more control over a program and lets you customize your analysis.

Parameters

Parameters modify the action of the command. Some parameters accept values. Consider the following example:

All qualifiers are preceded by a dash (-). Some qualifiers accept values, which modifies the qualifier. Do not insert spaces in between a qualifier and its value.

Command line syntax

Command lines have a special syntax. Below is an example of the syntax used within GCG:

 

 

Program Name or Command. GCG program or UNIX command you want to run.

Unqualified Parameter. An unqualified parameter is a value specified without a qualifier. You can specify input and output filenames without qualifiers, as in the example above, where ggammacod.seq is an input file. You can use the command-line qualifiers -INfile= or -OUTfile= to specify input and output files, respectively. Consider the following example:

% map+ -INfile=ggammacod.seq -OUTfile=ggammacod.map -Default
% map+ ggammacod.seq ggammacod.map -Default

Notice that the first command line uses qualifiers for the input and output files and the second does not. Both, however, perform the same action; that is, they both use ggammacod.seq as the input file and to write the output into a file named ggammacod.map.

The order in which unqualified parameters appear on the command line is significant to how the program interprets them. Always provide input filename(s) first, followed by output filename(s).

Note: In those cases where you can type an unqualified parameter, the documentation displays the optional qualifier in brackets (for example [-INfile1=]). Do not type the brackets.

Command line guidelines

Because command lines have a special syntax, there are a number of guidelines you should keep in mind as you work with them:

  1. You must type program names in lowercase.
  2. Command-line parameters are case insensitive. Therefore, you can type them in lowercase, uppercase, or mixed case and the program interprets them correctly. However, most parameter values are case sensitive and should be typed in all lowercase.
  3. Square brackets [ ] surrounding a parameter indicate that typing it is optional (for example [-INfile=]). That is, you can omit the qualifier contained within the brackets and type just the value. Such a parameter is called an unqualified parameter. For instance

% map+ -INfile=ggammacod.seq -Default

is the same as

% map+ ggammacod.seq -Default

  1. Most programs allow you to omit the qualifiers for input and output filenames. If this is the case, specify them all with the same syntax; that is, use either qualifiers for all the input and output files (% gap -INfile1=ggamma.seq -INfile2=agamma.seq) or no qualifiers for any of them (% gap ggamma.seq agamma.seq). If you do not use qualifiers, you must specify the filenames in order: infile1, infile2, etc., outfile1, outfile2, etc.
  2. If you use -Default to suppress all program prompts, and there is no default for a prompt (for example an input filename), the program will display an error message and stop. For more information about -Default, see "Using Command-Line Control" in this section.
  3. Some parameters have numbers associated with them, for example -INfile1= or -DATa2=. A 1 following the parameter name is assumed by the program, and you can omit typing it. However, for those programs that accept multiple filenames, you must include numbers greater than 1 as part of the parameter name.
  4. If the same parameter appears more than once on the command line, the program will use the last parameter.
  5. If the parameter value is out of the range of acceptable values, the program will use the nearest acceptable value. For example, if you have a sequence with 300 bases, and you specified -END=320, the program would use 300. The program does not warn you of this change.
  6. If you specify an input filename that doesn't exist, the program will display an error message and stop. If you specify a data file that doesn't exist, the program will use a default value, if available.
  7. If you misspell a parameter, the program will ignore it without warning.

Note: All plus programs will give a warning if the parameter entered is not a valid parameter.

Customizing program analysis

GCG programs offer flexibility in customizing your analyses by allowing you to modify the way a program processes your sequence information. Each program supports a number of parameters, or modifiers of the command. These parameters change the way the programs analyze your data.

Most GCG programs provide you with a summary of the available command-line parameters. Each command-line summary is subdivided by the following headings: Minimal Syntax, Input File(s), Prompted Parameters, Local Data Files, and Optional Parameters. Consider the following command-line summary for the Gap program:

 

Minimal Syntax. Shows the minimal command line you can type to suppress the program prompts and all interaction by you. The minimal command line sets the essential parameters that are those for which the program has no default value and without which it cannot run. A default value is one that a program uses if you do not supply one. Most programs prompt you for an input file or sequence for which there is no default value.

Prompted Parameters. Shows all parameters not included on the Minimal Syntax line that are required by the program to run. You can bypass these parameters by using the -Default parameter, which tells the program to use defaults for those parameters that have them. If you do not supply the required parameters or if you do not use -Default on the command line, the program will prompt you for them.

Local Data Files. Lists the local data files the non plus program uses by default. Local data files are non-sequence data files containing information such as restriction enzyme names and recognition sites. You can change the local data files a non plus program uses to tailor your analyses. Alternative data files for some programs are available; for many programs you can create your own data files as well. For more information, see Section 4, Using Data Files.

Optional Parameters. Lists additional parameters you may want to include on the command line to customize your analyses. Optional parameters offer you flexibility in manipulating a program. However, they are not required for the program to function.

Note: You can set optional parameters only from the command line; the program does not prompt you for them.

Using program parameters

To use program parameters:

Type -qualifier=value on the command line following the program name, for example % map+ -INfile=ggammacod.seq -Default. You can include as many parameters on the command line as you need to run your analysis.

To extend long commands onto a second line, type a backslash (\) at the end of the preceding line, press <Return>, and continue typing the rest of the command line.

For more information, see "Rules for Using Command-Line Parameters" in this section.

Displaying a summary of program parameters

You can find a summary of each program's available command-line parameters either in the Program Manual or in the Command-Line Summary this guide. However, an easier way to see the parameters that are available for a particular program is to display them online when you run the program.

To display a list of command-line parameters online:

Choose from the following.

  1. -CHEck. Type the parameter -CHEck on the command line following a program name, for example % map -CHEck. The program displays a summary of the available parameters and the prompt "Add what to the command line?" You can type the additional parameters you want at that time. You must precede each parameter with a dash (-).

Note: Plus programs will only display the summary of the available parameters.

2.      -CHEck is a global parameter (see "Using Global Parameters" in this section).

Using global parameters

You can find parameters specific to each program fully described in the "Optional Parameters" topic in the entry for each program in the Program Manual. In addition, there are a number of parameters that are global within the package; that is, they can be used by all GCG programs. To avoid repetition, these optional global parameters are not displayed in the "Command line summary" in the online or printed documentation.

A separate set of global parameters are also available when you run graphics programs which are applicable only for the non plus programs only. For more information, see "Graphic Global Parameters" in Chapter 5, Using Graphics.

To use global parameters:

Add them to the command line just as you would a program parameter, for example % map gamma.seq -CHEck.

Global Parameters

Description

-CHEck

Prints a summary of the available command-line parameters and prompts you for any additions you may want to make to the command line.

-Default

Tells the program to suppress all interaction and to use the program's default values for every parameter that is not explicitly defined on the command line.

-DOCLines=6

Sets the number of lines of documentation that GCG programs copy from input files to output files. This option sets a program to copy any number of lines you choose. The default is six lines.

-FASTA

Sets a non plus program to accept sequences in FastA format.

-INITialize=initialization_file.init

Names the file the program should use as a command-line initialization file (see "Using Command-Line Initialization Files" in the "For Advanced Users" section in Section 3 of the User's Guide).

If you do not specify the initialization_file.init, the program will use the file with a name the same as the program and the file extension .Init, for example % map -INIT uses the file Map.Init.

-QUIet

Sets a program not to ring the terminal bell, even when an error occurs.

Note: You can specify many of the above options to be in effect for an entire session using global switches. For more information, see the "Using Global Switches" topic below.

Using global switches

Global switches change the behavior of programs in the same way that command-line parameters do. However, unlike command-line parameters, which affect only the current program you are running, global switches affect every program you run until you log out.

You activate a global switch by typing its name on the command line, for example % comcheck.

Note: System Managers can change the values of global switches for all users by editing the file $GCGROOT/etc/symbol.conf                                                                                                                                           

For example, the default value for Nucleotide database is set to GenBank in the symbol.conf file as shown below;

DEFAULTNUCDB = genbank

In order to change the value of the default nucleotide database, you need to edit the symbol.conf file. The changed value looks like:

DEFAULTNUCDB = MyNucDB

Note: Command-line parameters always override global switches. For example, let's say at the beginning of your current work session you set the global switch % doclines 6. You could override that global switch for a single program by adding -DOClines=10 to the command line after the program name

Note: If you wish to customize global switch values for your local environment, then edit the file $HOME/.wp/symbol.conf file.

                       

A typical $GCGROOT/etc/symbol.conf file is as shown below:

 

########################################################################

# Fixed configuration variables

########################################################################

# The following are variables that can only be set in this file and cannot be overridden by the user.

WPROOT = ${WPROOT}

ACCOUNTING = FALSE

LOGGING = TRUE

AUTHNODE =

GCGMAXPROCESSORS = 64

GCGNICECOMMAND = nice +20;

GCGSUBMITCOMMAND = at now

VERSION = GCG 11.0

FRAMESEARCHNUCDB = EST

GCGMAILER = Mail -s __program__ __user__

 

########################################################################

# User configuration defaults

########################################################################

# The following are variables that are given a default value but  can be overridden by individual users in the $HOME/.wp/symbol.conf file

SQFORMAT = GCG

PROFILESEARCHNUCDB = EMBL

PLOTAUTOFEED = FALSE

PLOTDEVICE = PNG; Lets you define the type of graphics output device you want to use and the port to which it is

             connected. User can set any of the given values like gif, hpgl, png, postscript, regis, sixel, tektronix,

xwindows.

PLOTDRIVER = pngd

PLOTPAGESIZE = A4 (Specifies the type of paper to be used for printing the plot graphics)

PLOTWIDTH = 1280

PLOTHEIGHT = 1024

PLOTPASSTHROUGH = FALSE

COPYHEADLINES = 6 (Sets the number of lines of documentation that GCG Package programs copy from input files into

                  output files. The default number of non-blank lines copied is six.)

DEFAULTNUCDB = genbank (default nucleotide database)

DEFAULTPROTDB = uniprot (default protein database)

DOCUMENTATION = TRUE - (Turns on the documentation that appears when you use GCG Package commands.)

COMQUERY = FALSE

DOPLOTCHECK = TRUE (Turns on the report of your current graphics configuration that appears when you run a graphics program)

ISUNIXDOC = TRUE

UWBEEP = FALSE (Turns off the bell-ringing function of all programs.)

Using Command line control

Command line control is based on the assumption that much of your work with the computer and GCG involves the repetition of similar commands. For instance, if you run the same analysis repeatedly, you may want to bypass the program's interactive prompts. To do so, you must supply all of a program's essential parameters--that is, those which the program must have to run to completion without your interaction. In addition you can specify optional parameters.

To use command-line control, include one or more parameters after a program name, supplying those necessary to suppress the program's prompts. To extend long commands onto a second line, type a backslash (\) at the end of the preceding line. Parameters must be preceded by a dash (-); do not type a space in between the dash (-) and the parameter. Many parameters require values, for example -BEGin=1 -END=1000, although not all do, for example -BATch. Values can include filenames, numbers, and character strings.

Note: Not all programs support command-line control. See the "Command line summary" for each program in the Program Manual. The "Minimal Syntax" line lists the minimum command line you can type to suppress all program prompts.

Suppressing program prompts

There may be times when you want to suppress program prompts. For instance, if you want to run a program in the background (see "Running Programs in the Background" in this section), you must create a shell script that includes the required command-line parameters. The parameters must answer all the program prompts and allow the shell script to run to completion without your interaction. Otherwise, the program will stop when it reaches the first unanswered prompt.

To suppress program prompts:

Answer all of the program's questions by using parameters on the command line. Use the following guidelines:

  1. Bypass prompts, both those with default answers and those without, by typing the required parameter on the command line. These parameters are listed under the "Prompted Parameters" heading within the "Command Line Summary" topic of each program.

For example, to suppress the program prompts of the FastA program, you can type something similar to % fasta+ -INfile=ggammacod.seq -Default, where GGammaCod.Seq specifies the input file and -Default tells the program to accept default values for the rest of the program prompts.

  1. Bypass prompts which have default answers by typing the parameter with a different value or no value on the command line. For example, -BEGin -END on the command line causes the program to use the default values and suppresses the corresponding program prompts. Or, you can provide a value for one or both of the parameters, for example -BEGin -END=300.
  2. Bypass all prompts which have default answers (and whose values have not already been specified on the command line) by typing the parameter -Default on the command line following the program name. -Default tells the program to accept all default parameters in the program. However, not all prompts have a default answer, and often you must provide a program with the name of the input file.

If you want to change parameters, type the parameter and new value on the command line.

Note: When you use -Default without specifying an output filename, the program supplies a default name for the output file. The default name is often the name of the input sequence or file with the name of the program as the extension, for example ggammacod.fasta.

Working with text output files

[ Previous | Top | Next ]

Note: If you are using a program that produces graphics output, see Section 5, Using Graphics.

This section teaches you how to

  1. Redirect program output.
  2. Print text output files.

Redirecting program output to a device

Programs typically direct their output to a file. However, you can redirect the output to your terminal screen or a printer. If you do so, the output is not saved in a file for future use.

Directing output to a file

Most GCG programs write a text file with the output from the program. They ask the question "What should I call the output file?" and often provide a default filename consisting of the name of the input file with an extension of the program name. For example, if you run the program Map with the input file Gamma.Seq, the program provides Gamma.Map as the default output filename.

If you save program output to a file, you can view it on your screen or print it at any time.

To direct output to a file:

Type the name of an output file in response to the program prompt "What should I call the output file?" If you are using command-line control, type -OUTfile=filename. The program writes its results into the file you named in your current directory.

In some cases output files act as input to other programs. In addition, you can edit most output files with any text editor, allowing you to customize your files for other uses. For more information about working with output files, such as how to view and edit them, see "Working with Files" in Section 1, Getting Started.

Directing output to your screen

While almost all GCG programs write their results into a text file, you also can direct the output to your terminal screen.

To direct output to your screen:

Choose from the following.

  1. Type term in response to the prompt "What should I call the output file?" If you are using command-line control, type -OUTfile=term. The program results appear on your screen.
  2. On the command line, type -OUTfile=- | more. The hyphen (-) is standard output, which by default is your terminal screen. When you pipe standard output into the "more" program, it lets you view the output one screen at a time. Press the <Space Bar> to advance from screen to screen.

Note: For plus programs, type –outfile=- to write the output to standard output.

For more information about standard output and piping, see "Using Command-Line Redirection" in Section 1, Getting Started.

Note: When you direct output to your screen, no output file is saved. Also, note that some programs, such as Assemble, CodonFrequency, and Translate, do not let you direct output to your terminal screen.

Directing output to a printer

To send an output file directly from a program to a queued printer:

Type "| lpr" (that is, double quote ("), pipe (|), lpr, double quote (")) in response to the program prompt "What should I call the output file?" If you are using command-line control, type -OUTfile=- | lpr. The program sends the output to the default printer. See your system manager for more information on how to send output directly from a program to a printer and on what printers are available to you.

Note: When you direct your program output directly from a program to the printer, no output file is saved.

Using the batch queue

[ Previous | Top | Next ]

Most GCG programs run in a very short time. However, some programs, such as the database searching programs, can take several minutes to several hours to run. In such cases, you may want to run the programs in the batch queue. After you submit a program to run in the batch queue, your terminal is free for other work. Also, if your system charges for resources, it often will cost less to run programs in the batch queue.

Note: The batch queue is sometimes referred to as the queue or script-execution queue in other UNIX documentation.

This section teaches you how to

  1. Submit jobs to the batch queue.
  2. Check if your batch job completed.
  3. Delete a batch job.
  4. Troubleshoot a failed batch job.
  5. Customize batch.
What is the batch queue?

The batch queue is a list of batch jobs waiting to execute. When you submit a job to the batch queue, it is scheduled to run at a later time.

When you submit a job to batch, you are telling the system to run the command for you as a separate process and at a later time. While the program you submitted is either running in the background or waiting to run, your terminal is free to work on other jobs. Or, you even can log off the computer and your program will continue to run.

Batch job status

When you submit a job to the batch queue, the system displays its name and status on your screen. A just-submitted job can have one of the following statuses:

When do I use the batch queue?

You should use the batch queue when you want to run a program at a later time or when you want to run programs that accept the -BATch parameter in the background. Otherwise, add an ampersand (&) to the command line to place the program in the background to run immediately. For more information, see "Running Programs in the Background" in this section.

-Batch Parameter

Some of the New GCG 11.0 programs that use the –Batch are:

CoilScan+

FastA+

FastX+

FindPatterns+

SSearch+

MEME+

Formatdb+

NetBlast+

TFastA+

TFastX+

 

GCG default setting for the -BATch parameter is to execute a job as soon as possible. However, your system manager may have modified the -BATch parameter to execute jobs at a later time. See your system manager for more information.

Batch job example

The following is a typical example of a program submitted to the batch queue using the -BATch parameter.

System messages

Note the system messages in the batch job example above:

** fasta will run as a batch or at job.

This GCG message confirms that this program was submitted to the batch queue.

** fasta was submitted using the command:
"atnow".

This GCG message identifies the UNIX command used to submit your program to the batch queue. If the command you see is different than the one in the example, your system manager has changed the -BATch parameter.

Note: Since you or your system manager is able to modify the command to submit jobs to batch, your message may read differently.

job smith.841776982.a at Mon Dec 2 13:56.22 1996

The system also displays a job number and date below the messages. The system assigns a unique number to each job submitted to the batch queue. To check on jobs in the batch queue, type % at -l. The system displays a list of jobs waiting to execute.

Batch job results

When you submit a job to the batch queue, the program creates two files in your current directory. Both files have the same base name (which is the name of the program), an underscore (_), and a unique number, for example fasta_30848_1. One of the two files has the extension ".init"; this file contains the parameters you are using to run the program. The other file, which has no extension, contains the shell script that runs the program. When your job completes, the system deletes both files from your directory unless you add -NODELete to the program command line.

After the job executes in the batch queue, the system sends an e-mail message notifying you that the job completed. This e-mail message contains the standard output and standard error, the messages normally displayed on your screen when you run the program interactively. If for some reason your batch job fails, you can examine the contents of this e-mail message to determine why.

You can find the results of your batch job in the output filename you specified. Unless you specify otherwise, the output file appears in the directory you were in when you submitted the program. If the batch job fails or is interrupted, the .init file and the file that has no extension may not be deleted. If this is the case, you can delete the files from the directory.

Submitting jobs to the batch queue

Some programs support the command-line parameter -BATch to submit themselves to the batch queue. For those programs that do not support -BATch, you can write shell scripts to submit them to the batch queue.

To submit a job to the batch queue:

Choose from the following.

  1. -BATch. If the program supports this option, add the parameter -BATch to the command line. The program prompts you for all required parameters that you didn't specify on the command line. After the last prompt, instead of running, the program submits itself to the batch queue. A number of messages display on your screen that confirm the batch submission (see the batch job example earlier in this section).
  2. Shell script. If a program doesn't support the -BATch option, write a shell script to submit to the batch queue. For more information on writing shell scripts, see "Working with Shell Scripts" in the "For Advanced Users" section in this section.

 

Checking if your batch job completed

The system sends you a mail message when your batch job completes. You can find the output file in the directory you were in when you ran the batch job.

Deleting a batch job

At some point in your work with submitting jobs to the batch queue, you may want to cancel an already submitted job. For instance, what if you submitted a FastA job to batch, but then realized you specified the wrong sequence? You can delete the job from the batch queue.

To delete a job from the batch queue:

  1. Type % at -l to display the unique number assigned to each job in the batch queue. For example

    % at -l
    job smith.841776982.a at Mon Dec 2 13:56.22 1996
  2. Type % at -r job_number to delete the job from the batch queue, for example % at -r smith.841776982.a.

 

Troubleshooting a failed batch job

A batch job may fail for a number of reasons: perhaps you forgot to specify a value for a parameter that did not have a default, or the program stopped running because of memory problems, or maybe you provided a filename that did not exist, among other reasons.

There are two ways to troubleshoot a failed batch job. One way is to check the batch job's e-mail message. After the job executes in the batch queue, the system sends an e-mail message notifying you that the job completed. This e-mail message contains the standard output and standard error, the messages normally displayed on your screen when you run the program interactively. If for some reason your batch job fails, you can examine the contents of this e-mail message to determine why.

A second way to troubleshoot a failed batch job is to run the program again, sending the system and error messages to your screen while it runs. These messages may be more meaningful than the e-mail messages.

To troubleshoot a failed batch job:

Note: If you are submitting a job to the batch queue using the -BATch parameter, do steps 1 and 2. If you are submitting a shell script to the batch queue, do only step 2.

  1. Run the program in batch again, adding -NODELete to the command line.

This parameter prevents the batch program's shell script and .init file from being deleted after the program completes.

  1. After the batch job completes (presumably failing), type % csh -xv filename. This command runs the batch shell script again, displaying all the system and error messages as the program runs. You can often determine why and where a batch job fails by examining these messages.

TIP - If your shell script runs correctly interactively but fails when you run it in batch, check that GCG is initialized in the script. For more information, see "Creating a Shell Script" in the "For Advanced Users" section of this section.

Customizing batch

You can change the time a batch job runs by editing the file symbols.conf in your $HOME/.wp directory. You can change the time for each separate program or for all programs that support the -BATch parameter. Your changes to batch stay in effect until you log off of the computer.

To customize the time at which a job is submitted to the batch queue:

For example, if you wish to change the batch timing for a FindPatterns+ program, follow the instructions given below;

Open the file $HOME/.wp/dirs.conf.  The file displays the programs supporting the -BATch parameter with an option –BatchList. Include the name of the program for which you want to change the batch time in the –BatchList option.

Type the submit command with which you want to run the program(s). For example, to run a program at 1:00 a.m., type at 1. For help on specifying a submit command, type ? and press <Return>.

Add a line in the file like:

<ProgramName>SubmitCommand at night/at now/at noon

Example:    FindPatterns+SubmitCommand at now

For advanced users

[ Previous | Top | Next ]

This section covers advanced tasks you may want to perform after you have become familiar with the basics of running GCG programs. This section teaches you how to

  1. Redirect output to another program.
  2. Use command-line initialization files.
  3. Use aliases.
  4. Work with shell scripts.

Redirecting output to another program

A pipe (|) is a mechanism for running two programs from a single command line. One program generates output while the second program accepts that output as program input.

There are two kinds of pipes that you can use with GCG: shell pipes and GCG pipes.

When a pipe character appears as part of the value of a command line parameter where a filename is expected, a GCG pipe is used. In such a case, the pipe character must be enclosed in double quotation marks (") to prevent the shell from interpreting it. When you use an unquoted pipe character to redirect the standard output of a program, a shell pipe is used.

You can use only GCG pipes from the program prompts. Whereas shell pipes can be used only to redirect standard output (or both standard error and standard output), you can use GCG pipes in place of any output file. Shell pipes run both programs simultaneously; GCG pipes run the two programs serially: first the program generating the output runs, then the program consuming the output.

The first example below uses shell pipes and the second uses GCG pipes. In these examples both produce exactly the same output.

Example 1:

% gunzip –c uniprot_trembl.dat.gz | dataset+ -infile= - -ln uniprotdb -dir=/HomeDir/dataset/testdb -d

Notice that in the first example GCG program gunzip (standard UNIX utility to unzip files) sends the output to standard output (-out=-). The shell uses the standard output of gunzip as the standard input to the program Dataset+.

Example 2:

You typically direct where your program output goes; that is, you might direct output to a file, to your screen, or to a printer or plotter (see "Redirecting Program Output to a Device" in this section). You also can direct output from one program as input to another program. For example, the Compare program writes an output file that is input to the DotPlot program. To redirect the Compare output to the DotPlot program, you could type "| dotplot -Default" in response to the program prompt "What should I call the output file?" The | is a pipe that takes the output from the current program or command and passes it to a second command following the |. This second command and its parameters must suppress any interactive prompts. You must enclose the | and its following command in double quotation marks (").

Note that although piping the output from one program into another saves you some time, no output file is saved in the process.

To redirect output to another program:

Type "| program -Default" in response to the prompt "What should I call the output file?" To redirect output to another program using command-line control, add -OUT="| program -Default" to the command line.

Using command line initialization files

What is a command-line initialization file?

A command-line initialization file is a separate file in which you define parameters that you want to use consistently with a particular program. Let's say you consistently run the program Map with the parameters -ENZymes=* -MENu=s -SIXbase -WIDth=100. Instead of typing those parameters each time you run the Map program; you can type them once in a command-line initialization file.

All GCG programs that have command-line control let you define parameters in command-line initialization files. You can type parameters on the command line to override those defined within the command-line initialization file.

Why would I want to use one?

Command-line initialization files are advantageous if you want to ensure that you consistently run a program with the same parameters each time. They are especially appropriate to use when you have a number of parameters you want to consistently use. Another advantage is that, because a command-line initialization file is simply a file, you can modify it with a text editor.

Note: If you have a limited number of parameters you want to use, you may want to consider defining them in an alias. For more information, see "Using Aliases" in the "For Advanced Users" section of this section.

Creating a command line initialization file

To create a command-line initialization file:

  1. Open a new file with the text editor of your choice, for example vi.
  2. Type the appropriate information. A command-line initialization file consists of an optional documentary heading, a dividing line ending with two adjacent periods (..), and the parameters you want added to the command line.

Below is an example of a command-line initialization file for the Map program.

 

  1. Save and exit the file.

If you save the file with the name of the program and the extension .init, for example map.init, the corresponding program automatically will use the file each time you run the program from that directory. If you do not want to use the initialization file every time you use the program, save the file with a different name.

Using a command line initialization file

You can name command-line initialization files so that programs automatically use them each time they run, or you can manually specify the initialization file on the command line when you run the program. Note that in either case, you can override a parameter you specified within the initialization file by adding that parameter and its new value to the command line. Command-line parameters always override parameters defined within a command-line initialization file.

To specify a command-line initialization file for a program:

Choose from the following.

  1. Name the initialization file with the program name and the extension .init, for example map.init. When you run the program, it automatically uses the appropriate .init file and displays a message telling you so, for example "I read your map.init file."

Note: You must run the program from the directory containing the .init file for the program to automatically use it.

  1. Add -INITialize=filename to the command line, where filename is the name of the command-line initialization file you want to use.

Using aliases

What is an alias?

An alias is a shorthand shell command that you define. For instance, let's say you switch between two graphics devices frequently. Each time you switch to a different device, you must redefine your graphics configuration. Instead of running through the graphics configuration commands each time, however, you can define an alias symbol for each device. Then, to switch between devices, you only have to type the alias instead of running through the entire graphics configuration command set up. (For more information on graphics devices, see Section 5, Using Graphics.)

You can type parameters on the command line to override those defined within the alias.

Why would I want to use one?

Defining aliases is advantageous if you want to define a shorthand abbreviation for a command and its parameters. They also ensure that you consistently run a program with the same parameters each time. Aliases are especially appropriate to use when you have a limited number of parameters you want to consistently use.

Note: When you have many parameters you want to use with a command, define them in a command-line initialization file.

Defining aliases

To define an alias:

1.      System Managers can define global aliases in the files, aliases.ksh and aliases in $GCGROOT/etc directory.  Use aliases if you normally use csh, and aliases.ksh, if you use ksh.

2.      If you wish to create aliases in your local environment, create a file aliases.ksh in your $HOME/ or appropriate location for setting your own aliases and sourcing it separately after sourcing GCG.

3.      Type the alias(es). Aliases use the following syntax:

(csh)
alias abbreviation command_line

(ksh)
alias abbreviation="command_line"

For example, let's say you frequently switch between two graphics devices, an Apple LaserWriter printer and a Tektronix graphics terminal. To create an alias for each device to switch between them quickly and efficiently, you might type the following:

(csh)
% alias lw postscript laserwriter /dev/tty15
% alias tk tektronix tek4207 Term

(ksh)
% alias lw="postscript laserwriter /dev/tty15"
% alias tk="tektronix tek4207 term"

4.      Save and exit the file.

5.      Test the alias to make sure it works. Follow these steps:

Using aliases

To use an alias:

Type the symbol you defined, for example % lw. The program or command runs with the parameters you specified.

Working with shell scripts

[ Previous | Top  ]

What is a shell script?

A shell script is a file that contains UNIX or program commands. It mimics exactly what you would type if you ran the commands interactively. You can use a shell script to execute commands and set up aliases when you log in to the system. For example, your .login (csh) or .profile (ksh) file is a shell script. You also can create shell scripts to submit programs that do not support the -BATch parameter to the batch queue.

Why would I want to use one?

Shell scripts are advantageous for customizing your login environment. For instance, in your .login (csh) or .profile (ksh) file you can define that GCG is automatically initialized, your graphics configuration is initialized. Shell scripts are also useful when you want to submit programs that do not support the -BATch parameter to the batch queue.

Creating a shell script

To create a shell script:

  1. Open a file in the text editor of your choice, for example vi.
  2. Type the appropriate commands and comments. For example, let's say you want to submit the StringSearch program to the batch queue. To do so, you need to create a shell script similar to the following:

(csh)

 (ksh)

a.       Unless your script initializes the package, you cannot use program aliases in a shell script.

b.      Turn off global expansion by typing % set noglob (csh) or % set -f (ksh).

c.       Keep the following guidelines in mind as you create shell scripts:

d.      Include comments to document the function of the commands. Precede the comments with a pound symbol (#). Your comments do not affect how the shell script will run. However, they will help you or anyone else who uses or maintains the shell script.

e.       Do not leave blank lines. They may be interpreted incorrectly and warning messages may appear.

f.        Include a special comment on the first line of the shell script that specifies which shell you want to use. This line should read #!/bin/csh -f (csh) or #!/bin/ksh (ksh).

Note: This shell does not have to be the same as the shell you use to log in.

g.       Extend long commands onto a second line by using a backslash (\) at the end of the first line.

h.       Use command-line control if the program supports it (see "Using Command-Line Control" in this section). If a program does not support command-line control, use input redirection and type the response to each program prompt on a separate line in the order the questions are asked.

For example, the Correspond program does not support command-line control. To create a shell script for this program, you might type the following:

Note: The << tells the shell script to use the information between the two names, in this case eof, as responses to the program prompts.

i.         Use complete directory and file specifications for input to ensure the correct files are accessed. Also, you may want to use the cd (change directory) command to set the appropriate directory of your files.

j.        If you submit the shell script to the batch queue, make sure you include your site's method for initializing GCG. For example

(csh)
 
% source $GCGCOMMANDGCGROOT/gcgstartup

(ksh)
unset GCGNID
% eval . $GCGCOMMAND$GCGROOT/gcgstartup

  1. Save the file and exit the text editor
  2. Test the shell script on a short sequence by running it interactively. Follow these steps:

a.       Type % chmod +x filename, where filename is the name of the shell script, for example % chmod +x stringsearch.csh. (chmod +x adds executable status to the file.)

b.      Type the filename on the command line to run the program(s) interactively, for example, % ./stringsearch.csh. If the shell script does not run without error or as you expect it to, edit the file as necessary and test it again.

Testing a shell script until it works correctly will prevent you from using excess CPU time on one that doesn't work.

TIP - A shell script must include all required parameters to suppress program prompts. You may want to create a shell script, however, in which you can change a parameter from the command line. For example, you may want to change the input file for a program but use the same parameters. To do so, use the $argv[number] (csh) or $number (ksh) shell variable to pass parameters to the shell script. Consider the shell script examples below.

(csh)

 

 (ksh)

To run the shell script, type % ./stringsearch.csh parameter (csh) or % ./stringsearch.ksh parameter (ksh) where parameter is the replacement for the shell variable you used. For example, % ./stringsearch.csh pseudo replaces "$argv[1]" (csh) or "$1" (ksh) and searches for the string "pseudo" in the GenBank database.

Using a shell script

To use a shell script:

Choose from the following.

Note: Check with your system manager to see if this option is supported at your site.

To submit a shell script to the batch queue to run at night, follow these steps:

    1. Use the ‘at’ command to run the shell script at a later time, for example, % at midnight. This places you in the ‘at’ program, and you will not see the operating system prompt appear along the left side of your screen.

      For more information on using the ‘at’ command, type % man at to view the UNIX online help.
    2. Type the name of the shell script you want to run in batch followed by any parameters the shell script allows you to set, for example % ./stringsearch globin, and press <Return>.
    3. Press <Ctrl>d to submit the shell script the batch queue. The operating system prompt returns and the shell script submit itself to the batch queue to run at midnight.

To submit a shell script to run interactively:

    1. If you haven't done so already, make the shell script file executable. To do so, type % chmod +x filename, where filename is the name of the shell script, for example % chmod +x stringsearch.csh. (chmod +x adds executable status to the file.)
    2. Type the filename on the command line to run the program interactively, for example, % stringsearch.csh. The file runs the program with the parameters you specified. If you did not answer all the program prompts, it also will ask you for information.

Your system manager may have specific queues set up to run batch jobs. Ask him/her for assistance in submitting a shell script to the batch queue.

To run a shell script in the background, type % ./filename &, for example % ./stringsearch.csh &. The shell script begins running in the background, leaving your terminal free for other work. For more information, see "Running Programs in the Background" in this section.

[Genhelp | Program Manual | User's Guide | Data Files | Databases | Release Notes ]

Technical Support: support-us@accelrys.com, support-japan@accelrys.com,
or support-eu@accelrys.com

Copyright (c) 1982-2005 Accelrys Inc. All rights reserved.

Licenses and Trademarks: Discovery Studio ®, SeqLab ®, SeqWeb ®, SeqMerge ®, GCG ® and, the GCG logo are registered trademarks of Accelrys Inc.

All other product names mentioned in this documentation may be trademarks, and if so, are trademarks or registered trademarks of their respective holders and are used in this documentation for identification purposes only.

www.accelrys.com/bio