EMBOSS Developers Guide
   Next

EMBOSS Developers Guide

Bioinformatics Programming

Dr. Jon Ison

Senior Scientific Officer
EMBL European Bioinformatics Institute

EMBL-EBI, Wellcome Trust Genome Campus, Hinxton, Cambridge, CB10 1SD, UK

Mr. Peter Rice

Group Leader
EMBL European Bioinformatics Institute

EMBL-EBI, Wellcome Trust Genome Campus, Hinxton, Cambridge, CB10 1SD, UK

Dr. Alan Bleasby

Senior Scientific Officer
EMBL European Bioinformatics Institute

EMBL-EBI, Wellcome Trust Genome Campus, Hinxton, Cambridge, CB10 1SD, UK

Revision History
August 2009The EMBOSS Developers
Version 1

Table of Contents

Acknowledgements
1. EMBOSS Acknowledgements
1.1. Funding Bodies
1.2. Contributors
2. EMBOSS Developers Guide Acknowledgements
Preface
1. Introduction to EMBOSS
2. Developing EMBOSS
3. Key Features for Developers
3.1. Support for developers
3.2. C programming library development
4. About the Authors
5. How To Cite EMBOSS
Conventions
1. Command Line Sessions and Commands
2. Program Listings and Code
3. Other Conventions
4. Special Text Blocks
Welcome to the EMBOSS Developers Manual
1. Chapter 1. Getting Started
2. Chapter 2. Your First EMBOSS Application
3. Chapter 3. Software Development under EMBOSS
4. Chapter 4. ACD File Development
5. Chapter 5. C Programming
6. Chapter 6. Programming with AJAX
7. Chapter 7. Quality Assurance
8. Chapter 8. Application Documentation
9. Chapter 9. A Complete Application
10. Chapter 10. Incorporating Third-party Applications
11. Appendix A. ACD Syntax Reference
12. Appendix B. Libraries Reference
13. Appendix C. C Coding Standards
14. Appendix D. Code Documentation Standards
15. Appendix E. Resources
1. Getting Started
1.1. Licence Information
1.1.1. GPL
1.1.2. LGPL
1.1.3. Licensing under EMBASSY
1.2. Installation of CVS (Developers) Release
1.2.1. Downloading via CVS
1.2.2. Keeping up-to-date with CVS
1.2.3. Configuration
1.2.4. Compilation
1.2.4.1. Static and Dynamic Compilation
1.2.5. Setting your PATH
1.2.6. Testing all is Well
1.2.7. Database Setup
1.2.8. EMBASSY Packages
1.3. Developer Documentation
1.3.1. Application Documentation
1.3.2. Library Documentation
1.3.2.1. AJAX Library Documentation
1.3.2.2. NUCLEUS Library Documentation
1.3.3. Navigating the Libraries
1.3.3.1. Library File Documentation
1.3.3.2. Function Documentation
1.3.3.3. Object (C data Structure) Documentation
1.3.4. The Source Code
1.3.4.1. Navigating the Source Code using SRS
1.3.5. Demonstration Applications
1.3.6. Programming Guides
1.3.7. AJAX Command Definition (ACD) Developers Guide and Syntax
1.3.8. C Coding Standards and Guidelines
1.3.9. Quality Assurance Guidelines
1.3.10. Code and Application Documentation Standards
1.3.11. EMBOSS Software Development Course
1.4. Project Mailing Lists
1.4.1. User Mailing List
1.4.2. Developer Mailing List
1.4.3. Announcements Mailing List
1.4.4. Mail Archives
1.4.4.1. User Mailing List Archive
1.4.4.2. Developer Mailing List Archive
1.5. Contributing Software to EMBOSS
1.5.1. Please Submit your Code!
1.5.2. Types of Code Submission
1.5.3. Known Required Developments
1.5.3.1. EMBOSS Feature Requests and Bug Reports
2. Your First EMBOSS Application
2.1. helloworld in C
2.2. helloworld in EMBOSS
2.2.1. Planning and Design
2.2.2. Writing the ACD File
2.2.3. Testing the ACD file
2.2.4. Writing the Source Code
2.2.5. Integration (Adding the Application to EMBOSS)
2.2.6. Compilation
2.2.7. Debugging
2.2.8. Testing
2.2.9. Documentation
2.3. Modifying helloworld
2.3.1. Modifying the ACD File
2.3.2. Modifying the C Source Code
2.3.3. Running the Program
2.3.4. Qualifiers and Parameters
2.3.5. Adding an Integer
2.3.6. Parameters and Qualifiers Revisited
2.4. Modifying matcher
2.4.1. Planning
2.4.2. Editing the ACD Files
2.4.3. Editing the C Source File
2.4.4. Compilation
2.4.5. Testing All Is Well
2.4.6. Further Developments
2.5. String Handling
2.5.1. stringplay.acd
2.5.2. stringplay.c
2.5.3. Compilation and Testing
2.5.4. Adding Functionality
2.5.4.1. String Memory Management
3. Software Development under EMBOSS
3.1. EMBOSS Programming
3.1.1. Introduction
3.1.2. Inbuilt Functionality
3.1.2.1. Support for Biological Datatypes
3.1.2.2. Support for Common File Formats
3.1.2.3. Simple Database Configuration
3.1.2.4. Command Line Handling
3.1.2.5. Command Line Qualifiers
3.1.2.6. Sequence and Sequence Feature Specification
3.1.3. Before you start Coding
3.1.4. Basic Steps to Development
3.1.5. Project Management
3.1.5.1. Models for Releasing Software
3.1.5.2. Software Life Cycle Models
3.1.5.3. User Requirements
3.1.6. Planning
3.1.6.1. Application Development
3.1.6.2. Library Development
3.1.7. ACD File Development
3.1.8. C Source Code Development
3.1.8.1. Coding Standards
3.1.8.2. Application Development
3.1.8.3. Library Development
3.1.9. Integration and Compilation
3.1.10. Debugging
3.1.11. Quality Assurance Testing
3.1.12. Documentation
3.1.13. Distribution
3.1.14. Maintenance, Support and Training
3.2. Integration and Compilation
3.2.1. Using myemboss for Application Development
3.2.2. Adding New EMBOSS Applications
3.2.3. Adding New EMBASSY Applications
3.2.4. Adding a New EMBASSY Package
3.2.4.1. Directory Structure
3.2.4.2. Editing the Makefile.am Files
3.2.4.3. Editing the configure.in Files
3.2.5. Adding New Functions and Datatypes
3.2.6. Adding New Library Files
3.3. Debugging
3.3.1. Direct Debugging
3.3.2. AJAX Debugging Functions
3.3.3. Controlling Debugging Behaviour
3.3.4. Debuggers
3.3.5. Tracing Memory Problems
4. ACD File Development
4.1. Introduction to ACD File Development
4.1.1. ACD Files
4.1.2. ACD General Syntax
4.1.2.1. ACD File Names
4.1.2.2. Whitespace
4.1.2.3. Comments
4.1.3. ACD Definitions
4.1.4. Parameters and Qualifiers
4.1.4.1. Prompting Behaviour and Default Values
4.1.4.2. Help Information
4.1.4.3. Examples
4.1.5. ACD File Sections
4.1.5.1. Sections in an ACD File
4.1.5.2. Input section
4.1.5.3. Required section
4.1.5.4. Additional section
4.1.5.5. Advanced section
4.1.5.6. Output section
4.1.5.7. Example
4.1.5.8. Standard File Sections (sections.standard file)
4.2. Application Definition
4.2.1. Application Definition Format
4.2.2. Application Attributes
4.2.3. Application Documentation
4.2.3.1. Application Keywords File (keywords.standard)
4.2.4. Application Groups
4.2.4.1. Application Group Names File (groups.standard)
4.3. Data Definition
4.3.1. Data Definition Format
4.3.2. Parameter Naming Conventions
4.3.3. ACD Datatypes
4.3.3.1. Groupings of ACD Datatypes
4.3.3.2. Simple ACD Datatypes
4.3.3.3. Input ACD Datatypes
4.3.3.4. Output ACD Datatypes
4.3.3.5. Selection ACD Datatypes
4.3.3.6. Graphics ACD Datatypes
4.3.4. Types of Data Attributes
4.3.5. Global Attributes
4.3.5.1. Parameters and Qualifiers
4.3.5.2. User Prompting
4.3.5.3. Datatype Definition
4.3.5.4. Help Information and Documentation
4.3.5.5. Hints for GUIs
4.3.5.6. For use by SOAPLAB
4.3.6. Datatype-specific Attributes
4.3.6.1. Attributes for Simple ACD Datatypes
4.3.6.2. Attributes for Input ACD Datatypes
4.3.6.3. Attributes for Output ACD Datatypes
4.3.6.4. Attributes for Selection ACD Datatypes
4.3.6.5. Attributes for Graphics ACD Datatypes
4.3.7. Attributes for Datatype-associated Qualifiers
4.3.8. Introduction to Calculated Attributes
4.3.8.1. Retrieving Values of Calculated Attributes
4.3.8.2. Sequence Calculated Attributes
4.3.8.3. Feature Calculated Attributes
4.4. Operations
4.4.1. Types of Operation
4.4.2. General Operation Syntax
4.4.2.1. Arithmetic Operators
4.4.2.2. Logical Operators
4.4.2.3. Equality Operators
4.4.2.4. Conditional Operators
4.4.3. Retrieving Data Values in ACD Files.
4.4.4. Calculations and Tests
4.4.4.1. Arithmetic Operations
4.4.4.2. Tests for Equality
4.4.4.3. Boolean Tests
4.4.5. Conditional Statements
4.4.5.1. Unary Conditional Statements
4.4.5.2. Ternary Conditional
4.4.5.3. Case Conditional
4.4.6. Use of Variables
4.4.6.1. Automatic Variables
4.5. Controlling the Prompt
4.5.1. Introduction
4.5.2. Parameters
4.5.3. Qualifiers
4.5.4. Defaults
4.5.5. Maxima and Minima
4.5.6. Setting the Prompts
4.5.7. Negation
4.5.8. Boolean Datatypes
4.5.8.1. Prompting for boolean Values
4.6. ACD Utilities
4.6.1. Introduction
4.6.2. Using the Utilities
4.6.3. Global Qualifiers
4.6.4. Description of Utilities
4.6.4.1. acdc
4.6.4.2. acdtrace
4.6.4.3. acdvalid
4.6.4.4. acdlog
4.6.4.5. acdpretty
4.6.4.6. acdtable
4.6.5. Use of entrails
5. C Programming
5.1. Basic Datatypes
5.1.1. Fundamental C Datatypes
5.1.2. Fundamental AJAX Datatypes
5.1.2.1. Integer Types
5.1.2.2. Other AJAX Types
5.1.3. Derived Types
5.1.4. Storage Class and Linkage
5.2. C Pointers Primer
5.2.1. Pointer Basics
5.2.1.1. Declaring Pointers
5.2.2. Pointers to Pointers
5.3. Objects (C Data Structures)
5.3.1. Object Definition
5.3.2. Object Functions
5.4. Memory Management in EMBOSS
5.4.1. Introduction to Memory Management
5.4.1.1. General memory management macros
5.4.1.2. Object memory management macros
5.4.1.3. Object constructor and destructor functions
5.4.1.4. Failsafe object construction
5.4.1.5. Dynamic objects
5.4.1.6. EMBOSS is free of arbitrary limits
5.4.2. General Memory Management
5.4.2.1. General Macros
5.4.2.2. Object Macros
5.4.2.3. Arrays of Fundamental C-type Datatypes
5.4.2.4. Memory Leaks
5.4.3. Object Memory Management
5.4.3.1. Introduction
5.4.3.2. Object Construction
5.4.3.3. Object Destruction
5.5. Programming with Objects
5.5.1. An Example Object: AjPPdbtosp
5.5.1.1. Object Definition
5.5.1.2. Object Construction
5.5.1.3. Object Destruction
5.5.1.4. Usage Example
5.5.2. AJAX Dynamic String Object
5.5.2.1. Introduction
5.5.2.2. String Definition
5.5.2.3. String Construction
5.5.2.4. String Destruction
5.5.2.5. String Functions
5.5.3. AJAX Dynamic Array Objects
5.5.3.1. Object Definition
5.5.3.2. AjPInt Construction and Destruction
5.5.3.3. AjPInt2d Construction and Destruction
5.5.3.4. AjPInt2d Putting and Getting Array Elements
6. Programming with AJAX
6.1. Demonstration Applications
6.2. Programming Guides
6.2.1. AJAX
6.2.2. NUCLEUS
6.3. Handling ACD Files
6.3.1. Introduction
6.3.2. Program Initialisation
6.3.3. Retrieving ACD Values
6.3.4. Alternative ACD Retrieval Functions
6.3.5. Exiting Cleanly
6.4. Handling "Simple" ACD Datatypes
6.4.1. Introduction
6.4.2. AJAX Library Files
6.4.3. ACD Datatypes
6.4.4. ACD Data Definition
6.4.4.1. integer
6.4.4.2. float
6.4.4.3. boolean
6.4.4.4. toggle
6.4.4.5. string
6.4.4.6. array
6.4.4.7. range
6.4.4.8. Parameter Name
6.4.4.9. Common Attributes
6.4.5. AJAX Datatypes
6.4.6. ACD File Handling
6.4.6.1. Retrieval of "Simple" ACD Datatypes
6.4.6.2. Processing Command line Options and ACD Attribute
6.4.6.3. Memory Management
6.4.7. Object Memory Management
6.4.7.1. Default Object Construction
6.4.7.2. Default Object Destruction
6.4.7.3. Alternative Object Construction and Loading
6.4.8. Getting Range Object Elements
6.4.9. Querying Range Object Properties
6.4.10. Sequence Manipulation Functions
6.4.11. String Manipulation Functions
6.5. Handling Strings
6.5.1. Introduction
6.5.2. AJAX Library Files
6.5.3. ACD Datatypes
6.5.4. ACD Data Definition
6.5.4.1. Parameter Name
6.5.4.2. Common Attributes
6.5.5. AJAX Datatypes
6.5.6. ACD File Handling
6.5.6.1. Input String Retrieval
6.5.6.2. Processing Command line Options and ACD Attribute
6.5.7. String Object Memory Management
6.5.7.1. Default Object Construction
6.5.7.2. Default Object Destruction
6.5.7.3. Alternative Object Construction and Loading
6.5.8. String Referencing and Dereferencing Functions
6.5.9. String Assignment Functions
6.5.10. String Combination Functions
6.5.10.1. String append functions
6.5.10.2. String Join Functions
6.5.10.3. String Insert Functions
6.5.10.4. String Paste Functions
6.5.11. String Cut Functions
6.5.11.1. Simple cut functions
6.5.11.2. Removing characters from a string
6.5.11.3. Retaining characters in a string
6.5.11.4. String trimming functions
6.5.12. String Substitution Functions
6.5.13. String Query Functions
6.5.14. String Properties and Character Retrieval Functions
6.5.15. String Conversion Functions
6.5.16. String Formatting Functions
6.5.17. String Comparison Functions
6.5.18. String Search Functions
6.5.19. String Parsing Functions
6.5.20. String Iteration
6.5.21. String Tokenisation
6.5.22. Handling C-type (char *) Strings
6.5.22.1. C-type string constructor and destructor functions
6.5.22.2. C-type string comparison functions
6.5.23. Handling String Formatting
6.6. Handling Sequence Patterns
6.6.1. Introduction
6.6.2. AJAX Library Files
6.6.3. ACD Datatypes
6.6.4. ACD Data Definition
6.6.4.1. regexp
6.6.4.2. pattern
6.6.4.3. Parameter Name
6.6.4.4. Common Attributes
6.6.5. AJAX Datatypes
6.6.6. ACD File Handling
6.6.6.1. Input Pattern Retrieval
6.6.6.2. Alternative ACD Retrieval Functions
6.6.6.3. Processing Command line Options and ACD Attributes
6.6.6.4. Memory Management
6.6.7. Pattern Object Memory Management
6.6.7.1. Default Object Construction
6.6.7.2. Default Object Destruction
6.6.7.3. Alternative Object Construction and Loading
6.6.8. Read Functions
6.6.9. Getting Elements of Objects
6.6.10. Setting Elements of Objects
6.6.11. Debugging Functions
6.6.12. Miscellaneous Functions
6.7. Handling Sequences
6.7.1. Introduction
6.7.2. AJAX Library Files
6.7.3. ACD Datatypes
6.7.4. ACD Data Definition
6.7.4.1. Parameter Name
6.7.4.2. Common Attributes
6.7.5. AJAX Datatypes
6.7.6. ACD File Handling
6.7.6.1. Input Sequence Retrieval
6.7.6.2. Output Sequence Stream Retrieval
6.7.6.3. Alternative ACD Retrieval Functions
6.7.6.4. Processing Command line Options and ACD Attributes
6.7.6.5. Writing Sequences
6.7.6.6. Memory and File Management
6.7.7. Sequence Object Memory Management
6.7.7.1. Default Object Construction
6.7.7.2. Default Object Destruction
6.7.7.3. Alternative Object Construction and Loading
6.7.8. Getting and Setting Elements
6.7.8.1. Setting Single Values
6.7.8.2. Other Assignment Functions
6.7.8.3. Getting Single Values
6.7.9. Testing Sequence Properties
6.7.10. Calculating Sequence Properties
6.7.11. Sequence String Functions
6.7.12. Processing Sequences
6.7.13. Sequence Type Validation
6.7.14. Sequence Conversion
6.7.15. Handling Sequence Translation
6.7.16. Handling IUB Base Codes
6.7.16.1. Unambiguous codes
6.7.16.2. Ambiguity codes
6.7.16.3. Processing an IUB Base Code
6.7.16.4. Conversion of Base and Amino Acid Codes
6.7.17. DNA Calculations
6.7.17.1. General Functions for DNA Melting
6.7.17.2. Calculating DNA Melting and Annealing Temperatures and Energies
6.8. Handling Sequence Translation
6.8.1. Introduction
6.8.2. AJAX Library Files
6.8.3. ACD Datatypes
6.8.4. ACD Data Definition
6.8.5. AJAX Datatypes
6.8.6. ACD File Handling
6.8.6.1. Sequence or Menu Selection Retrieval
6.8.6.2. Memory Management
6.8.7. Translation Object Memory Management
6.8.7.1. Default Object Construction
6.8.7.2. Default Object Destruction
6.8.8. Translation
6.8.9. Miscellaneous Functions
6.9. Handling Features
6.9.1. Introduction
6.9.2. AJAX Library Files
6.9.3. ACD Datatypes
6.9.4. ACD Data Definition
6.9.4.1. Parameter Name
6.9.4.2. Common Attributes
6.9.5. AJAX Datatypes
6.9.6. ACD File Handling
6.9.6.1. Input Feature Retrieval
6.9.6.2. Output Feature Retrieval
6.9.6.3. Processing Command line Options and ACD Attributes
6.9.6.4. Memory Management
6.9.7. Memory Management
6.9.7.1. Default Object Construction
6.9.7.2. Default Object Destruction
6.9.7.3. Example
6.9.7.4. Alternative Object Construction and Loading
6.9.8. Reading Features
6.9.9. Writing Features
6.9.10. Output Feature Table Functions
6.9.11. Retrieving Elements of a Feature Object
6.9.12. Retrieving Elements of a Feature Table Object
6.9.13. Setting Elements of a Feature Object
6.9.14. Setting Elements of a Feature Table Object
6.9.15. Functions for Handling Feature Tags
6.9.16. Querying Properties of Features
6.9.17. Querying Properties of Feature Tables
6.9.18. Processing Features
6.9.19. Processing Feature Tables
6.9.20. Miscellaneous Functions
6.10. Handling Comparison Matrices
6.10.1. Introduction
6.10.2. AJAX Library Files
6.10.3. ACD Datatypes
6.10.4. ACD Data Definition
6.10.4.1. Parameter Name
6.10.4.2. Common Attributes
6.10.5. AJAX Datatypes
6.10.6. ACD File Handling
6.10.6.1. Input Comparison Matrix Retrieval
6.10.6.2. Output Comparison Matrix Retrieval
6.10.6.3. Processing Command line Options and ACD Attributes
6.10.6.4. Memory and File Management
6.10.7. Matrix Object Memory Management
6.10.7.1. Default Object Construction
6.10.7.2. Default Object Destruction
6.10.7.3. Alternative Object Construction and Loading
6.10.8. Functions for Retrieving the Properties of a Matrix.
6.10.9. Functions for Indexing a Matrix
6.10.10. Sequence Conversion
6.11. Handling Alignments
6.11.1. Introduction
6.11.2. AJAX Library Files
6.11.3. ACD Datatypes
6.11.4. ACD Data Definition
6.11.4.1. Parameter Name
6.11.4.2. Common Attributes
6.11.5. AJAX Datatypes
6.11.6. ACD File Handling
6.11.6.1. Input Alignment Retrieval
6.11.6.2. Output Alignment Retrieval
6.11.6.3. Memory and File Management
6.11.7. Alignment Object Memory Management
6.11.7.1. Default Object Construction
6.11.7.2. Default Object Destruction
6.11.7.3. Alternative Object Construction and Loading
6.11.8. Writing Alignments
6.11.9. Retrieving Elements of an Alignment Object
6.11.10. Setting Elements of an Alignment Object
6.11.11. Miscellaneous Functions
6.12. Handling Phylogenetic Data
6.12.1. Introduction
6.12.2. AJAX Library Files
6.12.3. AJAX Datatypes
6.12.4. ACD Datatypes
6.12.5. ACD Data Definition
6.12.5.1. discretestates
6.12.5.2. distances
6.12.5.3. frequencies
6.12.5.4. properties
6.12.5.5. tree
6.12.5.6. outdiscrete
6.12.5.7. outdistance
6.12.5.8. outfreq
6.12.5.9. outproperties
6.12.5.10. outtree
6.12.5.11. Parameter Name
6.12.5.12. Common Attributes
6.12.6. ACD File Handling
6.12.6.1. Phylogenetic Data Retrieval
6.12.6.2. Processing Command line Options and ACD Attributes
6.12.6.3. Memory and File Management
6.12.7. Phylogenetic Object Memory Management
6.12.7.1. Default Object Construction
6.12.7.2. Default Object Destruction
6.12.7.3. Alternative Object Construction and Loading
6.12.8. Reading Phylogenetic Data from File
6.12.9. Getting Elements of Phylogenetic Objects
6.12.10. Debug Functions
6.13. Handling Codon Usage Tables
6.13.1. Introduction
6.13.2. AJAX Library Files
6.13.3. ACD Datatypes
6.13.4. ACD Data Definition
6.13.4.1. Parameter Name
6.13.4.2. Common Attributes
6.13.5. AJAX Datatypes
6.13.6. ACD File Handling
6.13.6.1. Input Codon Usage Table Retrieval
6.13.6.2. Output Codon Usage Table Retrieval
6.13.6.3. Processing Command line Options and ACD Attributes
6.13.6.4. Memory and File Management
6.13.7. Codon Usage Table Object Memory Management
6.13.7.1. Default Object Construction
6.13.7.2. Default Object Destruction
6.13.7.3. Alternative Object Construction and Loading
6.13.8. Reading and Writing Codon Usage Tables
6.13.8.1. Reading a codon usage table
6.13.8.2. Writing a codon usage table
6.13.9. Getting and Setting Elements
6.13.9.1. Clearing a codon usage table
6.13.10. Calculated Properties
6.13.11. Back Translation
6.13.12. Miscellaneous Functions
6.14. Handling Files
6.14.1. Introduction
6.14.2. AJAX Library Files
6.14.3. ACD Datatypes
6.14.4. ACD Data Definition
6.14.4.1. infile
6.14.4.2. filelist
6.14.4.3. datafile
6.14.4.4. dirlist
6.14.4.5. directory
6.14.4.6. outfile
6.14.4.7. outdata
6.14.4.8. outdir
6.14.4.9. directory
6.14.4.10. Parameter Names
6.14.4.11. Common Attributes
6.14.5. AJAX Datatypes
6.14.6. ACD File Handling
6.14.6.1. Input File Retrieval
6.14.6.2. Output File Retrieval
6.14.6.3. Alternative ACD Retrieval Functions
6.14.6.4. Processing Command line Options and ACD Attributes
6.14.6.5. Memory and File Management
6.14.7. File and Directory Object Memory Management
6.14.7.1. Default Object Construction
6.14.7.2. Default Object Destruction
6.14.7.3. Alternative Object Construction and Loading
6.14.8. Reading from File
6.14.8.1. Buffered files
6.14.9. Writing to Files
6.14.9.1. General files
6.14.9.2. Binary files
6.14.9.3. Buffered files
6.14.10. Manipulating Files
6.14.11. Querying Properties of Files
6.14.11.1. Basic Properties
6.14.11.2. Output files
6.14.11.3. Buffered files
6.14.11.4. Directories
6.14.12. Querying and Manipulating File and Directory Names
6.15. Handling Application Reports
6.15.1. Introduction
6.15.2. AJAX Library Files
6.15.3. AJAX Datatypes
6.15.4. ACD Datatypes
6.15.5. ACD Data Definition
6.15.5.1. Parameter Name
6.15.5.2. Common Attributes
6.15.6. ACD File Handling
6.15.6.1. Report Retrieval
6.15.6.2. Processing Command line Options and ACD Attributes
6.15.6.3. Memory and File Management
6.15.7. Report Object Memory Management
6.15.7.1. Default Object Construction
6.15.7.2. Default Object Destruction
6.15.7.3. Alternative Object Construction and Loading
6.15.8. Preparing a Report
6.15.9. Example Report Application
6.15.9.1. ACD File
6.15.9.2. C Source Code
6.15.10. Report File Management
6.15.11. Setting Elements of a Report Object
6.15.12. Getting Elements of a Report Object
6.15.13. Debugging Report Objects
6.16. Handling Lists
6.16.1. Introduction
6.16.2. AJAX Library Files
6.16.3. ACD Datatypes
6.16.4. AJAX Datatypes for Handling Lists
6.16.5. Types of List
6.16.6. List Object Memory Management
6.16.6.1. Default Object Construction
6.16.6.2. Default Object Destruction
6.16.6.3. Managing Node Data
6.16.6.4. Alternative Object Construction and Loading
6.16.7. List Node Retrieval
6.16.8. List Iteration
6.16.8.1. List iterator construction
6.16.8.2. List iteration
6.16.8.3. List iterator destruction
6.16.9. Querying a List
6.16.10. List Editing
6.16.10.1. Adding nodes to a List
6.16.10.2. Removing nodes from a list
6.16.10.3. Reversing the order of nodes in a list
6.16.10.4. Garbage collection
6.16.11. List Sorting
6.16.11.1. String comparison functions
6.16.12. List Conversion
6.16.13. List Node Functions
6.17. Handling Arrays
6.17.1. Introduction
6.17.2. AJAX Library Files
6.17.3. AJAX Datatypes
6.17.3.1. char arrays
6.17.3.2. short arrays
6.17.3.3. unsigned int arrays
6.17.3.4. int arrays
6.17.3.5. float arrays
6.17.3.6. long arrays
6.17.3.7. double arrays
6.17.4. ACD Datatypes
6.17.5. ACD Data Definition
6.17.5.1. Parameter Name
6.17.5.2. Common Attributes
6.17.6. ACD File Handling
6.17.6.1. Input Array Retrieval
6.17.6.2. Processing Command line Options and ACD Attributes
6.17.6.3. Memory Management
6.17.7. Names of Functions
6.17.8. Array Object Memory Management
6.17.8.1. Default Object Construction
6.17.8.2. Default Object Destruction
6.17.8.3. Alternative Object Construction and Loading
6.17.9. Getting and Setting Array Elements
6.17.10. Sorting Arrays
6.17.11. Retrieving a C-type Array
6.18. Handling Tables
6.18.1. Introduction
6.18.2. AJAX Library Files
6.18.3. ACD Datatypes
6.18.4. AJAX Datatypes
6.18.5. Table Object Memory Management
6.18.5.1. Default Object Construction
6.18.5.2. Default Object Destruction
6.18.5.3. Alternative Object Construction and Loading
6.18.6. Table Hash Functions
6.18.7. Table Comparison Functions
6.18.8. Table Edit Functions
6.18.9. Table Query Functions
6.18.10. Table Map Functions
6.18.11. Print Functions
6.19. Handling Menus
6.19.1. Introduction
6.19.2. AJAX Library Files
6.19.3. ACD Datatypes
6.19.4. ACD Data Definition
6.19.4.1. list menu
6.19.4.2. selection menu
6.19.4.3. Parameter Name
6.19.4.4. Common Attributes
6.19.5. AJAX Datatypes
6.19.6. ACD File Handling
6.19.6.1. Menu Retrieval
6.19.6.2. Alternative ACD Retrieval Functions
6.19.6.3. Processing Command line Options and ACD Attributes
6.19.6.4. Memory Management
6.20. Handling Graphical Output
6.20.1. Introduction
6.20.2. AJAX Library Files
6.20.3. ACD Datatypes
6.20.4. ACD Data Definition
6.20.4.1. Parameter Name
6.20.4.2. Common Attributes
6.20.5. Program Initialisation
6.20.6. AJAX Datatypes
6.20.7. ACD File Handling
6.20.7.1. Output Graphics Retrieval
6.20.7.2. Processing Command line Options and ACD Attributes
6.20.7.3. Memory and File Management
6.20.8. Graphics Object Memory Management
6.20.8.1. Default Object Construction
6.20.8.2. Default Object Destruction
6.20.9. Graphics File Management
6.20.10. Initialisation Functions
6.20.11. Creating Windows
6.20.12. Drawing Functions
6.20.13. Setting Graphical Elements to Render
6.20.14. Retrieving Properties of Graphs
6.20.15. Calculated Properties of Graphs
6.20.16. Graph Debug Functions
6.20.17. Histograms
6.21. Handling Maths
6.21.1. Introduction
6.21.2. AJAX Library Files
6.21.3. ACD Datatypes
6.21.4. AJAX Datatypes
6.21.5. Conversion Functions
6.21.6. Random Number Functions
6.21.7. Rounding
6.21.8. Miscellaneous Functions
6.22. Handling System Code
6.22.1. Introduction
6.22.2. AJAX Library Files
6.22.3. ACD Datatypes
6.22.4. AJAX Datatypes
6.22.5. System Calls
6.22.6. Application Arguments
6.22.7. Cast Functions
6.22.8. File Functions
6.22.9. C Function Wrappers
6.22.10. Functions from ajutil.c/h
6.23. Handling Exception Messages
6.23.1. Introduction
6.23.2. AJAX Library Files
6.23.3. ACD Datatypes
6.23.4. AJAX Datatypes for Handling Messages
6.23.5. Message Functions
6.23.6. Querying the Status of Message Handling
6.23.7. Interacting with the user
6.23.8. Miscellaneous functions
7. Quality Assurance
7.1. General Quality Assurance
7.2. Application Quality Assurance
7.2.1. Test Records
7.2.1.1. ID ApplicationName-Tag
7.2.1.2. AA ApplicationName
7.2.1.3. AB PackageName
7.2.1.4. AP ApplicationName
7.2.1.5. AQ ApplicationName
7.2.1.6. CC comment
7.2.1.7. CL command
7.2.1.8. DI directory
7.2.1.9. DF FileName
7.2.1.10. DL directive
7.2.1.11. ER ErrorCode
7.2.1.12. FI FileName
7.2.1.13. FC [<=>] NumberLines
7.2.1.14. FP count / regexp /
7.2.1.15. FZ [<=>] FileSize
7.2.1.16. IC text
7.2.1.17. IN UserInput
7.2.1.18. OC text
7.2.1.19. PP command
7.2.1.20. QQ command
7.2.1.21. RQ RequiredApps
7.2.1.22. TI seconds
7.2.1.23. UC text
7.2.1.24. ##
7.2.2. Writing an Application QA Test
7.2.2.1. Location of test data
7.2.3. Running an Application QA Test
7.2.3.1. Example test
7.2.4. Useful Files and Directories
8. Application Documentation
8.1. Application Documentation Standards
8.1.1. Introduction
8.1.2. Application Documentation
8.1.2.1. ACD File Documentation
8.1.2.2. Sections of Application Documentation
8.1.2.3. Application Documentation Process
8.1.3. EMBASSY Package Documentation
8.1.3.1. Sections of EMBASSY Package Documentation
8.1.3.2. EMBASSY Package Documentation Process
9. A Complete Application
9.1. The ACD File (seqret.acd)
9.1.1. Application Definition
9.1.2. ACD File Sections
9.1.3. Data Definitions
9.1.4. Attributes
9.2. The C Source Code (seqret.c)
9.2.1. Variable Declarations
9.2.2. ACD File and Command line Processing
9.2.3. Retrieving Values from the ACD File
9.2.4. Sequence Handling
9.2.5. Exiting Cleanly
9.3. Inbuilt Functionality
9.4. Documentation (seqret.html)
9.5. Quality Assurance Tests
10. Incorporating Third-party Applications
10.1. Benefits to Incorporating Applications into EMBOSS
10.2. Wrappers and Ports
10.3. Pros and Cons
10.3.1. Development Cost
10.3.2. Flexibility
10.3.3. Limitations
10.3.4. Maintenance Cost
10.3.5. Support Cost
10.3.6. Perceived Risk
10.3.7. Summary
10.4. How To Wrap Third Party Applications
10.4.1. Planning and Design
10.4.2. ACD File Development
10.4.3. C Source Code Development
10.4.4. Quality Assurance Testing
10.4.5. Documentation
10.4.6. Integration
10.5. HMMER Wrapper: Overview
10.6. HMMER Wrapper: hmmbuild
10.6.1. HMMER Wrapper: ehmmbuild.acd
10.6.1.1. Application Definition and Inputs
10.6.1.2. Required Section
10.6.1.3. Advanced Section
10.6.1.4. Output Section
10.6.2. HMMER Wrapper: ehmmbuild.c
10.6.2.1. Header Documentation
10.6.2.2. main() Function
10.6.2.3. Processing the ACD File
10.6.2.4. Housekeeping and File Format Handling
10.6.2.5. Building the Command line
10.6.2.6. Invoking the Application
10.7. HMMER Wrapper: hmmalign
10.7.1. HMMER Wrapper: hmmalign.acd
10.7.1.1. Input Section
10.7.1.2. Output Section
10.7.2. HMMER Wrapper: ehmmalign.c
10.7.2.1. Documentation Header
10.7.2.2. main() Function, Housekeeping and ACD File Processing
10.7.2.3. File Format Handling
10.7.2.4. Building the Command line
10.7.2.5. Invoking the Application
10.8. Reducing The Length Of The Command Line
10.9. How To Port Third Party Applications
10.10. HMMER port
10.10.1. HMMER Port: ohmmalign.acd
10.10.2. HMMER Port: ohmmalign.c
10.10.2.1. Heading Code
10.10.2.2. main() Function Variable Declarations
10.10.2.3. ACD File Processing
10.10.2.4. Handling Input Data
10.10.2.5. Exiting Cleanly
10.11. Summary
A. ACD Syntax Reference
A.1. Introduction to ACD Syntax
A.1.1. General Syntax
A.1.1.1. Whitespace
A.1.1.2. Comments
A.1.2. ACD Definitions
A.1.2.1. Application Definition
A.1.2.2. Data Definition
A.1.3. Parameter Naming Conventions
A.1.3.1. General Conventions
A.1.3.2. Datatype-specific Conventions
A.1.3.3. Validated Parameter Names
A.1.4. Types of Attributes
A.1.5. Parameters and Qualifiers
A.1.6. ACD File Sections
A.1.6.1. Validation of Sections
A.2. Datatypes
A.2.1. Description of Simple ACD Datatypes
A.2.1.1. array
A.2.1.2. boolean
A.2.1.3. integer
A.2.1.4. float
A.2.1.5. range
A.2.1.6. regexp
A.2.1.7. pattern
A.2.1.8. string
A.2.1.9. toggle
A.2.2. Description of Input ACD Datatypes
A.2.2.1. codon
A.2.2.2. cpdb
A.2.2.3. datafile
A.2.2.4. directory
A.2.2.5. dirlist
A.2.2.6. discretestates
A.2.2.7. distances
A.2.2.8. features
A.2.2.9. filelist
A.2.2.10. frequencies
A.2.2.11. infile
A.2.2.12. matrix
A.2.2.13. matrixf
A.2.2.14. properties
A.2.2.15. scop
A.2.2.16. sequence
A.2.2.17. seqall
A.2.2.18. seqset
A.2.2.19. seqsetall
A.2.2.20. tree
A.2.3. Description of Output ACD Datatypes
A.2.3.1. align
A.2.3.2. featout
A.2.3.3. outcodon
A.2.3.4. outcpdb
A.2.3.5. outdata
A.2.3.6. outdir
A.2.3.7. outdiscrete
A.2.3.8. outdistance
A.2.3.9. outfile
A.2.3.10. outfileall
A.2.3.11. outfreq
A.2.3.12. outmatrix
A.2.3.13. outmatrixf
A.2.3.14. outproperties
A.2.3.15. outscop
A.2.3.16. outtree
A.2.3.17. report
A.2.3.18. seqout
A.2.3.19. seqoutall
A.2.3.20. seqoutset
A.2.4. Description of Selection ACD Datatypes
A.2.4.1. list
A.2.4.2. selection
A.2.5. Description of Graphics ACD Datatypes
A.2.5.1. Graph
A.2.5.2. graphxy
A.3. Application Attributes
A.3.1. documentation:
A.3.2. groups:
A.3.3. keywords:
A.3.4. gui:
A.3.5. batch:
A.3.6. embassy:
A.3.7. external:
A.3.8. cpu:
A.3.9. supplier:
A.3.10. version:
A.3.11. nonemboss:
A.3.12. executable:
A.3.13. template:
A.3.14. comment:
A.4. Global Attributes
A.4.1. Introduction
A.4.2. Global Attributes Table
A.4.3. Parameters and Qualifiers
A.4.3.1. parameter: "Boolean" ("N")
A.4.3.2. standard: "Boolean" ("N")
A.4.3.3. additional: "Boolean" ("N")
A.4.4. User Prompting
A.4.4.1. information: "String" ("")
A.4.4.2. code: "String" ("")
A.4.4.3. prompt: "String" ("")
A.4.5. Datatype Definition
A.4.5.1. knowntype: "String" ("")
A.4.5.2. default: "Value" ("")
A.4.5.3. relations: "String" ("")
A.4.5.4. outputmodifier: "Boolean" ("N")
A.4.5.5. missing: "Boolean" ("N")
A.4.6. Help Information and Documentation
A.4.6.1. help: "String" ("")
A.4.6.2. valid: "String" ("")
A.4.6.3. expected: "String" ("")
A.4.7. Hints for GUIs
A.4.7.1. needed: Boolean ("Y")
A.4.8. For use by SOAPLAB
A.4.8.1. qualifier: "String" ("")
A.4.8.2. template: "String" ("")
A.4.8.3. comment: "String" ("")
A.5. Datatype-specific Attributes
A.5.1. Simple Attributes Description
A.5.1.1. array
A.5.1.2. boolean
A.5.1.3. float
A.5.1.4. integer
A.5.1.5. range
A.5.1.6. regexp
A.5.1.7. pattern
A.5.1.8. string
A.5.1.9. toggle
A.5.2. Input Attributes Description
A.5.2.1. codon
A.5.2.2. cpdb
A.5.2.3. datafile
A.5.2.4. directory
A.5.2.5. dirlist
A.5.2.6. discretestates
A.5.2.7. distances
A.5.2.8. features
A.5.2.9. filelist
A.5.2.10. frequencies
A.5.2.11. infile
A.5.2.12. matrix
A.5.2.13. matrixf
A.5.2.14. properties
A.5.2.15. scop
A.5.2.16. sequence
A.5.2.17. seqall
A.5.2.18. seqset
A.5.2.19. seqsetall
A.5.2.20. tree
A.5.3. Output Attributes Description
A.5.3.1. align
A.5.3.2. featout
A.5.3.3. outcodon
A.5.3.4. outcpdb
A.5.3.5. outdata
A.5.3.6. outdir
A.5.3.7. outdiscrete
A.5.3.8. outdistance
A.5.3.9. outfreq
A.5.3.10. outfile
A.5.3.11. outfileall
A.5.3.12. outmatrix
A.5.3.13. outmatrixf
A.5.3.14. outproperties
A.5.3.15. outscop
A.5.3.16. outtree
A.5.3.17. report
A.5.3.18. seqout
A.5.3.19. seqoutall
A.5.3.20. seqoutset
A.5.4. Selection Attributes Description
A.5.4.1. list
A.5.4.2. select
A.5.5. Graphics Attributes Description
A.5.5.1. graph
A.5.5.2. xygraph
A.6. Calculated Attributes
A.6.1. "Simple" ACD Datatypes
A.6.1.1. string
A.6.2. "Input" ACD Datatypes
A.6.2.1. Sequences
A.6.2.2. Sequence Features
A.6.2.3. Other Inputs (not sequences or features)
A.7. Sequence Types
A.8. Operations
A.8.1. Types of Operation
A.8.2. Retrieving Data Values
A.8.3. Types of Calculations and Tests
A.8.3.1. Arithmetic Operations
A.8.3.2. Tests for Equality
A.8.3.3. Boolean Tests
A.8.4. Conditional Statements
A.8.4.1. Unary Conditional Statements
A.8.4.2. Ternary Conditional
A.8.4.3. Case Conditional
A.8.5. Use of Variables
A.8.5.1. Automatic Variables
A.8.6. Summary of ACD Operators
B. Libraries Reference
B.1. Library Documentation
B.2. Source Code in SRS
B.3. AJAX Library Files
B.4. NUCLEUS Library Files
C. C Coding Standards
C.1. General Guidelines
C.2. Code Layout
C.2.1. Application Code Layout
C.2.1.1. Standard File Sections
C.2.2. Library Code Layout
C.2.2.1. Library Header File
C.2.2.2. Library Source File
C.2.2.3. Standard File Sections
C.2.3. Ease of Reading
C.2.3.1. Line Length
C.2.3.2. Variable Names
C.2.3.3. Braces
C.2.3.4. Indentation
C.3. ANSI C Standard
C.4. Use of the Preprocessor
C.4.1. Constants
C.4.2. Macros
C.5. Comments
C.6. Variables
C.6.1. Global variables
C.6.2. Static Variables in Functions
C.6.3. Variable Declarations
C.6.4. Variable Initialisation
C.6.5. Use of int, ajint, long and ajlong
C.7. Precedence of Operators
C.8. Structures and Unions
C.8.1. Declaration
C.8.2. Naming Conventions
C.8.3. Datatype Documentation
C.9. Functions
C.9.1. Function Prototypes
C.9.2. Implicit Declarations
C.9.3. Function and Parameter Names
C.9.4. Function Layout
C.9.5. Function Documentation
C.10. Program Flow
C.10.1. Loops
C.10.2. goto
C.10.3. switch Statements
C.11. Memory Allocation
C.11.1. General Memory Management
C.11.2. Object Construction
C.11.3. Object Destruction
D. Code Documentation Standards
D.1. Introduction
D.2. General Comments
D.3. Application Code Documentation
D.3.1. Standard Header
D.3.2. main() Function
D.3.3. Application Datatypes and Functions
D.4. Library Code Documentation
D.4.1. Standard Header
D.4.2. Library Datatypes and Functions
D.4.3. Functional Sections
D.4.3.1. Function Section Documentation Tags
D.4.3.2. Example
D.5. Datatype Documentation
D.5.1. Datatype Documentation Tags
D.6. Function Documentation
D.6.1. Function Documentation Tags
D.6.2. Parameter Codes
E. Resources
E.1. EMBOSS Programmatic Interfaces

List of Tables

5.1. C Fundamental Datatypes
5.2. Fundamental AJAX Datatypes
5.3. Other AJAX Types
6.1. Programming Guides for the AJAX Library
6.2. ACD Data Retrieval Functions
6.3. AJAX Library Files for Handling "Simple" ACD Datatypes
6.4. Datatypes and Functions for "Simple" ACD Datatype Input
6.5. AJAX Library Files for Handling Strings
6.6. Datatypes and Functions for String Input
6.7. AJAX Library Files for Handling Patterns
6.8. Datatypes and Functions for Pattern Input
6.9. AJAX Library Files for Handling Sequences
6.10. Datatypes and Functions for Sequence Input and Output
6.11. AJAX Library Files for Handling Sequence Translation
6.12. Datatypes and Function for Sequence Translation
6.13. AJAX Library Files for Handling Features
6.14. Datatypes and Functions for Feature Input and Output
6.15. AJAX Library Files for Handling Matrices
6.16. Datatypes and Functions for Comparison Matrix Input and Output
6.17. AJAX Library Files for Handling Alignments
6.18. Datatypes and Functions for Alignment Input and Output
6.19. Phylogenenetic datatypes
6.20. AJAX Library Files for Handling Phylogenetic Data
6.21. Datatypes and Functions for Phylogenetic Data Input and Output
6.22. AJAX Library Files for Handling Codon Usage Tables
6.23. Datatypes and Functions for Codon Usage Table Input and Output
6.24. AJAX Library Files for Handling Files
6.25. Datatypes and Functions for File and Output
6.26. AJAX Library Files for Handling Reports
6.27. Datatypes and Functions for Report Output
6.28. AJAX Library Files for Handling Lists
6.29. AJAX Library Files for Handling Arrays
6.30. Datatypes and Functions for Array Input and Output
6.31. AJAX Library Files for Handling Tables
6.32. AJAX Library Files for Handling Menus
6.33. Datatypes and Functions for File and Output
6.34. AJAX Library Files for Handling Graphics
6.35. Datatypes and Functions for Graphical Output
6.36. AJAX Library Files for Handling Maths
6.37. AJAX Library Files for Handling System
6.38. AJAX Library Files for Handling Messages
7.1. Records used in qatest.dat
8.1. Sections in Application Documentation
8.2. Sections in Package Documentation
A.1. Parameter and Qualifier Naming Conventions
A.2. Behaviour of Command line Parameters and Qualifiers
A.3. ACD File Sections
A.4. Application Attributes
A.5. Global Attributes
A.6. ACD Sequence Types
B.1.
B.2. NUCLEUS Library Files
D.1. Function Section Documentation Tags
D.2. Datatype Documentation Tags
D.3. Function Documentation Tags
D.4. Parameter Codes (basic types)
D.5. Parameter Codes (modifiers)
   Next
   Acknowledgements