/*
 ******************************************************************************
 *  Copyright 1984-1993 United States Data Corporation. All Rights Reserved.
 ******************************************************************************
 *                                - NOTICE -
 *
 *  The information contained herein is confidential information of United
 *  States Data Corporation, a Delaware corporation, and is protected by
 *  United States copyright and trade secret law and international treaties.
 *  This information is not to be disclosed, used or copied by or transferred
 *  to any individual, corporation, company or other person without the
 *  express written permission of United States Data Corporation.
 ******************************************************************************
 *
 * Module:	HDT_DBS.H
 *
 *	Header file for database session API.
 *
 * History:
 *		bjc 04/29/93	Created. 
 */


#ifndef _DBS_INCLUDED
#define _DBS_INCLUDED

#include <hdt_base.h>		/* Base Definitions for the API */
#include <hdt_dbc.h>

/*
 ************************************************************************
 *                              Constants                               *       
 ************************************************************************
 */

/*
 *  DB Session Structure flags
 */

#define DBS_CLOG_ON	0x0001		/* log session activity */


/*
 *  DBS Function Constants
 */

#define DBS_SYNC	0		/* sync/async operation constants */
#define DBS_ASYNC	1

#define DBS_NO_COMMIT	0		/* flags for dbs_exec_immediate() */
#define DBS_COMMIT	1

#define DBS_READ	DBC_READER	/* read/write operation constants */
#define DBS_WRITE	DBC_WRITER

#define DBS_LEN_EMSG	256		/* maximum error message length */
#define DBS_LEN_QBUF	5119		/* maximum length of query buffer */

/*
 *  Or-wise flags for function dbs_commit() 
 */

#define DBS_COMMIT_FORCE	0x0001		/* force commits */
#define DBS_COMMIT_READER	0x0002		/* commit reader only */
#define DBS_COMMIT_WRITER	0x0004		/* commit writer only */


/*
 ************************************************************************
 *                              Structures                              * 
 ************************************************************************
 */

/*
 *  DBSM hook function to be called by the session before it attempts to
 *  perform an operation that requires an open session.
 */

typedef void (*DBSM_NOTIFY) (void*, void*);

/* 
 * DBS - DataBase Session structure
 *
 * A database session structure denotes two open historian sessions between 
 * the task and an historian.  One session is a reader, the other is a writer.
 * Chained from each session is a linked list of open statements (cursors)
 * for the session.
 */

typedef struct _dbs
{
	id_t		task_id;		/* task id for connection */
	char		*alias;			/* historian alias for db */
	HSD_SESSIONID	*read_sessid;		/* reader historian session */
	HSD_SESSIONID	*write_sessid;		/* writer historian session */
	TAG		send_mbx;		/* send mbx to historian */	
	TAG		recv_mbx;		/* receive mbx to historian */	
	DBC		*cursors; 		/* link list; sess' cursors */
	short		commit_writer;		/* writer sess commit flag */
	short		commit_reader;		/* reader sess commit flag */
	short		attached;		/* number of users of sess */
	short 	flags;			/* general tuning flags */
	HS_DA		*hdttypes;    /* mapping of hdt datatypes */

	/*
	 *  The following are DBSM hooks for session grouping and management.
	 */

	void		*dbsm;			/* pointer to its DBSM */
	DBSM_NOTIFY	*dbsm_notify;		/* inform DBSM of activity */
	int		olock;			/* never invol. close sess */
	struct _dbs	*next;			/* linked list of sessions */
} DBS;


/*
 ************************************************************************
 *                              Macros                                  *       
 ************************************************************************
 */

#define dbs_get_task_id(p)	((p)->task_id)
#define dbs_get_alias(p)	((p)->alias)
#define dbs_get_send_mbx(p)	((p)->send_mbx)
#define dbs_get_recv_mbx(p)	((p)->recv_mbx)
#define dbs_get_attached(p)	((p)->attached)

#define dbs_get_flags(p)	((p)->flags)
#define dbs_set_flags(p, flg)	((p)->flags = flg)

/*
 *  DBSM hook macros
 */

#define dbs_set_olock_on(p)		((p)->lock = TRUE)
#define dbs_set_olock_off(p)		((p)->lock = FALSE)
#define dbs_set_dbsm(p, _dbsm)		((p)->dbsm = (void*) _dbsm)
#define dbs_set_dbsm_notify(p, func)	((p)->dbsm_notify = func)

/*
 *  Client log function - macro saves a function call when not logging.
 */

#define dbs_post_clog(dbs, rw_mode, hs_func, sql_stmt)		\
	if ((dbs_get_flags(dbs) & CLOG_SQL) 			\
	 || (Clog_flags & CLOG_SQL)) 				\
		dbs__post_clog(dbs, rw_mode, hs_func, sql_stmt)

/*
 ************************************************************************
 *                           Global Variables                           *       
 ************************************************************************
 */

extern char	*Dbs_qbuf;		/* query buffer */


/*
 ************************************************************************
 *                         Function Prototypes                          * 
 ************************************************************************
 */
#ifdef __cplusplus
extern "C" {
#endif
/*
 *  Database session construction/destruction
 */

extern DBS*	dbs_create(char *alias, TAG *send_mbx, 
		           TAG *recv_mbx, id_t task_id);
extern int	dbs_destroy(DBS *dbs);	
extern int	dbs_open(DBS *dbs, int rw_mode);
extern int	dbs_close(DBS *dbs, int rw_mode, int detach);
extern int	dbs_attach(DBS *dbs, int open_flags);
extern int	dbs_detach(DBS *dbs);


/*
 *  Session cursor routines
 */

extern DBC*	dbs_init_cursor(DBS *dbs, char *sql_stmt,  
		                int rw_mode, short cache_size);

extern int	dbs_attach_cursor(DBS *dbs, DBC *dbc);

extern DBC*	dbs_find_cursor1(DBS *dbs, char *sql_stmt);

extern DBC*	dbs_find_cursor2(DBS *dbs, void *qgroup, 
		                void *qmember, void *qinstance);

extern int	dbs_detach_cursor(DBC *dbc);

extern int	dbs_close_by_qinst(DBS *dbs, void *qinstance, 
		                   DBC_CMP_QINST qinst_cmp, int detach);


/*
 *  Misc. database session utility routines.
 */

extern int	dbs_describe_sql(DBS *dbs, char *sql, 
		                 HS_DA **select, HS_DA **params);

extern int	dbs_describe_table(DBS *dbs, char *tblname, HS_DA **tbl_da);

extern int	dbs_set_tblmaxrec(DBS *dbs, char *tblname, u32 maxrec);
extern int	dbs_schema_create(DBS *dbs, char *schema, char *tblname);
extern int	dbs_set_readonly(DBS *dbs);
extern void	dbs_reset_csr_stat(DBS *dbs, int rw_mode);
extern PFH	dbs_map_syncmode(int);
extern void	dbs_upd_hs_shut(id_t task_id);

extern int	dbs_get_hist_id(DBS *dbs);
extern int	dbs_get_hist_taskid(DBS *dbs);
extern u32	dbs_get_sess_type(DBS *dbs);
extern int	dbs_commit(DBS *dbs, int flags, int sync);
extern int	dbs_exec_now(DBS *dbs, char *sql_stmt, int rw_mode, int sync);

extern void	dbs__post_clog(DBS *dbs, int rw_mode, 
		               int hs_func, char *sql_stmt);

#ifdef __cplusplus
}
#endif

#endif

