All data definitions for report output should have standard parameter names (see Appendix A, ACD Syntax Reference):

Attributes that are typically specified are summarised below. They are datatype-specific (Section A.5, “Datatype-specific Attributes”) unless they are indicated as being global attributes (Section A.4, “Global Attributes”).

parameter: Reports are typically the primary output of an EMBOSS application and, as such, should be defined as parameters by using the global attribute parameter: "Y".

rformat: Specifies the report format to use, which must be one of the supported report formats (see the EMBOSS Users Guide). There is a default report format that will be used if the user doesn't change it with -rformat on the command line.

multiple: A boolean attribute which should be set to "Y" if the output can contain more than one report from the same input. This will generally have a value of "N" if you are using a single input sequence (the sequence ACD datatype) and "Y" if you're processing multiple sequences from an input stream (the seqall ACD datatype).

type: Specifies where the report format is one of the standard feature table formats (see the EMBOSS Users Guide). type: defines whether the report output is "protein" or "nucleotide". There is a default based on the type of any input sequence, but a value should always be specified.

taglist: Defines the tag / value pairs from the internal feature table that are to be reported in the output. Each tag is in the general format type:tagname and can (optionally) be appended with [=columnname] to indicate a column name to use in the report:

For example:

Typical taglist datatypes are:

The name can be anything within reason but tag names and types must match those used in the C source code of the application.

In the given example float:molwt indicates that one of the columns is called molwt and that it will contain floating point values.

To retrieve an output report stream an object pointer is declared and initialised using ajAcdGetReport:

    AjPReport report=NULL;

    report = ajAcdGetReport("report");

Currently there are no functions for this.

It is your responsibility to close any files and free up memory at the end of the program.

void  ajReportClose (AjPReport pthys);

void  ajReportExit (void);

Report objects are typically loaded from ACD file processing via a call to ajAcdGetReport (see above). You should therefore never need to instantiate the report object (AjPReport) manually. In the unlikely event you do then the default constructor is:

AjPReport  ajReportNew (void);    

The constructor returns the address of a new report object. In the following code the pointer does not need to be initialised to NULL but it is good practice to do so:

    AjPReport      report = NULL;

    report    = ajReportNew();

    /* The object is instantiated and ready for use */

You must free the memory for an object once you are finished with it. The default destructor function is:

void  ajReportDel (AjPReport* Preport);

It is used as follows:

    AjPReport     report =NULL;

    report = ajAcdGetReport("report");

    ...

    ajReportDel(&report);

Or if you manually instantiated the object:

    AjPReport report = NULL;

    report = ajReportNew();

    /* Do something with the instantiated objects */

    ajReportDel(&report);

    /* Done with the objects so the memory is freed. */

Currently there are none of these.

In the following ACD file, a sequence input and a report output are defined. The datafile datatype is just there so that a file of molecular weight data in the EMBOSS data area can be read.

application: wreport 
[
    documentation: "Example report program"
]

section: input [ info: "input Section" type: page ]
sequence: sequence  
[
    parameter: "Y"
    type: "Protein"
]

endsection: input


section: advanced [ info: "advanced Section" type: page ]

datafile: aadata  
[
    information: "Amino acid data file"
    help: "Molecular weight data for amino acids"
    default: "Eamino.dat"
]

endsection: advanced


section: output [ info: "output Section" type: page ]

report: outfile  
[
    parameter: "Y"
    rformat: "table"
    multiple: "N"
    precision: "1"
    taglist: "float:molwt int:len"
]
endsection: output

The section: and endsection: definitions provide a means by which GUIs can be instructed to organise the ACD information on the screen. Each section must always have a corresponding endsection. It is standard practice to have at least an input and an output section definition, adding others as appropriate.

The complete source code for the application is given below.

/* @prog wreport **************************************************************
**
** Show sequence length and molwt as a report
**
******************************************************************************/

int main(int argc, char **argv)

{
    AjPSeq       seq    = NULL;
    AjPReport    report = NULL;
    AjPFeattable ftable = NULL;
    AjPFeature   feat   = NULL;
    AjPStr       tmpstr = NULL;

    double       molwt;
    int          len;

    AjPFile      mfptr  = NULL;


    embInit ("wreport", argc, argv);

    seq    = ajAcdGetSeq ("sequence");
    report = ajAcdGetReport("outfile");

    /* This bit just reads in an EMBOSS data table of molwt info */
    mfptr  = ajAcdGetDatafile("aadata");


    embPropEaminoRead(mfptr);
    /* End of data file reading */

    /* Calculate the values to output */
    len   = ajSeqGetLen(seq);
    molwt = embPropCalcMolwt(ajSeqGetSeqC(seq),0,len-1);


    /* Create a feature table */
    ftable = ajFeattableNewSeq(seq);


    tmpstr = ajStrNew();


    /* Fill head and tail information for the report */
    ajFmtPrintS(&tmpstr,"This is some Header Text");
    ajReportSetHeaderS(report, tmpstr);

    ajFmtPrintS(&tmpstr,"This is some Tail Text");
    ajReportSetTailS(report, tmpstr);


    /* Create feature object and load with the output values */
    feat = ajFeatNewII(ftable,1,len);

    ajFmtPrintS(&tmpstr,"*molwt %.1f", (float)molwt);
    ajFeatTagAdd(feat,NULL,tmpstr);

    ajFmtPrintS(&tmpstr,"*len %d", len);
    ajFeatTagAdd(feat,NULL,tmpstr);


    /* Write report and clean up */
    ajReportWrite(report,ftable,seq);


    ajFeattableDel(&ftable);
    ajStrDel(&tmpstr);
    ajFileClose(&mfptr);

    embExit();
    return 0;}

First the variables are defined. Objects are needed for a sequence (AjPSeq) and a feature table (AjPFeattable) to hold the feature objects containing the column values. Also needed is an object for individual features (AjPFeature) to contain the values that will be printed in the report. Some housekeeping variables are required and, of course, the report itself (AjPReport):

AjPSeq       seq    = NULL;   /* Input sequence */
AjPReport    report = NULL;   /* Output report */
AjPFeattable ftable = NULL;   /* Feature table */
AjPFeature   feat   = NULL;   /* Individual feature */
AjPStr       tmpstr = NULL;

double       molwt;
int          len;

AjPFile      mfptr  = NULL;

The program can then be initialised and the ACD file processed:

    embInit ("wreport", argc, argv);

    seq    = ajAcdGetSeq ("sequence");
    report = ajAcdGetReport("outfile");

Code is then needed to read in the EMBOSS data file containing amino acid molecular weight data and calculate the molecular weight and length values to be reported. Note that len and molwt are used for both the variable names and for the column names. This is not necessary but does make the code more clear:

    mfptr = ajAcdGetDatafile("aadata");

    embPropEaminoRead(mfptr);

    len   = ajSeqGetLen(seq);
    molwt = embPropCalcMolwt(ajSeqGetSeqC(seq),0,len-1);

The report head and tail information is then set. This could have been done any time after the ajAcdGetReport but before the report is printed. They are optional but recommended. The temporary string object is used for this:

    tmpstr = ajStrNew();

    ajFmtPrintS(&tmpstr,"This is some Header Text");
    ajReportSetHeaderS(report, tmpstr);

    ajFmtPrintS(&tmpstr,"This is some Tail Text");
    ajReportSetTailS(report, tmpstr);

The feature table object is then created. Only one feature table is required per report. The sequence object is passed as a parameter so that the sequence name can be automatically loaded into the internal GFF format. A feature object can now be created into which the column values can be loaded. A single feature object with a tag/value pair is used for each output value. The column values are printed into a string object (tmpstr) which is used to load the feature object.

ajFeatNewII requires 3 parameters. The first is the feature table object, the last two are the sequence start and end positions. Rather naughtily they are hard coded in this example (as mentioned above). A feature object has to be created per line of output in the final report. ajFeatTagAdd is used to load the molecular weight and length values into the feature object:

    ftable = ajFeattableNewSeq(seq);

    feat = ajFeatNewII(ftable,1,len);

    ajFmtPrintS(&tmpstr,"*molwt %.1f", (float)molwt);
    ajFeatTagAdd(feat,NULL,tmpstr);

    ajFmtPrintS(&tmpstr,"*len %d", len);
    ajFeatTagAdd(feat,NULL,tmpstr);

This is the bit where the ACD column names (molwt and len) must match the ones in the ajFmtPrintS calls. Within the C program these names must be preceded by an asterisk (*). The datatypes specified in the ACD file (float and int) must also match what's given in the C code. The NULL parameter just means that only a value is being added (the library will add the /note tag automatically).

The report can now be written. Three objects are passed. The reason for the sequence object being passed is in case you choose a report format that prints out the (sub)sequence used:

    ajReportWrite(report,ftable,seq);

Finally the dynamic memory is recovered in a clean-up prior to exiting:

    ajFeattableDel(&ftable);
    ajStrDel(&tmpstr);
    ajFileClose(&mfptr);

    embExit ();

    return 0;