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 __BEGIN_DECLS
#define __END_DECLS
#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
#define SUBMITTER_POS   8
#define RESPONSIBLE_POS   9
#define CREATION_DATE_POS   10

Typedefs

typedef 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:
Kenneth W. Sodemann (stuffle@charter.net)
Revision:
1.11
Date:
2002/01/30 00:40:02


Define Documentation

#define CREATION_DATE_POS   10
 

Define the position of the cration date timestamp for the current problem report 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 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 RESPONSIBLE_POS   9
 

Define the position within the select clause of the problem report query for the login ID of the person to whom the problem report is currently assigned. Only the login id is returned, not the full name.

#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.

#define SUBMITTER_POS   8
 

Define the position of the submitter's login id within the select clause of the problem report query. Only the login id is returned, not the full name.


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 on Sun Oct 20 18:15:10 2002 for libPRepS by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002