C API for remote ACNUC access

API functions in alphabetical order : raa_acnucclose, raa_acnucopen, raa_acnucopen_alt, raa_alllistranks, raa_bcount, raa_bit0, raa_bit1, raa_btest, raa_copylist, raa_countfilles, raa_decode_address, raa_extract_1_seq, raa_extract_interrupt, raa_fcode, raa_getemptylist, raa_getlistrank, raa_getliststate, raa_gfrag, raa_ghelp, raa_iknum, raa_isenum, raa_knowndbs, raa_modifylist, raa_next_annots, raa_nexteltinlist, raa_nexteltinlist_annots, raa_nextmatchkey, raa_prep_acnuc_requete, print_raa_long, raa_open_socket, raa_opendb, raa_prep_extract, raa_proc_requete, raa_read_annots, raa_readacc, raa_readext, raa_readkey, raa_readlng, raa_readloc, raa_readshrt, raa_readsmj, raa_readspec, raa_readsub, raa_read_first_rec, raa_releaselist, raa_residuecount, raa_savelist, raa_seq_to_annots, raa_setlistname, raa_setliststate, raa_setsimext, raa_zerolist, scan_raa_long

API functions by theme : #include "raa_acnuc.h"

• Find, open, close database(s).
  • raa_acnucopen_alt, opens an acnuc database from its name.
  • raa_acnucopen, opens an acnuc db from environment variable racnuc
  • raa_open_socket, opens connection to remote acnuc server (needed before calling raa_knowndbs).
  • raa_knowndbs, gives list of names of known dbs
  • raa_opendb, opens db from name after raa_open_socket.
  • raa_acnucclose, closes the current acnuc db.
  • simultaneous access to several remote ACNUC dbs.
• Query database.
  • raa_prep_acnuc_requete, to be called once before starting queries.
  • raa_proc_requete, processes a query expressed with the acnuc query language and creates the list of matching sequences or species or keywords;
  • raa_nexteltinlist or raa_nexteltinlist_annots, loops through elements of list.
  • raa_nextmatchkey, finds next keyword matching a template.
  • raa_modifylist, modifies a sequence list by various criteria.
  • raa_savelist, save names of list elements in local file.
  • raa_getlistrank, raa_alllistranks, get list rank from list name, ranks of all currently defined lists.
  • raa_releaselist, deletes a list.
• Read sequence data and annotations.
  • raa_seq_to_annots, gain access to annotations from sequence rank.
  • raa_read_annots and raa_next_annots, read annotation lines
  • raa_gfrag, read sequence data
  • raa_prep_extract, raa_extract_1_seq, raa_extract_interrupt, extracts all seqs from a list to a local file
• Use species, keywords, accession nos.
  • raa_iknum, get db rank of species or keyword.
  • raa_fcode, get db rank of accession no., author, reference, type.
  • raa_isenum, get db rank of sequence name.
• Utility functions.
  • sock_fputs, send a character string to server
  • sock_flush, flush output to server
  • read_sock, read a character line received from server
  • raa_error_mess_proc, pointer to function called when connection gets lost
  • scan_raa_long, print_raa_long, reads/writes raa_long to decimal string

Typedefs :

typedef long long raa_long; /* scan_raa_long/print_raa_long converts from/to string decimal form */
typedef enum { raa_sub = 0, raa_loc, raa_key, raa_spec, raa_shrt, raa_lng, raa_ext, raa_smj,
	raa_aut, raa_bib, raa_txt, raa_acc } raa_file;
struct rlng {         
	int sub[SUBINLNG]; 
	int next; 
	};

Global variables :
int nseq, genbank, embl, swissprot, nbrf, longa, maxa;
struct rlng *plng;
void (*raa_error_mess_proc)(char *message) = NULL;

• raa_acnucopen opens access to a remote acnuc database using the racnuc, or, if undefined, acnuc, environment variable.
  int raa_acnucopen(char *clientid);
  clientid: NULL or the calling program name
  the value of the racnuc (or acnuc) environment variable should be such as pbil.univ-lyon1.fr:5558/embl
  return value :
  • 0 iff OK
  • 1 if problem with remote host name
  • 2 if cannot create connection with remote host
  • 3 if database is unknown by remote host
  • 4 if database is currently unavailable on remote host
  • 5 if neither racnuc nor acnuc are defined
  • 6 if not enough memory
  The global variables nseq, genbank, embl, swissprot, nbrf, longa, maxa are set, and the structure pointed to by plng is allocated.

• raa_acnucopen_alt opens access to a remote acnuc database using explicit address info.
  int raa_acnucopen_alt(char *server_ip, int s_num , char *db_name, char *clientid);
  • server_ip : ip name of the acnuc server (e.g., "pbil.univ-lyon1.fr")
  • s_num : socket number, normally 5558
  • db_name : name of the database (e.g. "embl")
  • clientid : NULL or the calling program name
  • return value : same as raa_acnucopen

• raa_open_socket opens access to the remote acnuc server
  int raa_open_socket(char *serveurName, int port, char *clientid);
  • serveurName : ip name of the acnuc server (e.g., "pbil.univ-lyon1.fr")
  • port: port number (e.g. 5558)
  • clientid: NULL or the calling program name
  • return value: 0 if OK; 1 if problem with remote host name; 2 if cannot create connection with remote host

• raa_opendb opens an acnuc database after raa_open_socket call
  int raa_opendb(char *dbname);
  dbname : database name (e.g., "embl")
  return value: 0 iff OK; 3 if database is unknown by remote host; 4 if database is currently unavailable on remote host

• raa_decode_address to decode an ACNUC-specific URL
  int raa_decode_address(char *address, char **server_ip, int *s_num, char **db_name);
  • address : same form as "pbil.univ-lyon1.fr:5558/swissprot" or "pbil.univ-lyon1.fr:5558"
  • server_ip : upon return, the ip name part of the address (pbil.univ-lyon1.fr)
  • s_num : upon return, the socket number part (5558)
  • db_name : upon_return, the db name (swissprot) or NULL if absent
  • return value : 0 iff OK

• raa_acnucclose to close access to the db
  void raa_acnucclose(void);

• raa_gfrag to read a sequence fragment
  int raa_gfrag(int nsub, int first, int lfrag, char *dseq);
  • nsub : rank of sequence
  • first : first residue to read (counting from 1)
  • lfrag : number of residues to read
  • dseq : character array, allocated by caller, to be filled with residues
  • return value : number of residues read (can be 0)

• raa_seq_to_annots get adress of start of annotations for a sequence
  void raa_seq_to_annots(int numseq, raa_long *faddr, int *div);
  • numseq : rank of sequence
  • *faddr : returned filled with the offset within flat file of beginning of annotations
  • div : returned filled with rank of division containing the sequence

• raa_read_annots read the first line of annotations of a sequence
  char *raa_read_annots(raa_long faddr, int div);
  • faddr : offset within flat file of beginning of annotations (typically from raa_seq_to_annots)
  • div : rank of division containing the sequence
  • return value : pointer to line read in static memory (NULL if error)

• raa_next_annots read the next line of annotations of a sequence
  char *raa_next_annots(NULL);
  or
  char *raa_next_annots(raa_long *faddr);
  • *faddr : returned filled with offset within flat file of beginning of line read (can be used later by raa_readannots)
  • return value : pointer to line read in static memory (NULL if error)

• raa_iknum get rank of a species of a keyword
  int raa_iknum(char *name, raa_file cas);
  • name : a species or a keyword (case is not significant)
  • cas :
  • return value : rank of given name (0 if absent)

• raa_isenum get rank of a sequence from its name
  int raa_isenum(char *name);
  • name : a sequence name (case is not significant)
  • return value : rank of given name (0 if absent)

• raa_prep_acnuc_requete prepare for using the query language
  int raa_prep_acnuc_requete(void);
  use it once after raa_acnucopen and before raa_proc_requete.

• raa_proc_requete
  int raa_proc_requete(char *requete, char **message, char *nomliste, int *numliste, int *count, int *locus, int *type);
  • requete : a string containing a query following the acnuc query language
  • message : if != NULL, returned filled with an error message in case of error in malloc'ed memory
  • nom_liste : the name to be given to the list (case is not significant)
  • numliste : upon return, if no error, the rank of the created list
  • count : if != NULL, returned filled with the number of elements in the created list
  • locus : if != NULL, returned filled with TRUE if list contains parent sequences only
  • type : if != NULL, returned filled with 'S', 'K', or 'E' for a list of seqs, keywords, or species
  • return value : O if OK or an error number

• raa_nexteltinlist returns the next element of a list
  int raa_nexteltinlist(int first, int lrank, char **name, int *length);
  • first : elements of list are searched after this position (initiate this to 0)
  • lrank : rank of the list
  • name : if != NULL, returned filled with the name of the element in static memory
  • length : if != NULL, returned filled with the element length (for seq list only)
  • return value : the rank of the next element in the list, or 0 if none

• raa_nexteltinlist_annots returns the next element of a sequence list and related information
  int raa_nexteltinlist(int first, int lrank, char **name, int *length, raa_long *offset, int *div);
  • first : elements of list are searched after this position (initiate this to 0)
  • lrank : rank of the sequence list
  • name : if != NULL, returned filled with the name of the sequence in static memory
  • length : if != NULL, returned filled with the sequence length
  • offset : if != NULL, returned filled with the annotation offset of the seq
  • div : if != NULL, returned filled with the division rank of the seq
  • return value : the rank of the next sequence in the list, or 0 if none

• raa_nextmatchkey returns the next keyword matching a given pattern
  int raa_nextmatchkey(int num, char *pattern, char **matching);
  • num : rank beyond which next matching keyword if sought (set num=2 the first time)
  • pattern : may contain the wild card character @ (used only if num = 2)
  • matching : if not NULL, filled with matching keyword in private memory
  • return value : rank of next matching keyword

• raa_bcount counts the number of elements in a list
  int raa_bcount(int lrank);
  • lrank : rank of the list
  • return value : the number of elements in the list

• raa_bit1 adds an element to a list
  void raa_bit1(int lrank, int num);
  • lrank : rank of the list
  • num: rank of the element to add

• raa_bit0 removes an element from a list
  void raa_bit0(int lrank, int num);
  • lrank : rank of the list
  • num: rank of the element to remove

• raa_btest tests presence of element in a list
  int raa_btest(int lrank, int num);
  • lrank : rank of the list
  • num: rank of the element to remove
  • return value: TRUE iff element num is in list lrank

• raa_copylist duplicates a list
  void raa_copylist(int rank_from, int rank_to);
  • rank_from : rank of the list to copy
  • rank_to : rank of the destination list that must have been previously allocated by e.g., raa_getemptylist

• raa_zerolist empties a list
  void raa_zerolist(int lrank);
  lrank : rank of the list to empty, that must have been previously allocated by e.g., raa_getemptylist.

• raa_setliststate sets the state of a list
  void raa_setliststate(int lrank, int locus, int type);
  • lrank: rank of the list
  • locus : TRUE iff list contains only parent sequences
  • type : 'S', 'K', or 'E' for list of seqs, keywords, or species.

• raa_getliststate gets the state of a list
  char *raa_getliststate(int lrank, int *locus, int *type, int *count);
  • lrank: rank of the list
  • locus : if != NULL, returned filled with TRUE iff list contains only parent sequences
  • type : if != NULL, returned filled with 'S', 'K', or 'E' for list of seqs, keywords, or species.
  • count : if != NULL, returned filled with the number of elements in list
  • return value : the list name in static memory, or NULL if error

• raa_getemptylist finds an empty list
  int raa_getemptylist(void);
  return value : the list rank, or 0 if none is available; the list is set to zero

• raa_setlistname sets the name of a list
  int raa_setlistname(int lrank, char *name);
  • lrank: rank of the list
  • name : name to give to the list
  • return value :
    • 0 : OK
    • 1 : a list with that name already existed and was deleted
    • -1 : no list with that rank exists

• raa_getlistrank gets the rank of a list from its name
  int raa_getlistrank(char *name);
  • name: name of the list
  • return value : > 0 if OK, 0 if no list with that name exists

• raa_releaselist releases a list
  int raa_releaselist(int lrank);
  • lrank: rank of the list
  • return value : 0 if OK, != 0 if no list with that rank exists

• raa_residuecount count residues in a list
  char *raa_residuecount(int lrank);
  • lrank: rank of the list
  • return value : total number of residues (nucleotides or aminoacids) in all sequences of the list as a char string in static memory (caution: may require a 64-bit integer to be sscanf'ed).

• raa_countfilles counts the number of subsequences present in a list
  int raa_countfilles(int lrank);
  • lrank: rank of the list
  • return value : the number of subsequences present

• raa_alllistranks counts the number of subsequences present in a list
  int raa_alllistranks(int **ranks);
  • ranks: upon return, an array of ranks of used lists in malloc'ed memory
  • return value : the number of used lists

• raa_fcode returns the rank of a record of an index file from its key
  int raa_fcode(raa_file case, char *name);
  • case: one of raa_aut raa_bib raa_acc raa_smj raa_sub
  • name: the record key
  • return value : the rank of the corresponding key

• raa_read_first_rec returns the total number of records in an index file
  int raa_read_first_rec(raa_file cas);
  • cas: an index file expressed using the raa_file enumeration
  • return value : the total number of records in the index file

• int atoi_u(const char *p);
  decodes a string as an unsigned decimal integer

• raa_readsub reads a SUBSEQ record
  char *raa_readsub(int num, int *plength, int *ptype, int *pext, int *plkey, int *plocus, int *pframe, int *pgencode)
  • num: seq rank
  • plength: upon return, filled, if != NULL, with seq length
  • ptype : upon return, filled, if != NULL, with rank of seq type
  • pext : upon return, filled, if != NULL, with
    • > 0 indicates a subsequence and pext is a record # in EXTRACT
    • ≤ 0 indicates a parent sequence and -pext is the start of long list of subsequences
  • plkey : upon return, filled, if != NULL, with start of short list of keywords
  • plocus : upon return, filled, if != NULL, with LOCUS rank for a parent sequence or 0 for a subsequence
  • pframe : upon return, filled, if != NULL, with reading frame (0,1, or 2)
  • pgencode : upon return, filled, if != NULL, with genetic code (0 is standard)
  • return value : sequence name in static memory or NULL if error

• raa_readloc reads a LOCUS record
  char *raa_readloc(int num, int *sub, int *pnuc, int *spec, int *host,
  int *plref, int *molec, int *placc, int *org);
  • num: rank of LOCUS record
  • sub, pnuc, spec, host, plref, molec, placc, org: fields of the record (any pointer can be NULL for no value returned)
  • return value: the date as a private character string

• raa_readspec reads a SPECIES record
  char *raa_readspec(int num, char **plibel, int *plsub, int *desc, int *syno, int *plhost);
  • num: rank of SPECIES record
  • plibel: if plibel != NULL, *plibel is returned as pointer to label in private memory, or as NULL if no label exists
  • plsub, desc, syno, plhost: returned with data read from the record
  • return value: pointer to name of species in private memory

• raa_readkey reads a KEYWORDS record
  char *raa_readkey(int num, char **plibel, int *plsub, int *desc, int *syno);
  • num: rank of KEYWORDS record
  • plibel: if plibel != NULL, *plibel is returned as pointer to label in private memory, or as NULL if no label exists
  • plsub, desc, syno: if != NULL, returned with data read from the record
  • return value: pointer to name of keyword in private memory

• raa_readsmj reads an SMJYT record
  char *raa_readsmj(int num, char **plibel, int *plong);
  • num: rank of SMJYT record
  • plibel: if plibel != NULL, *plibel is returned as pointer to label in private memory, or as NULL if no label exists
  • plong: if != NULL, upon return points to data read from record
  • return value: name as a private string

• raa_readacc reads an ACCESS record
  char *raa_readacc(int num, int *plsub);
  • num: rank of ACCESS record
  • plsub: if != NULL, upon return points to data read from record
  • return value: name as a private string

• raa_readext reads an EXTRACT record
  int raa_readext(int num, int *mere, int *deb, int *fin);
  • num: rank of record
  • mere, deb, fin: if != NULL, upon return point to data read from record
  • return value: 0 or rank of next chained record

• int raa_readlng(int point) reads a long list record
  the read data is placed in structure pointed to by global variable plng
  • point: rank of record
  • return value: 0 or rank of next chained record

• raa_readshrt reads a short list element
  unsigned raa_readshrt(unsigned point, int *val);
  • point: rank of element
  • val: upon return, the element value
  • return value: 0 or the rank of the next short list element

• raa_long scan_raa_long(char *txt);
  decodes a string as a number of type raa_long (capable of storing large file offset)

• char *print_raa_long(raa_long val);
  encodes a number of type raa_long (capable of storing large file offset) as a string in static memory

• char *raa_ghelp(char *fname, char *topic);
  returns all topic from fname (HELP or HELP_WIN) in one string in private memory

• int raa_setsimext(void *point, encode_function f);
  • point: pointer to data to be transmitted to the server
  • f: pointer to a function of type char* (*function)(void *) use to encode the data
  • return value : 0 iff OK

• raa_savelist saves in a local file names or acc. nos of members of a list
  int raa_savelist(int lrank, FILE *out, int use_acc, char *prefix);
  • lrank: rank of list to be saved in a file (can be seq, species or keyw list)
  • out: opened file where to save list members
  • use_acc: if TRUE, save accession numbers, if FALSE, save names of list members
  • prefix: if != NULL, write prefix before each name of each member in file out
  • return value: 0 iff ok

• raa_modifylist modifies list according to length or date or by scanning the annotation of its elements
  int raa_modifylist(int lrank, char *type, char *operation, int *pnewlist, int (*check_interrupt)(void), int *p_processed);
  • lrank: rank of list to be modified (must be a seq list)
  • type: "length" or "date" or "scan"
  • operation: (for length) ">10000" or "<500"
    (for date) ">1/jan/2003" or " < 29/FEB/96"
    (for scan) "string-to-be-searched-for" the prep_getannots command must be sent to the server with functions int sock_fputs(char *line); and char *read_sock(void); before using the scan operation
  • pnewlist: upon return, points to rank of newly created list containing result of operation
  • check_interrupt: NULL or pointer to a function that will be called iteratively by the function and that should return TRUE iff caller wants to interrupt the modification operation
  • p_processed: NULL, or pointer to value that will be set, upon return, to the number of list elements processed by the function until interruption or completion (for scan operation only)
  • return value: 0 if ok; 2 syntax error in operation; 3 creation of new list is impossible

• raa_knowndbs gets name and description of all known databases
  int raa_knowndbs(char ***pnames, char ***pdescriptions);
  • pnames: points to array of strings loaded with database names (in malloc'ed memory)
  • pdescriptions: points to array of strings loaded with database descriptions (in malloc'ed memory)
  • return value: number of elements in tables pnames and pdescriptions

• raa_prep_extract prepares for extraction of all members of a sequence list to a local file
  int raa_prep_extract(char *format, char *fname, char *operation, char *feature_name, char *bornes, char *min_bornes, char **pmessage, int lrank);
  • format: "fasta" or "flat" (e.g., genbank, embl) or "acnuc"
  • fname: name of output local file
  • operation: "simple", "translation" (translates on the fly CDS sequences), "feature" (extracts fragment corresponding to given feature name), "fragment", or "region"
  • feature_name: NULL or name of desired feature
  • bornes, min_bornes: NULL unless operation is "fragment" or "region"
  • pmessage: returned set to NULL or to error message
  • lrank: rank of sequence list
  • return value: 0 iff OK

• raa_extract_1_seq successively extracts one sequence from list.
  int raa_extract_1_seq(void);
  return value: number of extracted sequences (0 is possible),
         or -1 when all of list was processed. Must call this function until -1 is returned.

• raa_extract_interrupt cleanly interrupts an extraction before its full completion.
  void raa_extract_interrupt(void);

• sock_fputs send a character string to server
  int sock_fputs(char *line);
  return value: 0 iff success

• sock_flush flush output to server
  int sock_flush(void);
  return value: 0 iff success

• read_sock read a character line received from server
  char *read_sock(void);
  return value: a full line of data received from server in private memory.
  The function returns NULL if communication with server is lost.

• raa_error_mess_proc pointer to function called when connection gets lost
  void (*raa_error_mess_proc)(char *message);
  Usage example :

  void my_error_proc(char *message)
  {
  fprintf(stderr,"%s\n", message);
  }
  raa_error_mess_proc = my_error_proc;

  When no such function is assigned to raa_error_mess_proc, exit(0) is called after connection loss.