Main Page   File List   File Members  

pr_query.h File Reference

Functions to handle the data in the PRepS query table. More...

#include <glib.h>
#include <libpq-fe.h>

Go to the source code of this file.

Defines

#define __P(protos)    protos
#define PROJECT_NAME_POS   0
#define STATUS_NAME_POS   1
#define PROBLEM_TYPE_NAME_POS   2
#define SEVERITY_NAME_POS   3
#define PR_TITLE_POS   4
#define STATUS_ORDER_POS   5
#define SEVERITY_ORDER_POS   6
#define PR_NUMBER_POS   7

Typedefs

typedef struct pr_query_struct pr_query_struct

Functions

pr_query_structcreate_pr_query (gchar *user_id)
 Create the basic problem report query. More...

pr_query_structcreate_pr_query_from_table (PGconn *conn, const gchar *user_id, gint query_pk)
 Create a problem report query, initializing the structure with a query defined in the query table. More...

pr_query_structcreate_pr_query_from_table_li (const gchar *conn_str, const gchar *user_id, gint query_pk)
 Similar to create_pr_query_from_table(), accept this function does a database login rathher than using an existing connetion. More...

void destroy_pr_query (pr_query_struct *pr_query)
 Free the memory, etc. More...

void add_project_restriction (pr_query_struct *q, gint pk)
 Add a project constraint to the query. More...

void clear_project_restrictions (pr_query_struct *q)
 Clear the project restriction list. More...

void add_severity_restriction (pr_query_struct *q, gint pk)
 Add the given severity to the severity restriction list. More...

void clear_severity_restrictions (pr_query_struct *q)
 Clear the severity restrictions for the query. More...

void add_status_restriction (pr_query_struct *q, gint pk)
 Add the given status to the status restriction list. More...

void clear_status_restrictions (pr_query_struct *q)
 Clear the status restrictions for the query. More...

void add_problem_type_restriction (pr_query_struct *q, gint pk)
 Add the given problem type to the problem type restriction list. More...

void clear_problem_type_restrictions (pr_query_struct *q)
 Clear the problem type restrictions for the query. More...

void add_submitter_restriction (pr_query_struct *q, gchar *id)
 Add the given submitter ID to the submitter restriction list. More...

void clear_submitter_restrictions (pr_query_struct *q)
 Clear the submitter restrictions for the query. More...

void add_responsible_restriction (pr_query_struct *q, gchar *id)
 Add the given responsible ID to the responsible restriction list. More...

void clear_responsible_restrictions (pr_query_struct *q)
 Clear the responsible ID restrictions for the query. More...

void set_raw_pr_where (pr_query_struct *q, const gchar *str)
 Set the WHERE clause manually rather than using the 'set' and 'clear' functions. More...

void clear_raw_pr_where (pr_query_struct *q)
 Clear the raw WHERE clause. More...

void set_order_by (pr_query_struct *q, const gchar *str)
 Set the order by clause. More...

void clear_order_by (pr_query_struct *q)
 Clear the order by clause. More...

GString* create_query_string (const pr_query_struct *q)
 Create an executable SQL query from the query structure. More...


Detailed Description

Functions to handle the data in 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 are used to load those queries from the database, manipulate the criteria for the queries, and create the SQL statement associated with the query. These functions can also be used to build problem report queries from the user interface.

In most cases, there are four steps to follow when using the query functions:

    1. Create the query structure using one of the 'create' functions

    2. Modify the constraints on the query using the 'add' and 'clear'
       functions.

    3. Create a SQL query string from the query structure.  This query
       string is standard SQL that can then be sent to the database for
       execution.

    4. Call destroy_pr_query() to free up the memory used by the query
       structure.
    

Author(s):
Kenneth W. Sodemann (stufflehead@bigfoot.com)
Revision:
1.9
Date:
2000/11/13 16:22:35


Define Documentation

#define PROBLEM_TYPE_NAME_POS   2
 

Define the position of the problem type name within the select clause of the problem report query.

#define PROJECT_NAME_POS   0
 

Define the position of the project name within the select clause of the problem report query.

#define PR_NUMBER_POS   7
 

Define the position of the problem report number within the select clause of the problem report query.

#define PR_TITLE_POS   4
 

Define the position of the problem report title within the select clause of the problem report query.

#define SEVERITY_NAME_POS   3
 

Define the position of the severity name within the select clause of the problem report query.

#define SEVERITY_ORDER_POS   6
 

Define the position of the severity order flag within the select clause of the problem report query.

#define STATUS_NAME_POS   1
 

Define the position of the status name within the select clause of the problem report query.

#define STATUS_ORDER_POS   5
 

Define the position of the status order flag within the select clause of the problem report query.


Typedef Documentation

pr_query_struct
 

This structure holds the data used to build the query. The contents of this structure are not intended for public consumption, and are thus hidden. Use the functions documented within this library to modify the contents of this structure.


Function Documentation

add_problem_type_restriction ( pr_query_struct * q,
gint pk )
 

Add the given problem type to the problem type restriction list.

By default, the query is not restricted by problem type. If you want to restrict the results by problem type, use this function to add the problem types you want the query restricted to.

Parameters:
pk   The problem type to add to the list.
q   A pointer to the query to modify.

add_project_restriction ( pr_query_struct * q,
gint pk )
 

Add a project constraint to the query.

By default the query is contrained to all projects that the current user has access to. If you want to contrain the projects further, use this function to add the projects that you want the query to be run against.

Parameters:
pk   The project number of the project to restrict by.
q   A pointer to the query to modify.

add_responsible_restriction ( pr_query_struct * q,
gchar * id )
 

Add the given responsible ID to the responsible restriction list.

By default, the query is not restricted by the person the problem report is assigned to. If you want to restrict the results by the assignee, use this function to add the login ids of those you want the query restricted to.

Parameters:
id   The responsible ID to add to the list.
q   A pointer to the query to modify.

add_severity_restriction ( pr_query_struct * q,
gint pk )
 

Add the given severity to the severity restriction list.

By default, the query is not restricted by severity. If you want to restrict the results by severity, use this function to add severities you want the query restricted to.

Parameters:
pk   The severity to add to the list.
q   A pointer to the query to modify.

add_status_restriction ( pr_query_struct * q,
gint pk )
 

Add the given status to the status restriction list.

By default, the query is not restricted by status. If you want to restrict the results by status, use this function to add statuses you want the query restricted to.

Parameters:
pk   The status to add to the list.
q   A pointer to the query to modify.

add_submitter_restriction ( pr_query_struct * q,
gchar * id )
 

Add the given submitter ID to the submitter restriction list.

By default, the query is not restricted by submitter. If you want to restrict the results by submitter, use this function to add the submitters you want the query restricted to.

Parameters:
id   The login ID of the submitter to add to the list.
q   A pointer to the query to modify.

clear_order_by ( pr_query_struct * q )
 

Clear the order by clause.

Parameters:
q   A pointer to the query structure.

clear_problem_type_restrictions ( pr_query_struct * q )
 

Clear the problem type restrictions for the query.

Parameters:
q   : pointer to the query to modify.

clear_project_restrictions ( pr_query_struct * q )
 

Clear the project restriction list.

Remove any existing project constraints associated with the query. The query is still limited to only the projects that the user has access to.

Parameters:
q   A pointer to the query to modify.

clear_raw_pr_where ( pr_query_struct * q )
 

Clear the raw WHERE clause.

If a raw WHERE clause has been setup via set_raw_pr_where(), it will be cleared by a call to this function. If any restrictions had been setup by calls to 'add' functions, they will be effective again after this call.

Parameters:
q   : the query to modify.

clear_responsible_restrictions ( pr_query_struct * q )
 

Clear the responsible ID restrictions for the query.

Parameters:
q   A pointer to the query to modify.

clear_severity_restrictions ( pr_query_struct * q )
 

Clear the severity restrictions for the query.

Parameters:
q   A pointer to the query to modify.

clear_status_restrictions ( pr_query_struct * q )
 

Clear the status restrictions for the query.

Parameters:
q   A pointer to the query to modify.

clear_submitter_restrictions ( pr_query_struct * q )
 

Clear the submitter restrictions for the query.

Parameters:
q   A pointer to the query to modify.

create_pr_query ( gchar * user_id )
 

Create the basic problem report query.

Allocate a pr_query_struct, and initialize the data to create a basic problem report query. The resulting query returns all problem reports for the projects that the user has access to. The results of the query are, by default, sorted by project, severity, and status. It is the caller's responsibility to destroy the query struct via a call to destroy_pr_query().

This funtion is designed to create a query structure that is a good starting point for further refinment from the end user. The function is best used in 'find' dialogs, or when creating a new user defined query.

Parameters:
user_id   login_id of the current user. This parameter is used to limit the selection to only the projects that the user has access to.

Returns:
A pointer to the query structure. It is the caller's responsibility to destroy the query struct via a call to destroy_pr_query().

create_pr_query_from_table ( PGconn * conn,
const gchar * user_id,
gint query_pk )
 

Create a problem report query, initializing the structure with a query defined in the query table.

Allocate a pr_query_struct, and initialize the data using a query defined in the query table. It is the caller's responsibility to destroy the query struct via a call to destroy_pr_query().

Remember that project constraints are not stored in the query table. By defalt, the query is run against all projects in the current database that the user has access to. Use add_project_restriction() to add more project constraints, if needed.

Parameters:
conn   The database connection to use when getting the query info.
user_id   The login_id of the current user. This is used to limit the selection to only the projects that the user has access to.
query_pk   The primary key for the query to be used.

Returns:
A pointer to the query structure.

create_pr_query_from_table_li ( const gchar * conn_str,
const gchar * user_id,
gint query_pk )
 

Similar to create_pr_query_from_table(), accept this function does a database login rathher than using an existing connetion.

Allocate a pr_query_struct, and initialize the data using a query defined in the query table. It is the caller's responsibility to destroy the query struct via a call to destroy_pr_query().

Remember that project constraints are not stored in the query table. By defalt, the query is run against all projects in the current database that the user has access to. Use add_project_restriction() to add more project constraints, if needed.

This function attempts to login to the database instead of using an existing connection.

Parameters:
conn   The connect string. For details on the connect string syntax, see the function 'PQconnectdb' in the 'libpq' section of the 'PostgreSQL Programmer's Guide'.
user_id   The login_id of the current user. This is used to limit the selection to only the projects that the user has access to.
query_pk   The primary key for the query to be used.

Returns:
A pointer to the query structure.
Return values:
NULL   Failed to login to the database.
non-NULL   Function was successful.

create_query_string ( const pr_query_struct * q )
 

Create an executable SQL query from the query structure.

Create the query string represented by the query structure. The resulting GString is valid SQL that is executable by PostgreSQL.

This function allocates a new GString. It is the callers responsiblity to destroy the GString (use g_string_free()).

Parameters:
q   A pointer to the query to output as a SQL statement.

Returns:
The SQL query string representing the given query.

destroy_pr_query ( pr_query_struct * pr_query )
 

Free the memory, etc.

Free any memory that was allocated for the pr_query_struct.

Parameters:
pr_query   A pointer to the query struct that needs to be destroyed.

set_order_by ( pr_query_struct * q,
const gchar * str )
 

Set the order by clause.

Parameters:
str   The order by clause. \bDO \bNOT include the actual 'ORDER BY' in the string.
q   A pointer to the query structure.

set_raw_pr_where ( pr_query_struct * q,
const gchar * str )
 

Set the WHERE clause manually rather than using the 'set' and 'clear' functions.

Sets the query restrictions to use the raw SQL restrictions provided. Use this function if the 'set' and 'clear' functions will not work for what you want (for example, if you want to test one of the parameters for NULL).

The raw SQL will be appeneded to the WHERE clause of the following SQL statement:

  SELECT prj.name, stat.name, pt.name, sevr.name,
         pr.title, stat.order_num, sevr.order_num,
         pr.problem_num
    FROM project prj, status stat, problem_type pt,
         severity sevr, problem_report pr
   WHERE prj.project_num = pr.project_num
     AND stat.status_num = pr.status_num
     AND sevr.severity_num = pr.severity_num
     AND pt.type_num = pr.type_num
  
Parameters:
str   The raw SQL restriction and ordering string.
q   A pointer to the query to modify.

Warning:
Any restrictions (except project restrictions) setup with the 'add' functions will not apply if this funtion is used.


Generated at Sun Jan 7 09:55:03 2001 for libPRepS by doxygen1.2.3 written by Dimitri van Heesch, © 1997-2000