#ifndef __PRQ_UTILS_H #define __PRQ_UTILS_H /*------------------------------------------------------------------------- * Copyright (c) 1999-2002 Kenneth W. Sodemann (stuffle@charter.net) *------------------------------------------------------------------------- * prq_utils * * Synopsis: * Helper routines for modules dealing with the pr_query table. * * $Id: prq_utils.h,v 1.1 2003/03/09 20:59:11 stuffle Exp $ * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to * Free Software Foundation, Inc. * 59 Temple Place, Suite 330 * Boston, MA 02111-1307 USA *------------------------------------------------------------------------- */ /*! \file prq_utils.h \brief Utility functions used when dealing with the PRepS query table. PRepS has a query table that stores the queries that the user can use to select which items to display. The functions defined here aid in dealing with that table. Specifically, the query table makes use of PostgreSQL's array feature that allows for arrays of data to be stored in a column. These functions make it easier to access the 'array' columns in the query table. \author Kenneth W. Sodemann (stuffle@charter.net) $Revision: 1.1 $ $Date: 2003/03/09 20:59:11 $ */ #include #include /* * __BEGIN_DECLS should be used at the beginning of your declarations, * so that C++ compilers don't mangle their names. Use __END_DECLS at * the end of C declarations. */ #undef __BEGIN_DECLS #undef __END_DECLS #ifdef __cplusplus # define __BEGIN_DECLS extern "C" { # define __END_DECLS } #else # define __BEGIN_DECLS /* empty */ # define __END_DECLS /* empty */ #endif /* * The __P macro is used to wrap function prototypes, so that compilers * that don't understand ANSI C prototypes still work, and ANSI C * compilers can issue warnings about type mismatches. */ #undef __P #if defined (__STDC__) || defined (_AIX) \ || (defined (__mips) && defined (_SYSTYPE_SVR4)) \ || defined(WIN32) || defined(__cplusplus) # define __P(protos) protos #else # define __P(protos) () #endif /*! \def SEVR_NUMS * Use in create_num_list() calls to specifiy the 'severity numbers' * column. */ /*! \def STAT_NUMS * Use in create_num_list() calls to specify the 'status numbers' column. */ /*! \def TYPE_NUMS * Use in create_num_list() calls to specify the 'problem type numbers' * column. */ /*! \def SUB_IDS * Use in create_txt_list() calls to specify the 'submitter login-ids' * column. */ /*! \def RESP_IDS * Use in create_txt_list() calls to specify the 'responsible login-ids' * column. */ #define SEVR_NUMS "severity_nums" #define STAT_NUMS "status_nums" #define TYPE_NUMS "problem_type_nums" #define SUB_IDS "submitter_ids" #define RESP_IDS "responsible_ids" __BEGIN_DECLS /*! \fn create_num_list (PGconn *conn, gint query_pk, const gchar *column) \brief Create a list of numbers from a PostgreSQL int array field. PostgreSQL allows for arrays of values to be stored in a column. This function takes the contents of one of those columns and returns its contents as a linked list of integers. Use this function for fields that contain arrays of integers. It is the caller's responsibility to destroy the list. \param conn The database connection. \param query_pk The primary key of query we are interested in. \param column The name of the column we are interested in (defined above) \return A linked list of the integers in the array. */ GList *create_num_list __P((PGconn *conn, gint query_pk, const gchar *column)); /*! \fn create_txt_list (PGconn *conn, gint query_pk, const gchar *column) \brief Create a list of text entries from a PostgreSQL text array field. PostgreSQL allows for arrays of values to be stored in a column. This function takes the contents of one of those columns and returns its contents as a linked list of integers. Use this function for fields that contain arrays of text. This function g_malloc's gchar arrays and places them in a list. It is the caller's responsibility to properly g_free the gchar buffers, and destroy the list. \param conn The database connection. \param query_pk The primary key of query we are interested in. \param column The name of the column we are interested in. \return A linked list of the text strings in the array. */ GList *create_txt_list __P((PGconn *conn, gint query_pk, const gchar *column)); /*! \fn create_int_arr_str (GList *list) \brief Create an array string from a linked list of integers. PostgreSQL allows for arrays of values to be stored in a column. This function takes a list of integers and creates a chacter string that represents the array in the format that PostgreSQL expects. This function allocates a new GString. It is the callers responsiblity to destroy the GString (use g_string_free()). \param list A linked list of integers. \return The string representation of the array, using the syntax that PostgreSQL expects. */ GString *create_int_arr_str __P((GList *list)); /*! \fn create_txt_arr_str (GList *list) \brief Create an array string from a linked list of integers. PostgreSQL allows for arrays of values to be stored in a column. This function takes a list of strings and creates a chacter string that represents the array in the format that PostgreSQL expects. This function allocates a new GString. It is the callers responsiblity to destroy the GString (use g_string_free()). \param list A linked list of strings. \return The string representation of the array, using the syntax that PostgreSQL expects. */ GString *create_txt_arr_str __P((GList *list)); __END_DECLS #endif