1 /* $Id: blast_message.h 442874 2014-08-07 19:26:31Z camacho $ 2 * =========================================================================== 3 * 4 * PUBLIC DOMAIN NOTICE 5 * National Center for Biotechnology Information 6 * 7 * This software/database is a "United States Government Work" under the 8 * terms of the United States Copyright Act. It was written as part of 9 * the author's official duties as a United States Government employee and 10 * thus cannot be copyrighted. This software/database is freely available 11 * to the public for use. The National Library of Medicine and the U.S. 12 * Government have not placed any restriction on its use or reproduction. 13 * 14 * Although all reasonable efforts have been taken to ensure the accuracy 15 * and reliability of the software and data, the NLM and the U.S. 16 * Government do not and cannot warrant the performance or results that 17 * may be obtained by using this software or data. The NLM and the U.S. 18 * Government disclaim all warranties, express or implied, including 19 * warranties of performance, merchantability or fitness for any particular 20 * purpose. 21 * 22 * Please cite the author in any work or product based on this material. 23 * 24 * =========================================================================== 25 * 26 * Author: Tom Madden 27 * 28 */ 29 30 /** @file blast_message.h 31 * Structures for BLAST messages 32 */ 33 34 #ifndef ALGO_BLAST_CORE__BLAST_MESSAGE__H 35 #define ALGO_BLAST_CORE__BLAST_MESSAGE__H 36 37 #include <algo/blast/core/ncbi_std.h> 38 #include <algo/blast/core/blast_export.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** Structure to enclose the origin of an error message or warning 45 */ 46 typedef struct SMessageOrigin { 47 char* filename; /**< Name of the file */ 48 int lineno; /**< Line number in the file above */ 49 } SMessageOrigin; 50 51 /** Blast error message severities . 52 * These start with 1 to be consistent 53 * with the C toolkit severity numbers. 54 */ 55 typedef enum { 56 eBlastSevInfo = 1, 57 eBlastSevWarning, 58 eBlastSevError, 59 eBlastSevFatal 60 } EBlastSeverity; 61 62 /*** No single context is known to cause the error (probably a setup issue). */ 63 extern NCBI_XBLAST_EXPORT 64 const int kBlastMessageNoContext; 65 /*** Error message for failure to calculate ungapped Karlin-Altschul parameters */ 66 extern NCBI_XBLAST_EXPORT 67 const char* kBlastErrMsg_CantCalculateUngappedKAParams; 68 69 /** Structure to hold the a message from the core of the BLAST engine. */ 70 typedef struct Blast_Message { 71 struct Blast_Message *next; /**< next message in this list */ 72 EBlastSeverity severity; /**< severity code */ 73 char* message; /**< User message to be saved. */ 74 SMessageOrigin* origin; /**< Optional: origin of the message */ 75 int context; /**< Context, allows us to print message for query number. 76 kBlastMessageNoContext used if no context applies */ 77 } Blast_Message; 78 79 /** Deallocates message memory. 80 * @param blast_msg structure to be deallocated [in] 81 */ 82 83 NCBI_XBLAST_EXPORT 84 Blast_Message* Blast_MessageFree(Blast_Message* blast_msg); 85 86 87 /** Writes a message to a structure. The Blast_Message* is allocated. 88 * @param blast_msg structure to be filled in [in] 89 * @param severity severity code [in] 90 * @param context query context to which this error applies [in] 91 * @param message User message to be saved [in] 92 */ 93 94 NCBI_XBLAST_EXPORT 95 Int2 Blast_MessageWrite(Blast_Message* *blast_msg, EBlastSeverity severity, 96 int context, const char *message); 97 98 99 /** Print a message with ErrPostEx 100 * @param blast_msg message to be printed [in] 101 */ 102 103 NCBI_XBLAST_EXPORT 104 Int2 Blast_MessagePost(Blast_Message* blast_msg); 105 106 /* FIXME: should the code below and its implementation be moved to another 107 * file, say blast_error.[hc]? */ 108 109 /** Analogous to perror 110 * @param msg object to be appended to or created [in|out] 111 * @param error_code error code returned from BLAST function [in] 112 * @param context context number so that query or frame can be found [in] 113 * @return Blast_Message structure containing error description 114 */ 115 NCBI_XBLAST_EXPORT 116 void Blast_Perror(Blast_Message* *msg, Int2 error_code, int context); 117 118 /** Convenient define to call the function Blast_PerrorEx. */ 119 #define Blast_PerrorWithLocation(msg, error_code, context) \ 120 Blast_PerrorEx(msg, error_code, __FILE__, __LINE__, context) 121 122 /** Extended version of Blast_Perror which includes parameters for the file 123 * name and line number where the error/warning occurred. This function should 124 * be invoked via the Blast_PerrorWithLocation macro. 125 * @param msg object to be appended to or created [in|out] 126 * @param error_code one of the error codes defined below [in] 127 * @param file_name name of the file where the error ocurred [in] 128 * @param lineno line number where the error ocurred in the file above [in] 129 * @param context context number so that query or frame can be found [in] 130 */ 131 NCBI_XBLAST_EXPORT 132 void Blast_PerrorEx(Blast_Message* *msg, 133 Int2 error_code, 134 const char* file_name, 135 int lineno, 136 int context); 137 138 /* BLAST error codes: these are meant to describe errors that can occur in the 139 * core of BLAST only 140 */ 141 142 /** System error: out of memory condition */ 143 #define BLASTERR_MEMORY 50 144 145 /** Invalid parameter: possible programmer error or pre-condition not met */ 146 #define BLASTERR_INVALIDPARAM 75 147 148 /** Could not compute the ideal Karlin-Altschul parameters */ 149 #define BLASTERR_IDEALSTATPARAMCALC 100 150 151 /** Composition based statistics/Smith-Waterman not supported for a program 152 * type */ 153 #define BLASTERR_REDOALIGNMENTCORE_NOTSUPPORTED 101 154 155 /** All queries/contexts are determined invalid in the setup code */ 156 #define BLASTERR_INVALIDQUERIES 102 157 158 /** BLAST search was interrupted via a user-provided callback */ 159 #define BLASTERR_INTERRUPTED 103 160 161 /** Could not calculate Karlin-Altschul statistics for any context. */ 162 #define BLASTERR_NOVALIDKARLINALTSCHUL 104 163 164 /** The option is not supported with the specified program. */ 165 #define BLASTERR_OPTION_PROGRAM_INVALID 201 166 167 /** The value of the option is not supported (e.g., word size too small) */ 168 #define BLASTERR_OPTION_VALUE_INVALID 202 169 170 /** Blast seqsrc returns BLAST_SEQSRC_ERROR */ 171 #define BLASTERR_SEQSRC 300 172 173 #ifdef __cplusplus 174 } 175 #endif 176 #endif /* !ALGO_BLAST_CORE__BLAST_MESSAGE__H */ 177 178