6.3. Chemical database entry points

  DB_CXT db_get_context(DB_BOB ptr, DB_BOO ro, DB_INT verb);

    Get a dayblob context for blob of given name `nam'.  (In the demo
    version this is a filename).  This call will access a LOB locator.
    The readonly hint `ro' will be passed to my_blob_loc_access() when
    accessing the blob, i.e., if set TRUE, dayblob will never attempt to
    extend the blob past initial size nor call my_blob_update().

  DB_BOO db_free_context(DB_CXT cxt);

    The deallocates the context and releases associated LOB locator.

  DB_BOO db_set_verb(DB_CXT cxt, DB_INT verb);

    Set the verb(osity) level: 0 (none) to 3 (debug).  Return success.

  DB_INT db_verb(DB_CXT cxt);

    Return the current verb(osity) level: 0 (none) to 3 (debug).

  DB_INT db_crunch(DB_CXT cxt);

    Trim a blob: minimize size, e.g., remove space used by deleted entries.
    Return new size.

  DB_BOO db_insert(DB_CXT cxt, DB_BOB idb, DB_SOB sob);

    Insert a SMILES into a blob with binary ID `idb'; return success.

  DB_BOO db_update(DB_CXT cxt, DB_BOB idb, DB_SOB sob);

    Replace the SMILES for the existing entry with binary ID `idb'
    with the SMILES in `sob'.  Return success.

  DB_BOO db_delete_id(DB_CXT cxt, DB_BOB idb);

    Delete an entry by binary ID, return success.

  DB_BOO db_delete_smiles(DB_CXT cxt, DB_SOB sob, DB_INT norm, DB_INT kind);

    Delete all entries with SMILES of given kind.  Argument `norm' should be
    set TRUE iff given SMILES is known to be normalized.  Return success.

  DB_BOO db_delete_usmi(DB_CXT cxt, DB_SOB smi);

    Delete all entries with given unique SMILES.  This is faster than
    db_delete_smi() but requires a canonical SMILES.  Return success.

  DB_SOB db_id2usmi(DB_CXT cxt, DB_BOB idb);

    Return the canonical SMILES associated with a binary ID, or NULL.

  DB_SEQ db_e_lookup_smiles(DB_CXT cxt, DB_SOB sob, DB_INT norm, DB_INT kind);

    Return IDs of entries which have SMILES of given kind equivalent to the
    given SMILES, or NULL_OB if none exist.  Argument `norm' should be set
    TRUE iff given SMILES is known to be normalized.

  DB_SEQ db_lookup_usmi(DB_CXT cxt, DB_SOB smi);

    Return IDs of all entries which have the given unique SMILES, or
    NULL_OB if none exist.  This is faster than db_lookup_smi(),
    but requires a canonical SMILES.

  DB_SEQ db_tautomers(DB_CXT cxt, DB_SOB smi);

    Return IDs of all entries with structures which are tautomeric to the
    given SMILES molecule, or NULL_OB if none exist.  In this search,
    structures qualify as tautomers if they share a non-isomeric, oxidation-
    state-suppressed molecular graph and have the same integral net charge.

  DB_SEQ db_contains(DB_CXT cxt, DB_SOB smi);

    Return IDs of all entries with structures which are superstructures of
    the given SMILES, or NULL_OB if none exist.  (This is the molecular
    graph equivalent of a textual substring search.)

  DB_SEQ db_matches(DB_CXT cxt, DB_SOB smt);

    Return IDs of all entries with structures which match the given SMARTS
    pattern, or NULL_OB if none exist.  (This is the molecular graph
    equivalent of a textual regular expression search.)

  DB_SEQ db_similar(DB_CXT cxt, DB_SOB smi, DB_FLT tin);

    Return IDs of all entries with structures which are similar to the given
    SMILES structure as measured by having a Tanimoto similarity of at least
    the value given by `t', or NULL_OB if none exist.  (This is a molecular
    similarity search with a fixed cutoff value.)

  DB_SEQ db_nearest(DB_CXT cxt, DB_SOB smi, DB_INT nnn);

    Return IDs of `nnn' entries with structures most similar to the given
    SMILES structure as measured Tanimoto similarity, or NULL_OB on error.
    (This is a nearest neighbors search based on molecular similarity.)


6.4. Non-database chemical functions

  DB_INT db_smi2natoms(DB_SOB smi);

    Return the number of heavy (non-hydrogen) atoms in the molecule
    represented by the given SMILES, or -1 on error.

  DB_INT db_smi2hcount(DB_SOB smi);

    Return the total number of hydrogens in the molecule represented by
    the given SMILES, or -1 on error.

  DB_SOB db_smi2mf(DB_SOB smi);

    Return a canonical molecular formula of the molecule represented by
    the given SMILES, or NULL on error. The order of atoms in canonical
    formula is C, H, then alphabetically by atomic symbol, then * (wild);
    counts of 1 are not given, e.g., the MF for CCO ethanol is "C2H5O".

  DB_SOB db_smi2mdl(DB_SOB smi);
  DB_SOB db_mdl2smi(DB_SOB mdl);

    Convert SMILES to and from MDL file formats.  Molecular SMILES are
    converted to/from SD format, reaction SMILES to/from RD format.

  DB_SOB db_smi2usmi(DB_SOB smi);

    Return the canonical SMILES for the given SMILES, or NULL on error.

  DB_BOO db_smi_contains(DB_SOB smimol, DB_SOB smipat);

    Return TRUE iff the SMILES smimol contains the SMILES pattern 'smipat'.

  DB_BOO db_smi_matches(DB_SOB smi, DB_SOB smt);

    Return TRUE iff the SMILES smi matches the SMARTS pattern 'smt'.

  DB_INT db_smi_tautomers(DB_SOB smi1, DB_SOB smi2);

    Return 1 if SMILES smi1 and smi2 are tautomeric, 0 if not, or -1 on error.

  DB_INT db_smi_similarity(DB_SOB smi1, DB_SOB smi2);

    Return similarity of two SMILES between 0.0 and 1.0, or -1.0 on error.

  DB_INT db_id_similarity(DB_CXT cxt, DB_BOB id1, DB_BOB id2);

    Return similarity of SMILES of two IDs in the database, or -1.0 on error.
    This is faster than db_smi_similarity() but only works for database SMILES.


6.5. Public blob utilities

The following entry points are not strictly required but may be useful to
users of the dayblob interface.

  DB_INT db_nitems(DB_CXT *cxt);

    Return the number of entries currently stored in the blob or -1 on error.

  DB_INT db_tabtop(DB_CXT *cxt);

    Return the number of entries which were ever inserted into the blob,
    or -1 on error (tabtop is high-water mark of tablen).

  DB_BOB db_lastid(DB_CXT *cxt);

    Return binary ID of the entry most recently inserted into the blob.