Index of /download/eloq/beta/B0710/fwutil/old

Icon  Name                               Last modified      Size  
[PARENTDIR] Parent Directory                                        -   
[   ] fwutil-pa20-61205.tar.gz           2006-12-05 16:41   62K  
[   ] fwutil-70130-win32.zip             2007-02-02 01:21   65K  
[   ] fwutil-70130-linux-glibc2.2.tar.gz 2007-02-02 01:20   44K  
[   ] fwutil-70130-hpux-pa20.tar.gz      2007-02-02 01:20  184K  
[   ] fwutil-70130-hpux-pa11.tar.gz      2007-02-02 01:20   66K  
[   ] fwutil-70130-hpux-ia64.tar.gz      2007-02-02 01:20  265K  
[TXT] README                             2006-12-05 16:41  9.0K  

FWUTIL library
==============

Revision: B.07.10.03
Document: Draft, 2006-12-04

Copyright 2006 Marxmeier Software. All rights reserved.

** Note ** 
This documentation is an early draft and may be incomplete 
and contains mistakes. Any information is subject to change 
without notice. Your feedback is kindly requested 
(support@marxmeier.com)


Introduction
============

The fwutil library enables access to the Eloquence database 
forward log file that holds the archived committed transactions.

Decoding the fwlog file format is performed by the fwutil 
library and a callback to a user provided function is performed
for IMAGE like operations which simplifies programming and 
isolates the utility from format changes.

The fwutil library works incrementally. Transactions from a
starting point are processed. The current progress is recorded
in a status file and may be used to continue subsequently.
Once the end of the fw log file(s) is reached, the library
may either return or wait for additional changes which are 
then processed.

The fwutil library makes use of the audit information in the
forward log file and the database server must be configured 
to record audit information.


Installation
============

The distribution archive holds the following files:

README - this file
fwutil.h - header file
libfwutil.sl - shared library
fwtest.c - example program source code
fwsql.c - example program source code

Unpack the archive file in a temporary location and move the
following files as shown:

fwutil.h -> /opt/eloquence6/include
libfwutil.sl -> /opt/eloquence6/lib/pa20_32/


Example code
============

Two example programs are provided:

fwtest.c - print some information on database transactions
fwsql.c  - convert database changes to SQL like syntax

Comple/link the example code as below (HP-UX)

cc -Ae -O fwtest -I/opt/eloquence6/include fwtest.c \
   -L/opt/eloquence6/lib/pa20_32 -lfwutil


Library functions
=================

The fwutil.h include file provides the function prototypes
and types.  It must be included in any file that makes use
of the fwutil library.

#include "fwutil.h"

The fwutil.h file is installed in the Eloquence include 
subdirectory.


Fwu_version
-----------

Output the fwutil library version (to stdout)

void Fwu_version(void);


Fwu_status
----------

Output the fwutil status file (to stdout)

int Fwu_status(const char *status_file, int verbose);

Arguments:
status_file specifies the name of the status file
if verbose is non-zero then the full content is printed

Returns:
Completion status, 0 for success, -1 on failure.


Fwu_synconly
------------

If called with a non-zero argument specifies that Fwu_process() 
should return once the end of the fwlog file(s) was reached.  

void Fwu_synconly(int mode);

Arguments:
0 = wait for new transactions after reaching the end
    of the fw log file(s).  This is the default.
1 = return after reaching the end of the fw log file(s)


Fwu_verbose
-----------

If called with a non-zero argument specifies that Fwu_process() 
should output additional progress messages (to stderr).

void Fwu_verbose(int mode);

Arguments:
0 = Don't print progress messages. This is the default
1 = Output additional debug messages (to stderr)

This is similar to setting the FWUTIL_DEBUG_FLAGS environment
variable to "*1".


Fwu_process
-----------

Process archived transations.

int Fwu_process(Fwu_callback_t cb, const char *cfg_file, 
             const char *status_file,
	     const char *fwr_start);

Arguments:
- cb specifies a pointer to a user provided callback function.
This function is called for image-like changes(see below).
- cfg_file specifies the name of the server configuration file
(eloqdb6.cfg). This is used to locate the fwlog files.
- status_file specifies the name of the fwutil status file.
- The fwr_start argument may be used to specify a starting point
when processing any archived transactions. If set, the 
status file is initialized. NULL should be specified to use the 
status file.


Returns:
Completion status, 0 for success, -1 on failure.
On failure, a message is printed to stderr.

Discussion:

By default, the fwutil library processes all enqueued changes and 
then closely follows any on-going changes on the server.  
If the Fwu_synconly() function was called with a non-zero argument,
Fwu_process() returns once all enqueued changes are processed.

The fwutil library uses a local file to maintain its most recent
sucessfully executed call. The status file may be specified with the
status_file argument and defaults to fwutil.stat in current directory.

The Fwu_status() fucntion outputs the content of the status file. 
If Fwu_verbose() was called with a non-zero argument all details are
output, otherwise only information on the most recently completed 
call is output.

The fwr_start argument is used to specify the forward log file that 
the fwutil library should be starting with.  It is required on the 
first use and may also be used to specify a different starting point. 
If not specified, the position is obtained from the status file.
The fwr_start argument uses a syntax of "gen[-seg[.action]]" where 
gen specifies the generation of the forward log file, the optional 
seg specifies a file segment and the optional action specifies a 
specific action in this file. Typically only the generation is used.


Fwu_callback_t
--------------

This defines the prototype of a user-defined callback function.

typedef int (*Fwu_callback_t)(int db_node_id, const char *db_name, 
                   const char *set_name, time_t timestamp, 
		   enum Fwu_OP op, unsigned int recno, int recsz,
                   const void *bi_rec, const void *ai_rec);

Arguments:
- db_node_id specifies the internal id of the database. This value
is unique for each database.
- db_name specifies the database name.
- set_name specifies the data set name.
- timestamp specifies the time when the transaction was recorded
(seconds since 1.1.1970 UTC).
- op specifies the IMAGE call (Fwu_OP_UPDATE/Fwu_OP_PUT/Fwu_OP_DELETE).
- recno specifies the record number.
- recsz specifies the record size in bytes (as specified in schema).
- bi_rec provides a pointer to a buffer holding the previous record
data. This is present for an UPDATE and DELETE call. Otherwise a
NULL pointer is passed.
- ai_rec provides a pointer to a buffer holding the updated record
data.  This is present for a PUT and UPDATE call. Otherwise a NULL
pointer is passed.

Returns:
Completion status, 0 for success, -1 on failure.


Fwu_get_item
------------

Retrieve schema information.  Obtains next item definition
in schema order.

int Fwu_get_item(const char **i_name, int *i_type, 
	                int *i_size, int *i_count, unsigned int *i_fmt);

Arguments:
i_name is set to a NUL terminated pointer to the item name.
i_type is set to the native item type (X/U/B/I/K/E/P/Z).
i_size is set to the item size (in bytes).
i_count is set to the item count.
i_fmt is set to the item format.

Returns:
Completion status, 0 if no schema information available, 1 on success.


Fwu_CurrentLogGeneration
------------------------

Returns the current fw log file generation.

unsigned int Fwu_CurrentLogGeneration(void);


Fwu_CurrentLogSequence
----------------------

Returns the current fw log file sequence (within a generation).

unsigned int Fwu_CurrentLogSequence(void);


Fwu_CurrentTagSequence
----------------------

Returns the sequence number of the current transaction that is 
processed within the current fw log file.

unsigned int Fwu_CurrentTagSequence(void);


Utility functions
=================

The following utility functions for converting numeric data into
text format are included in the library. The prototypes are 
currently not defined in the fwutil.h header file and the function 
names are likely to change in the future.

int idb__fmt_signed_int(char *buf_p, int buf_sz, 
                        const void *v_p, int v_len);

Convert signed integer of 2/4/8 bytes

int idb__fmt_unsigned_int(char *buf_p, int buf_sz, 
                        const void *v_p, int v_len);

Convert unsigned integer of 2/4/8 bytes

int idb__fmt_ieee_float(char *buf_p, int buf_sz, 
                        const void *vp, int len);

Convert ieee float of 4/8 bytes

int idb__fmt_packed(char *buf_p, int buf_sz, 
                        const void *v_p, int v_len);

Convert value in packed format (positive/negative/unsigned)

int idb__fmt_zoned(char *buf_p, int buf_sz, 
                        const void *v_p, int v_len);

Convert value in zoned format (positive/negative/unsigned)

Arguments:
buf_p specifies the pointer to a (user provided) conversion buffer.
buf_sz specifies the size of the conversion buffer.
v_p specifies the pointer to the data value.
v_len specifies the size of the data value in bytes.

Returns:
returns 0 on success, -1 on error, 1 on buffer overflow

The output buffer is NUL terminated.

Example use:

int err;
static char cv_buf[256];

int err = idb__fmt_signed_int(cv_buf, sizeof(cv_buf), buf, size);
assert(!err);
printf("%s\n", cv_buf, strlen(cv_buf));


Environment variables
=====================

The FWUTIL_DEBUG_FLAGS environment variable may be used to
define fwutil debug mode.