Taurus Software - Downloads


		Home \| Contact Us

EloCap Tutorial

Table of Content

Introduction

Check you environment

Create source and target objects

Generate forward-log transactions

Generate the Message File transactions

Apply the Message File transactions to the target

APPENDIX (other commands and considerations)

Introduction

The EloCap Tutorial builds a working example that

posts inserts to an Eloquence dataset.
generates capture file transactions from the resulting Eloquence forward-log entries.
applies these transactions to a target database table.

The working example will simulate the standard EloCap work-flow :

Eloquence -> forward-log -> elocap -> Capture File -> Warehouse script -> target database

This tutorial assumes that the EloCap release is at minimum version 2.21.

This tutorial is not intended to be a substitute for product documentation, whether Eloquence, EloCap, Studio, Warehouse, or the target database itself.

Eloquence product documentation is available at the Marxmeier Software AG site:

http://eloquence.marxmeier.com/doc/

EloCap documentation is available in the product distribution README files.

Other Taurus product documentation is available at the Taurus Software site:

http://www.taurus.com/self-serve/Docs/n_documentation.html

query3k product documentation is available at the Marxmeier Software AG and at the HP QUERY/IX documentation sites, respectively:

http://eloquence.marxmeier.com/doc/

http://docs.hp.com/en/32650-90889/

This tutorial also assumes that you are familiar with basic Bourne shell commands or equivalent. You will need Eloquence dba privileges to manipulate the database as well as system privileges to execute the Eloquence utilities. See your Eloquence DBA and your System Administrator.

The structure of this tutorial is linear and command-driven. In practice, the order in which you choose to use some of these commands may differ. Also included at http://www.taurus.com/self-serve/elocap/ElocapDownloads.html is a zip file that contains a schema and Warehouse script code.

The example target database is SQL Server. The source Eloquence platform is HP-UX and the accompanying scripts are written to run on this source platform. In order to run the scripts on the Windows target system or to specify a different target database type, please modify the script OPEN statements accordingly.

Files included are:

applyMFTrans.wh - Warehouse script applies Message File transactions to the target table PARTS
capsamp.schema - DDL creates the sample Eloquence database
listMFTrans.wh - Warehouse script lists the Message File transactions
makeEloTrans.wh - Warehouse script populates PARTS.CAPSAMP, generating forward-log entries

The OPEN statements in these Warehouse scripts will require changes for your specific environment.

The tutorial consists of two sections : the tutorial proper that follows this introduction and an Appendix section containing useful syntax and considerations.

Check your environment

Set environmental variables based on your own configuration and Eloquence version:

These settings are useful as the operational files are located in numerous directories on the system.

export ELOQUENCE_RC=/sbin/init.d

export ELOQUENCE_HOME=/opt/eloquence6

export ELOQUENCE_CONFIG_DIR=/etc/opt/eloquence6

export ELOQUENCE_DATA_DIR=/var/elodata

export ELOQUENCE_FWLOG_DIR=/opt/eloquence6/taurus/fwlogs

export ELOCAP_HOME=/home/qa/elocap

export WHHOME=/users/whii/inhouse

Note : directories will likely have different pathnames than those listed above. If you have installed the elocap executable in your Warehouse directory, then ELOCAP_HOME and WHHOME should contain the same path value.

Check that the Eloquence subsystem is up and running:

The rc script has a release-specific name. For example, if you are running Eloquence version 8, it will be named eloq8.

$ $ELOQUENCE_RC/eloq6 status

eloqsd process is active (pid 2257) [running]
eloqdb6[eloqdb] process is active (pid 2267) [running]

$ ps -aef | grep eloqdb6 | grep -v grep | sort

eloq 2267 1 0 May 30 ? 3:35 eloqdb6: active
eloq 2268 2267 0 May 30 ? 0:02 eloqdb6: io thread 2267:1
eloq 2269 2267 0 May 30 ? 0:00 eloqdb6: io thread 2267:2
eloq 2271 2267 0 May 30 ? 0:00 eloqdb6: io thread 2267:3
eloq 2272 2267 0 May 30 ? 0:00 eloqdb6: io thread 2267:4

List the Eloquence data files:

The data file path and names are found in the current Eloquence configuration file located in the $ELOQUENCE_CONFIG_DIR directory. The information is located in the [Volumes] section of the configuration file.

$ ls -l $ELOQUENCE_DATA_DIR/*.vol total 28672
-rw------- 1 eloq eloq 8912896 Jun 17 09:57 taurusdata.vol
-rw------- 1 eloq eloq 5767168 Jun 17 15:56 tauruslog.vol

List the Eloquence users:

$ $ELOQUENCE_HOME/bin/dbdumpcat -t 30

-----------------------------------------------------
#30 sysuser (2 entries)
-----------------------------------------------------
|uid |name                |password        |priv     |
-----------------------------------------------------
|1   |dba                 |NULL            |00000003 |
|2   |public              |NULL            |00000004 |
-----------------------------------------------------

Determine the status of Eloquence forward-log generation:

$ $ELOQUENCE_HOME/bin/dbctl -u dba forwardlog status

Forward-logging is enabled.
Forward-log is '/opt/eloquence6/taurus/fwlogs/FwLog130-1.log'.

Begin a new forward-log:

$ $ELOQUENCE_HOME/bin/dbctl -u dba forwardlog restart

Forward-logging has been restarted.
Forward-log is '/opt/eloquence6/taurus/fwlogs/FwLog131-1.log'.

If the restart command returns with the message:

P0: forward-logging is not enabled - request ignored

then issue the enable command

$ $ELOQUENCE_HOME/bin/dbctl -u dba forwardlog enable

followed by the forwardlog restart command

$ $ELOQUENCE_HOME/bin/dbctl -u dba forwardlog restart

Forward-logging has been restarted.
Forward-log is '/opt/eloquence6/taurus/fwlogs/FwLog130-1.log'.

Note : the creation of new forward-log is by default deferred until next on-line backup or restart.

List the current Eloquence forward-logs:

$ ls -ltr $ELOQUENCE_FWLOG_DIR

-rw-rw-rw- 1 eloq eloq 524181 May 30 11:04 FwLog126-1.log
-rw-rw-rw- 1 eloq eloq 2498233 Jun 11 08:41 FwLog128-1.log
-rw-rw-rw- 1 eloq eloq 835519 Jun 11 09:17 FwLog129-1.log
-rw-rw-rw- 1 eloq eloq 1280894 Jun 17 09:52 FwLog130-1.log
-rw-rw-rw- 1 eloq eloq 36 Jun 17 09:52 FwLog131-1.log

Extract and review the Eloquence forward-log configuration In the Eloquence configuration file:

The Eloquence configuration file will have an Eloquence release-specific name.

$ egrep -v "^#|^\[|^$" $ELOQUENCE_CONFIG_DIR/eloqdb6.cfg
ServiceHttp = 18180
UID = eloq
GID = eloq
EnableIPC = 0
SyncMode = 1
EnableAudit = 1
FwLog = /opt/eloquence6/taurus/fwlogs/FwLog%N.log
allow = all
Root = /c/elodata/taurusdata.vol
Log02 = /c/elodata/tauruslog.vol

This information is also available through a web browser if Eloquence's ServiceHttp capability has been enabled in the configuration file (default is off).

For example, if Eloquence is running on mysys.mydomain.com and the ServiceHttp name has been set to a port value of 18180 as above, then the browser link to the Eloquence configuration information would be:

http://mysys.mydomain.com:18180/config

Ensure that elocap is fwutil-aware:

$ $ELOCAP_HOME/elocap -version

EloCap - 1.60
FWUTIL B.07.10.06 (build Mar 19 2008)

In order to load the required shared library libfwutil.sl, the LD_LIBRARY_PATH environmental variable may need to be set to the Eloquence library directory. For example, if you are running Eloquence version 8 and the relevant library directory is /opt/eloquence/8.0/lib/hpux32, then export as follows :

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/eloquence/8.0/lib/hpux32

List the current Eloquence databases:

$ $ELOQUENCE_HOME/bin/dbdumpcat -t 31

-------------------------------------------
#31 sysdb (12 entries)
-------------------------------------------
|dbid|name                |flags   |nodeid|
-------------------------------------------
|11  |SALES               |00000004|100   |
|12  |SALES2              |00000004|135   |
|13  |ODB                 |00000004|170   |
|14  |ODB2                |00000004|186   |
|15  |MANYT               |00000004|202   |
|16  |MACITM              |00000004|216   |
|17  |TSALES              |00000004|380   |
|18  |TSALE1              |00000004|416   |
|25  |DEMODB              |00000004|662   |
|150 |WHTST0              |00000004|4665  |
|151 |WHTST1              |00000004|4697  |
|153 |MARKSAMP            |00000004|4755  |
-------------------------------------------

Create source and target objects

Create sample database CAPSAMP using the provided schema:

$ $ELOQUENCE_HOME/bin/dbschema -T capsamp.schema

ELOQUENCE SCHEMA (C) Copyright 2005 Marxmeier Software AG (B.07.10)
PAGE 1 CAPSAMP ELOQUENCE SCHEMA PROCESSOR B.07.10

Item name count         : 33
Index item name count   : 7
Data set count          : 5
Collating sequence count: 0

*** Database catalog created

$ $ELOQUENCE_HOME/bin/dbcreate capsamp

List current Eloquence databases:

$ $ELOQUENCE_HOME/bin/dbdumpcat -t 31

-------------------------------------------
#31 sysdb (13 entries)
-------------------------------------------
|dbid|name               |flags    |nodeid|
-------------------------------------------
|11  |SALES              |00000004 |100  |
|12  |SALES2             |00000004 |135  |
|13  |ODB                |00000004 |170  |
|14  |ODB2               |00000004 |186  |
|15  |MANYT              |00000004 |202  |
|16  |MACITM             |00000004 |216  |
|17  |TSALES             |00000004 |380  |
|18  |TSALE1             |00000004 |416  |
|25  |DEMODB             |00000004 |662  |
|150 |WHTST0             |00000004 |4665 |
|151 |WHTST1             |00000004 |4697 |
|153 |MARKSAMP           |00000004 |4755 |
|154 |CAPSAMP            |00000004 |4781 |
-------------------------------------------

Ensure that Warehouse sees the CAPSAMP database:

$ $WHHOME/warehouse

Warehouse 3.02.5767-G (c) Taurus Software, Inc. 2008
Installed for: Taurus Software, Inc.
1> open db image capsamp mode=5
2> list db

Dataset Name    Type  RecSize    Entries   Capacity
CUSTOMERS       M     202        0         0
PARTS           M     94         0         0
ID              A     2          0         0
ORDERS          D     32         0         0
LINEITEMS       D     28         0         0

3> show db PARTS

Dataset Name Type RecSize Entries Capacity
PARTS M 94 0 0

Dataitem Name        Type
PARTNO               X16      Key item
PARTLOOKUP           X10
DESCRIPA             X20
DESCRIPB             X20
PARTUNIT             X2
PROFITGROUP          X4
MATNUMBER            X16
PRICEUNIT            X2
PRICE1               I1
PRICE2               I1

Create a table named PARTS in the target database:

To create the PARTS table, use Databridger Studio (better) or run the Warehouse Client to generate the DDL as follows. Then use the target database's management utility to apply the DDL.

$ $WHHOME/warehouse

Warehouse 3.02.5770-G (c) Taurus Software, Inc. 2008
Installed for: Taurus Software, Inc.
1> open db image capsamp mode=5
2> describe db.PARTS using odbc creates

CREATE TABLE PARTS (
PARTNO            CHAR(16) NOT NULL,
PARTLOOKUP        CHAR(10) NOT NULL,
DESCRIPA          CHAR(20) NOT NULL,
DESCRIPB          CHAR(20) NOT NULL,
PARTUNIT          CHAR(2) NOT NULL,
PROFITGROUP       CHAR(4) NOT NULL,
MATNUMBER         CHAR(16) NOT NULL,
PRICEUNIT         CHAR(2) NOT NULL,
PRICE1            SMALLINT NOT NULL,
PRICE2            SMALLINT NOT NULL );

Note : the command describe db using odbc creates generates DDL for all tables in the capsamp database.

Generate forward-log transactions

Insert two rows to the CAPSAMP.PARTS Eloquence dataset:

$ $WHHOME/warehouse -start makeEloTrans.wh

Database Name

Dataset Name Reads Writes Updates Deletes

DB: IMAGE capsamp
PARTS 0 2 0 0

Inspect the generated FwLog transactions for CAPSAMP.PARTS activity using the fwaudit utility:

$ $ELOQUENCE_HOME/bin/fwaudit -rv -e'CAPSAMP.PARTS' $ELOQUENCE_FWLOG_DIR/FwLog131-1.log

processing file: /opt/eloquence6/taurus/fwlogs/FwLog131-1.log

SIGN-ON session:278
protocol{8os{HPUXip{127.0.0.1user{marklogin{public
uid{106pid{21869pname{/users/whii/inhouse/warehouse -start makeEloTrans.wh

DBPUT CAPSAMP.PARTS (#4795) recno:8 session:278
timestamp: 2008-06-17 09:57:02
PARTNO : "0000000000000001"
PARTLOOKUP : ""
DESCRIPA : "PN-00001"
DESCRIPB : ""
PARTUNIT : ""
PROFITGROUP : ""
MATNUMBER : "00001"
PRICEUNIT : ""
PRICE1 : 150
PRICE2 : 175

DBPUT CAPSAMP.PARTS (#4795) recno:9 session:278
timestamp: 2008-06-17 09:57:02
PARTNO : "0000000000000002"
PARTLOOKUP : ""
DESCRIPA : "PN-00002"
DESCRIPB : ""
PARTUNIT : ""
PROFITGROUP : ""
MATNUMBER : "00002"
PRICEUNIT : ""
PRICE1 : 250
PRICE2 : 275

Generate the Message File transactions

Create a Message File of insert transactions in the current directory:

1. example uses a Standard Header

2. example uses -synconly

3. as -dset format is DB:DATASET, CAPSAMP:@ is all CAPSAMP datasets

4. see Appendix for Ascii Capture File and extended header generation

$ $ELOCAP_HOME/elocap \
    -start 131 -synconly \
    -cfg $ELOQUENCE_CONFIG_DIR/eloqdb6.cfg \
    -stat capsamp.stat \
    -pidfile capsamp.pid \
    -fga -dset CAPSAMP:@ capsamp.msg \
    -verbose -showskip -capstats

06-17-08 10:03:45 22693 Setup capture file capamp.msg header, size=62
06-17-08 10:03:45 22693 Opened pid file capsamp.pid, #3
06-17-08 10:03:45 22693 Closed pid file capsamp.pid, #3
R1: processing forward-log file: '/opt/eloquence6/taurus/fwlogs/FwLog131-1.log'
06-17-08 10:03:45 22693 Opened capture file capamp.msg, #5
R1: replication is up-to-date until 2008-06-17 09:58:38
2 Eloquence forward log file records processed.
Current position=131-1.27

Number of records written to capture files:

Capture file: capsamp.msg
Capture file -dset : CAPSAMP:@

Database CAPSAMP Inserts Updates Deletes Total
PARTS 2 0 0 2

Log records not copied to any capture file:
* No records skipped. All records copied to a capture file.
06-17-08 10:03:45 22693 Closed capture file capamp.msg, #5

Note : add the parameter -dumprecs for a hex listing of raw records as they are read from the Eloquence log files and written to the capture file.

List the Message File transaction headers:

$ $WHHOME/warehouse -start listMFTrans.wh
06-AUG-2008 14:14:18 : begin

Expected Capture File generation options : REGHDR, YY

TX# 1

         SEQ 000000
         FILENAME CAPSAMP
         GROUPNAME
         ACCTNAME
         DSETNAME PARTS
         TXDATE 080617
         TXTIME 09:57:02
         TXTYPE IP

TX# 2

         SEQ 000001
         FILENAME CAPSAMP
         GROUPNAME
         ACCTNAME
         DSETNAME PARTS
         TXDATE 080617
         TXTIME 09:57:02
         TXTYPE IP

      2 total records read
      2 IP inserts
      0 IU updates
      0 ID deletes
      0 unknown type

06-AUG-2008 14:14:18 : end

Database Name
Dataset Name Reads Writes Updates Deletes
CAPFIL: FIXED capsamp.msg
2 0 0 0

Elapsed time: 0:00:00, cpu time 0:00:00.0

Apply the Message File transactions to the target

Apply the Message File insert transactions to the target table PARTS:

Note : it is preferable that you generate this script using Studio.

$ $WHHOME/warehouse -start applyMFTrans.wh

Database Name
    Dataset Name            Reads     Writes     Updates     Deletes
MSGFILE: FIXED /home/mark/capsamp.msg
                                2          0           0           0
QA2_MATEST: REMOTE qa2 ODBC matest
    DBO.PARTS                   0          2           0           0

List the inserts to table PARTS (any client can be used for listing purposes):

c:\>"C:\Program Files\Microsoft SQL Server\80\Tools\BINN\osql.exe" -E -d matest

1> select * from PARTS

2> go

PARTNO           PARTLOOKUP DESCRIPA             DESCRIPB             PARTUNIT PROFITGROUP MATNUMBER
PRICEUNIT PRICE1 PRICE2
---------------- ---------- -------------------- -------------------- -------- ----------- ----------------
--------- ------ ------
0000000000000001            PN-00001                                                       00001
          150    175

0000000000000002            PN-00002                                                       00002
          250    275

(2 rows affected)

APPENDIX (other commands and considerations)

List the Eloquence database opens:

$ $ELOQUENCE_HOME/bin/dbctl list db

Database Ref WrShrd WrExcl RdShrd RdExcl WrSngl
---------------- ---- ------ ------ ------ ------ ------
capsamp 2 1 0 1 0 0

List the CAPSAMP dataset opens:

There are 2 remote Warehouse Client OPENs, one read-mode and one write-mode.

$ $ELOQUENCE_HOME/bin/dbctl list dbopen capsamp

TID  IP ADDR             M   User / Login
---- ------------------- --- ------------------------------------------8    127.0.0.1:50211     9   mark / public
     uid{106pid{25909pname{/users/whii/inhouse/whserv
9    127.0.0.1:50215     1 mark / public
     uid{106pid{26134pname{/users/whii/inhouse/whserv

List the current Eloquence sessions:

$ $ELOQUENCE_HOME/bin/dbctl list session

TID  IP ADDR              User / Login
---- -------------------- -------------------------------------------
8    127.0.0.1:50211      mark / public
     uid{106pid{25909pname{/users/whii/inhouse/whserv
9    127.0.0.1:50215      mark / public
     uid{106pid{26134pname{/users/whii/inhouse/whserv

List the Eloquence system objects:

The Id column is the Eloquence object type that you would query with -t flag.

$ $ELOQUENCE_HOME/bin/dbdumpcat -l

ELOQUENCE DBDUMPCAT (C) Copyright 2005 Marxmeier Software AG (B.07.10)
-------------------------------------------------
| Server catalog                                |
| localhost:eloqdb                              |
|-----------------------------------------------|
| Id | Name                             | Count |
|-----------------------------------------------|
| 20 | sysobjects                       |   529 |
| 21 | sysdevices                       |     2 |
| 22 | sysvat                           |     0 |
| 30 | sysuser                         |     2 |
| 31 | sysdb                            |    14 |
| 32 | systables                        |    10 |
| 33 | syscolumns                       |    65 |
| 34 | sysindex                         |     0 |
| 35 | sysindexseg                      |     0 |
| 36 | syscollate                       |     0 |
-------------------------------------------------

Drop the CAPSAMP database:

$ $ELOQUENCE_HOME/bin/dbpurge CAPSAMP

Create an abbreviated text report of forward-log contents:

Specify log file name or '*' to check all forward-log files.

$ $ELOQUENCE_HOME/bin/fwaudit -r $ELOQUENCE_FWLOG_DIR/FwLog131-1.log

SIGN-ON session:278
protocol{8os{HPUXip{127.0.0.1user{marklogin{public
uid{106pid{21869pname{/users/whii/inhouse/warehouse -start makeEloTrans.wh
DBPUT CAPSAMP.PARTS (#4795) recno:8 session:278
timestamp: 2008-06-17 09:57:02
DBPUT CAPSAMP.PARTS (#4795) recno:9 session:278
timestamp: 2008-06-17 09:57:02

Check on forward-log consistency:

Specify log file name or '*' to check all forward-log files.

$ $ELOQUENCE_HOME/bin/fwaudit $ELOQUENCE_FWLOG_DIR/*

ELOQUENCE FWAUDIT (C) Copyright 2005 Marxmeier Software AG (B.07.10)
WARNING: file generation mismatch in file
/opt/eloquence6/taurus/fwlogs/FwLog128-1.log
found: 128, expected:127
information from 1 forward-log generation(s) is apparently missing

Create an Ascii Capture File of insert transactions in the current working directory:

1. example uses a Standard Header

2. example uses -synconly

3. example uses -ascii

$ $ELOCAP_HOME/elocap \
-start 131 -synconly \
-cfg $ELOQUENCE_CONFIG_DIR/eloqdb6.cfg \
-stat capsamp.stat \
-pidfile capsamp.pid \
-fga -dset CAPSAMP:@ -ascii capsamp.asc \
-verbose -showskip -capstats

06-17-08 14:11:39 15641 Setup capture file capsamp.asc header, size=62
06-17-08 14:11:39 15641 Opened pid file capsamp.pid, #3
06-17-08 14:11:39 15641 Closed pid file capsamp.pid, #3
R1: processing forward-log file: '/opt/eloquence6/taurus/fwlogs/FwLog131-1.log'
06-17-08 14:11:39 15641 Opened capture file capsamp.asc, #6
R1: replication is up-to-date until 2008-06-17 14:09:10
2 Eloquence forward log file records processed.
Current position=131-1.1015

Number of records written to capture files:

Capture file: capsamp.asc
Capture file options: FGA
Capture file -dset : CAPSAMP:@

Database CAPSAMP . . Inserts Updates Deletes Total
PARTS 2 0 0 2

Log records not copied to any capture file:

* No records skipped. All records copied to a capture file.

06-17-08 14:11:39 15641 Closed capture file capsamp.asc, #6

Note : only use an Ascii Capture File for safe-storing purposes. The lengths of some Eloquence numeric data types (such as P) may, when written to an Ascii Capture File, not match the Eloquence data type length for the source field. This is by design. Please see the Elocap README document section "ASCII Capture Files" for an explanation of EloCap's handling of such numeric data types in an ascii context.

List the Ascii Capture File transactions:

Either run the listMFTrans.wh script as described above, or

$ cat capsamp.asc

000000CAPSAMP PARTS 08061714:07:22IP0000000000000001 PN-00001 00001 150 175
000001CAPSAMP PARTS 08061714:07:22IP0000000000000002 PN-00002 00002 250 275

Determine query3k versions:

$ $ELOQUENCE_HOME/bin/query3k -versions

QUERY3K application revision:
B.07.10 (20060112)

Eloquence library revision:
IMAGE3K B.07.10.03
ELOQDB B.07.10.03

SORT:
Redstone SORT 2005-03-30

EloCap Header fields:

Reference-only, see EloCap product documentation for details.

                         YY        Date        YYYY Date
Field        Size        Offset    Size        Offset
SEQ          6           1         6           1
FILENAME     8           7         8           7
GROUPNAME    8           15        8           15
ACCTNAME     8           23        8           23
DSETNAME     16          31        16          31
TXDATE       6           47        8           47
TXTIME       8           53        8           55
TXTYPE       2           61        2           63
Size                     62                    64

The additional Extended Header information when -exthdr option is used:

Field        Size        Offset    Size        Offset
PROG         24          63        24          65
SESSION      8           87        8           89
USER         8           95        8           97
GROUP        8           103       8           105
ACCOUNT      8           111       8           113
JS           1           119       1           121
JSNUM        5           120       5           122

Size 124 126

Other fields:

Field        Size        Offset    Size        Offset
RECNUM       15          125       15          127
DBNAME       24          7         24          7
DBUSER       24          95        8           97

Note: DBNAME and DBUSER are alternate names for a concatenation of three other fields.

EloCap command line options that control header field generation:

By default the elocap process generates a Standard Header where the year portion of the TXDATE field is 2 bytes long (YY).

In order to generate additional header information, add one or more of the following options to the elocap command line.

-exthdr add extended header fields to the header

-recnum add the Eloquence record number to header

-yyyy use four-byte YYYY year in TXDATE

Based on the example that generates Message File with a Standard Header, in order to generate Message File with all available header fields simply add these three italicized options to the command line:

$ $ELOCAP_HOME/elocap \
-start 131 -synconly \
-cfg $ELOQUENCE_CONFIG_DIR/eloqdb6.cfg \
-stat capsamp.stat \
-pidfile capsamp.pid \
-fga -dset CAPSAMP:@ -exthdr -yyyy -recnum capsamp.msg \
-verbose -showskip -capstats

Note : the Eloquence record number is not a guaranteed unique identifier.

To identify the starting position within the stat file to be used by EloCap the next time it runs:

$ $ELOCAP_HOME/elocap \
-stat capsamp.stat \
-showstat -verbose

signature = ELOQ.IREPL01.01
byte order = 4321
charset = hp-roman8
volume release = 11
volume set id = 1b6c4133
next action = 131-1.306419

The next action value represents the forward-log starting point located in the file FwLog131-1.log.

This log spec is of the form:

gen[-seq[.tag]]
where
gen log generation
seq log sequence
tag log tag sequence

Warehouse connection to an Eloquence database:

By default the Eloquence database server listens on the Registered Port 8102.

This assignment is defined in the local Services file that is usually named /etc/services :

eloqdb 8102/tcp # Eloquence A.06.xx data base server

A Warehouse or Studio Open of an Eloquence database can be fully or partially-qualified, depending on whether the default port is implied. Hence the following Warehouse Open strings are identical in outcome if the Eloquence database instance is listening on port 8102 on system qax04/192.168.1.20 where the Warehouse Client is also running :

open db image capsamp
open db image :8102/capsamp
open db image 127.0.0.1:8102/capsamp
open db image localhost:8102/capsamp
open db image 192.168.1.20:8102/capsamp
open db image qax04.taurus.com:8102/capsamp

In order to open the capsamp database on an Eloquence instance listening on alternate port 8121, where the local Services file reads :

eloqdb2 8121/tcp # alternate Eloquence data base server

you can specify the instance identifier as :8121/capsamp in your Warehouse or Studio open string.

To alter the Warehouse lookup of Eloquence client library (HP-UX):

By default Warehouse looks to load a library named libimage3k.sl in the platform-specific sub-directory under /opt/eloquence6/lib/. The look-up target can be altered by modifying one or more of the following environmental variables, where the names and default values are :

WHIMAGEHOME: /opt/eloquence6/
WHIMAGEPATH: lib/
WHIMAGELIB: libimage3k.sl

For example, in order to load the following library:

/opt/eloquence/8.0/lib/pa20_32/libimage3k.sl

you would set a single environmental variable:

$ export WHIMAGEHOME=/opt/eloquence/8.0/

Warehouse appends the platform-dependent sub-directory name ( pa20_32 in this example ) to the WHIMAGEPATH based on its execution environment.

OPEN commands for accessing a capture file from a Warehouse script:

If the capture file is an ascii file:

OPEN TEXT filename MODE=r

Reading an ascii capture file is non-destructive.

If the capture file is a message file, to read and delete transactions:

OPEN FIXED filename MODE=r MSG

Reading a message file with mode=r MSG is destructive.

To read a message file without deleting the transactions:

OPEN FIXED filename MODE=rc MSG

Reading a message file MODE=rc MSG is non-destructive.

The c attribute in the mode will cause the transactions to be retained. This is useful for repetitive testing.

Eloquence environment variables:

The following environmental variables, if present, are consulted by the Eloquence client library:

EQ_DBSERVER: database server
EQ_DBUSER: database user
EQ_DBPASSWORD: database user password

For details on the alternate file: construct associated with EQ_DBUSER and EQ_DBPASSWORD, please see the Eloquence documentation.

The following environmental variable, if present, allows an Eloquence client to provide additional information to the Eloquence database server. This information will added to the forward-log audit information and can be used by EloCap:

EQ_AUDIT_INFO: application-specific information

For details on how EloCap can apply the EQ_AUDIT_INFO value to the EloCap Header, please see the README file in your EloCap distribution.

Transition to a new forward-log file:

The elocap process reads a forward-log using Eloquence's fwutil library calls. If the Eloquence log writer facility switches to a new forward-log, the fwutil library follows the switch without the need to restart elocap. This means that elocap continues to process transactions across physical file transitions without intervention.

For example, if the Eloquence dba has issued a dbtcl forwardlog restart command to switch to a new physical forward-log, elocap will be informed by the library when a read operation has crossed a physical log file boundary. elocap notes this event with an informational message:

1. elocap is launched and begins processing the forward-log named FwLog131-1.log:

06-17-08 10:03:45 17541 Opened pid file capsamp.pid, #3
06-17-08 10:03:45 17541 Closed pid file capsamp.pid, #3
R1: processing forward-log file: '/opt/eloquence6/taurus/fwlogs/FwLog131-1.log'
06-17-08 10:03:45 17541 Opened capture file capsamp.asc, #6
R1: replication is up-to-date until 2008-06-17 09:58:38

2. At a later point, a dbctl forwardlog restart command is issued. This command creates a new forward-log file, FwLog132-1.log. When elocap completes processing the FwLog131-1.log, the fwutil library informs it of its transition to the new physical file. elocap reports the event and continues processing entries :

R1: processing forward-log file: '/opt/eloquence6/taurus/fwlogs/FwLog132-1.log'

Work-flow persistence:

By default the elocap process waits for new forward-log entries to be written by Eloquence. Likewise the Warehouse incremental script waits for new Message File transactions to be written by EloCap. An empty input queue causes neither process to exit and require a restart.

Using the -dumprecs option:

The -dumprecs option causes EloCap to produce a hex output of raw records as these are read from the Eloquence forward-log files and written to the capture file. For example, given a set of three transactions, an insert followed by an update and a delete,

where the insert to the Eloquence PARTS table is:

PARTNO = "0000000000099999"

DESCRIPA = "PN-99999"

MATNUMBER = "99999"

PRICE1 = 260

PRICE2 = 220

and the subsequent update modifies the data in column DESCRIPA:

DESCRIPA = "ChangeU"

the hex output with all available header fields:

Insert log record length 94 (0x005e) for CAPSAMP.PARTS

0000: 30 30 30 30 30 30 30 30 30 30 30 39 39 39 39 39 0000 0000 0009 9999

0010: 20 20 20 20 20 20 20 20 20 20 50 4e 2d 39 39 39 PN -999

0020: 39 39 20 20 20 20 20 20 20 20 20 20 20 20 20 20 99

0030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0040: 20 20 20 20 20 20 20 20 39 39 39 39 39 20 20 20 9999 9

0050: 20 20 20 20 20 20 20 20 20 20 01 04 00 dc .. ..

Writing capture record length 156 (0x009c) to capsamp.msg

0000: 30 30 30 30 31 38 43 41 50 53 41 4d 50 20 20 20 0000 18CA PSAM P

0010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 50 41 PA

0020: 52 54 53 20 20 20 20 20 20 20 20 20 20 20 31 30 RTS 10

0030: 31 30 32 37 30 39 3a 32 39 3a 35 32 49 50 30 30 1027 09:2 9:52 IP00

0040: 30 30 30 30 30 30 30 30 30 39 39 39 39 39 20 20 0000 0000 0999 99

0050: 20 20 20 20 20 20 20 20 50 4e 2d 39 39 39 39 39 PN-9 9999

0060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0080: 20 20 20 20 20 20 39 39 39 39 39 20 20 20 20 20 99 999

0090: 20 20 20 20 20 20 20 20 01 04 00 dc ....

Update log record length 94 (0x005e) (Before) for CAPSAMP.PARTS

0000: 30 30 30 30 30 30 30 30 30 30 30 39 39 39 39 39 0000 0000 0009 9999

0010: 20 20 20 20 20 20 20 20 20 20 50 4e 2d 39 39 39 PN -999

0020: 39 39 20 20 20 20 20 20 20 20 20 20 20 20 20 20 99

0030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0040: 20 20 20 20 20 20 20 20 39 39 39 39 39 20 20 20 9999 9

0050: 20 20 20 20 20 20 20 20 20 20 01 04 00 dc .. ..

Update log record length 94 (0x005e) (After) for CAPSAMP.PARTS

0000: 30 30 30 30 30 30 30 30 30 30 30 39 39 39 39 39 0000 0000 0009 9999

0010: 20 20 20 20 20 20 20 20 20 20 43 68 61 6e 67 65 Ch ange

0020: 64 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 dU

0030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0040: 20 20 20 20 20 20 20 20 39 39 39 39 39 20 20 20 9999 9

0050: 20 20 20 20 20 20 20 20 20 20 01 04 00 dc .. ..

Writing capture record length 250 (0x00fa) to capsamp.msg

0000: 30 30 30 30 31 39 43 41 50 53 41 4d 50 20 20 20 0000 19CA PSAM P

0010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 50 41 PA

0020: 52 54 53 20 20 20 20 20 20 20 20 20 20 20 31 30 RTS 10

0030: 31 30 32 37 30 39 3a 32 39 3a 35 32 49 55 30 30 1027 09:2 9:52 IU00

0040: 30 30 30 30 30 30 30 30 30 39 39 39 39 39 20 20 0000 0000 0999 99

0050: 20 20 20 20 20 20 20 20 50 4e 2d 39 39 39 39 39 PN-9 9999

0060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0080: 20 20 20 20 20 20 39 39 39 39 39 20 20 20 20 20 99 999

0090: 20 20 20 20 20 20 20 20 01 04 00 dc 30 30 30 30 .... 0000

00a0: 30 30 30 30 30 30 30 39 39 39 39 39 20 20 20 20 0000 0009 9999

00b0: 20 20 20 20 20 20 43 68 61 6e 67 65 64 55 20 20 Ch ange dU

00c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

00d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

00e0: 20 20 20 20 39 39 39 39 39 20 20 20 20 20 20 20 9999 9

00f0: 20 20 20 20 20 20 01 04 00 dc .. ..

Delete log record length 94 (0x005e) for CAPSAMP.PARTS

0000: 30 30 30 30 30 30 30 30 30 30 30 39 39 39 39 39 0000 0000 0009 9999

0010: 20 20 20 20 20 20 20 20 20 20 43 68 61 6e 67 65 Ch ange

0020: 64 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 dU

0030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0040: 20 20 20 20 20 20 20 20 39 39 39 39 39 20 20 20 9999 9

0050: 20 20 20 20 20 20 20 20 20 20 01 04 00 dc .. ..

Writing capture record length 156 (0x009c) to capsamp.msg

0000: 30 30 30 30 32 30 43 41 50 53 41 4d 50 20 20 20 0000 20CA PSAM P

0010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 50 41 PA

0020: 52 54 53 20 20 20 20 20 20 20 20 20 20 20 31 30 RTS 10

0030: 31 30 32 37 30 39 3a 32 39 3a 35 32 49 44 30 30 1027 09:2 9:52 ID00

0040: 30 30 30 30 30 30 30 30 30 39 39 39 39 39 20 20 0000 0000 0999 99

0050: 20 20 20 20 20 20 20 20 43 68 61 6e 67 65 64 55 Chan gedU

0060: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20

0080: 20 20 20 20 20 20 39 39 39 39 39 20 20 20 20 20 99 999

0090: 20 20 20 20 20 20 20 20 01 04 00 dc ....